API integration

Build your own custom checkout experience using our API integration.


With our online payments API integration, you'll be able to accept more than 250+ different payment methods, while maintaining full control over the UI and user experience.

For many local payment methods and 3D Secure, you'll need to redirect the shopper to the payment method's website so they can complete the payment.

To accept online payments, you'll need an integration that can:

  1. Get a list of payment methods available to the shopper.
  2. Collect the shopper's payment details.
  3. Make a payment.
  4. Redirect the shopper to complete the payment.
  5. Present the payment result to the shopper.

We also recommend that you test your integration before you start accepting live payments.

Before you begin

Before you start integrating with our online payments API, make sure that you have performed the following steps:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup
  2. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
  3. Install one of our Libraries to connect with the Adyen APIs.

For more information on these steps, refer to Get started with Adyen.

Step 1: Get available payment methods

First, you need to present a list of available payment methods to your shopper. Retrieve a list with a /paymentMethods call, providing the name of your merchantAccountAlso specify the shopper'countryCode, and the currency and value of the payment. We'll use this to tailor the payment method list to your shopper.

curl https://checkout-test.adyen.com/v40/paymentMethods \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "merchantAccount": "YourMerchantAccount",
  "countryCode": "NL",
  "amount": {
    "currency": "EUR",
    "value": 1000
  }
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.checkout.payment_methods({
  :merchantAccount => 'YourMerchantAccount',
  :countryCode => 'NL',
  :amount => {
    :currency => 'EUR',
    :value => 1000
  }
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest();
paymentMethodsRequest.setMerchantAccount("YourMerchantAccount");
paymentMethodsRequest.setCountryCode("NL");
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1000L);
paymentMethodsRequest.setAmount(amount);
PaymentMethodsResponse response = checkout.paymentMethods(paymentMethodsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "merchantAccount" => "YourMerchantAccount",
  "countryCode" => "NL",
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
);
$result = $service->paymentMethods($params);

A list of available paymentMethods will be returned in the response. Each payment method will have a name, which you can display to your shopper in your payments form. It will also have a type. Pass this back to indicate the shopper's chosen payment method when you make the payment

Additionally, every payment method will have a details array that indicates what you need to collect from the shopper. Each object in details has a key that represents the field you need to collect, and a type, such as text, number, or for a list, select.

In the example below, there are two paymentMethods you can present to the shopper: Credit Card and SEPA Direct Debit . If the shopper chose to pay with SEPA Direct Debit, you'd need to collect their sepa.ownerName (the name on their bank account) and sepa.ibanNumber (the IBAN number of their account) using text fields presented in your payments form.

/paymentMethods response
{
  "paymentMethods":[
    {
      "details":[{
          "key":"encryptedCardNumber",
          "type":"cardToken"
        },{
          "key":"encryptedExpiryMonth",
          "type":"cardToken"
        },{
          "key":"encryptedExpiryYear",
          "type":"cardToken"
        },{
          "key":"encryptedSecurityCode",
          "type":"cardToken"
        }
      ],
      "name":"Credit Card",
      "type":"scheme"
    },{
      "details":[{
          "key":"sepa.ownerName",
          "type":"text"
        },{
          "key":"sepa.ibanNumber",
          "type":"text"
        }
      ],
      "name":"SEPA Direct Debit",
      "type":"sepadirectdebit"
    }
  ]
}

Step 2: Collect shopper details

You can use the result you received from /paymentMethods to dynamically determine what information you need to collect from the shopper via your payments form. Alternatively, you can hard-code these fields into your payments form.  

For most payment methods, you can collect the payment details directly from the shopper. For credit cards, however, you will need to encrypt any sensitive credit card details.

Are you PCI Level 1 or 2 certified? You can optionally submit raw card data. See Collecting raw card data for more information.

Encrypt credit card details 

Secured Fields is our JavaScript library that you can use to securely collect your shopper's credit card details without sensitive credit card data touching your server. When the shopper enters their card details on your website, Secured Fields collects the sensitive data, and creates an encrypted version that you can safely transmit to Adyen. 

Integrating Secured Fields is a two-step process:

  1. Generate Origin Key
    Secured Fields require an Origin Key, a unique key that is tied to the domain of your website. You need one Origin Key per domain. You can generate an Origin Key in your Customer Area

    1. Go to Account > Users, and click on the ws@Company.[YourCompanyAccount] user.

    2. Under Origin key, enter your website's domain and click Generate Origin Key.

      For the domain, use a concatenation of the protocol, host, and port. Do not include subdirectories or a trailing slash. For example, https://your-company.com or https://checkout.your-company.com:8080.

    3. Copy your Origin Key and securely store in your system – this is required to use Secured Fields.

    If you have multiple domains, you will need to generate an Origin Key for each domain.

  2. Add Secured Fields to payments form 

    First, embed the Secured Fields library in your payments page by including the following script in the <head>

    <script type="text/javascript" src="https://checkoutshopper-test.adyen.com/checkoutshopper/assets/js/sdk/checkoutSecuredFields.1.3.0.min.js"></script>

    Collect sensitive card data from your shopper by inserting data-cse elements into a <div> in the <body> of your payments page. These render as iframes, where the shopper can enter their card details. You'll need to add an encryptedCardNumber, encryptedExpiryMonthencryptedExpiryYear, and encryptedSecurityCode

    <div class="cards-div">
    
        <div class="js-chckt-pm__pm-holder">
           <input type="hidden" name="txvariant" value="card" />
           <label>
               <span class="input-field" data-cse="encryptedCardNumber" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryMonth" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedExpiryYear" />
           </label>
           <label>
               <span class="input-field" data-cse="encryptedSecurityCode" />
           </label>
        </div>
    </div>

    Finally, add the following code to the bottom of the <body>. Replace the [ORIGIN KEY] with the Origin Key you generated earlier.

    <script type="text/javascript">
    var securedFields = csf(
        {
            configObject : {
                originKey : "[ORIGIN KEY]"
            },
            rootNode: '.cards-div'
        }
    );
    </script>

    The Secured Fields will perform validation on the card details as they are entered by the shopper. When the shopper submits the payment, their card details are replaced by encrypted values. These are added to hidden <input> fields in the <div> that holds the data-cse elements. 

    <div id="pmHolder" class="js-chckt-pm__pm-holder">
    	<input type="hidden" name="txvariant" value="card">
            ...        
    	<input type="hidden" name="encryptedExpiryMonth" id="card-encrypted-month" value="adyenjs_0_1_21$Y2vHlRIynd...">
    	...
    </div>

    Loop through and collect the encrypted card details from the corresponding data-cse values. You'll use these to make the payment.

Step 3: Make a payment

Tokenized payments

If you have a subscription or recurring business model, we recommend using our tokenization service. See Recurring and subscription payments for details.

After you've collected payment details from the shopper, initiate a payment with a  /payments API call. Specify the shopper's chosen payment method using the  type, and include the information you collected from the shopper in the  paymentMethod object. You'll also need to include the  amount, your own unique  reference for this payment, and a  returnUrl which will be used to redirect the shopper back to your payments page for payment methods that require a redirect.

The example below is for a card payment using details encrypted using Secured Fields.

curl https://checkout-test.adyen.com/v40/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"Your order number",
  "paymentMethod":{
    "type":"scheme",
    "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  "returnUrl":"https://your-company.com/checkout/",
  "merchantAccount":"YourMerchantAccount"
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"
 
response = adyen.checkout.payments({
  :amount => {
    :currency => "EUR",
    :value => 1000
  },
  :reference => "Your order number",
  :paymentMethod => {
    :type => "scheme",
    :encryptedCardNumber => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryMonth => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryYear => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedSecurityCode => "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  :returnUrl => "https://your-company.com/checkout/",
  :merchantAccount => "YourMerchantAccount"
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);
 
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
Amount amount = new Amount();
amount.setCurrency("USD");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
paymentsRequest.setReference("Your order number");
paymentsRequest.setPaymentMethod(new HashMap<String, String>());
paymentsRequest.putPaymentMethodItem("type", "scheme");
paymentsRequest.putPaymentMethodItem("encryptedCardNumber", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedExpiryMonth", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedExpiryYear", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedSecurityCode", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.setReturnUrl("https://your-company.com/...");
paymentsRequest.setMerchantAccount("YourMerchantAccount");
PaymentsResponse response = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "reference" => "Your order number",
  "paymentMethod" => array(
    "type" => "scheme",
    "encryptedCardNumber" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode" => "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  ),
  "returnUrl" => "https://your-company.com/checkout/",
  "merchantAccount" => "YourMerchantAccount"
);
$result = $service->payments($params);

If the payment was successful you'll receive an Authorised resultCode and a pspReference, which is our unique identifier for the transaction. If you've set up notifications you'll also receive a successful AUTHORISATION notification. You can immediately present the payment result to the shopper.

Authorised /payments response
{
  "pspReference": "88154795347618C",
  "resultCode": "Authorised"
}

For many payment methods, you'll receive a redirectShopper resultCode instead. This means you'll need to redirect the shopper to complete the payment. 

Step 4: Redirect shopper

For some local payment methods, such as iDEAL, or card payments with 3D Secure, you'll need to redirect the shopper to a webpage or app to verify the payment.

When you make a payment with these methods you'll receive a RedirectShopper resultCode. You'll also receive a redirect object containing a url. Redirect the shopper to this address to verify the payment. 

For 3D Secure payments, you'll need to POST additional fields when you redirect the shopper and when you complete the payment. See 3D Secure for more information.

Redirect /payments response
{
  "resultCode":"RedirectShopper",
  "details":[
    {
      "key":"payload",
      "type":"text"
    }
  ],
  "redirect":{
    "method":"GET",
    "url":"https://test.adyen.com/hpp/redirectIdeal.shtml?brandCode=ideal&currencyCode=EUR&issuerId=0721&merchantAccount=YourMerchantAccount&merchantReference=Your+order+number&merchantSig=Az62YcY..."
  }
}

Complete the redirect payment

Once the shopper has verified the payment, they are redirected back to your website or app using the returnUrl you provided earlier. This will be appended with a payload:

https://your-company.com/checkout/?payload=sdfsdfsdf...&type=complete&resultCode=authorised

Submit the payload to the /payments/details endpoint to complete the redirect.

curl https://checkout-test.adyen.com/v40/payments/details \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "details":{
    "payload":"sdfsdfsdf..."
  }
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.checkout.payments.details({
  :details => {
    :payload => "sdfsdfsdf..."
  }
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
PaymentDetailsRequest paymentDetailsRequest = new PaymentDetailsRequest();
HashMap<String, String> details = new HashMap<>();
details.put("payload", "sdfsdfsdf...");
paymentsDetailsRequest.setDetails(details);
PaymentsResponse paymentsResponse = checkout.paymentDetails(PaymentDetailsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "details" => array(
    "payload" => "sdfsdfsdf..."
  )
);
$result = $service->paymentDetails($params);

If the payment was successful you'll receive an Authorised resultCode and a pspReference, which is our unique identifier for the transaction. If you've set up notifications you'll also receive a successful AUTHORISATION notification. 

Next up, let's find out how you can present the payment result to the shopper.

Step 5: Present payment result

When a payment is completed you'll receive a resultCode. You can use this to present the shopper with the result of the payment via your website or app. To find out more about the resultCodes you can receive and how you can action them, see Result codes.

Next, let's look at how you can test your integration.

Testing your integration

Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the status of a test payment in your Customer Area, under TransactionsPayments.

When you've completed testing, there are some additional steps you'll need to complete before you can accept live payments from shoppers. Refer to Getting started with Adyen for more information.

Multiple Origin Keys

When you're securely collecting card details with Secured Fields, you'll need an Origin Key for each domain where you are using Secured Fields. You can generate a key for each domain in your Customer Area. If you have many domains and generating them by hand is unreasonable, you can use our /originKeys call.

We'll return originKeys for each of the originDomains that you specify.

For the domain, use a concatenation of the protocol, host, and port. Do not include subdirectories or a trailing slash. For example, https://your-company.com or https://checkout.your-company.com:8080.

curl https://checkout-test.adyen.com/v40/originKeys \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
   "originDomains":[
      "https://www.your-company1.com",
      "https://www.your-company2.com",
      "https://www.your-company3.com"
   ]
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.checkout_utility.origin_keys({
   :originDomains => [
      "https://www.your-company1.com",
      "https://www.your-company2.com",
      "https://www.your-company3.com"
   ]
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);
 
CheckoutUtility checkoutUtility = new CheckoutUtility(client);
OriginKeysRequest originKeysRequest = new OriginKeysRequest();
originKeysRequest.setOriginDomains(new ArrayList<String>(Arrays.asList(
    "https://www.your-company1.com",
    "https://www.your-company2.com",
    "https://www.your-company3.com")
));
OriginKeysResponse originKeysResponse = checkoutUtility.originKeys(originKeysRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\CheckoutUtility($client);

$params = array(
    "originDomains" => array(
        "https://www.your-domain1.com",
        "https://www.your-domain2.com",
        "https://www.your-domain3.com"
    )
);

$result = $service->originKeys($params);
/originKeys response
{
   "originKeys":{
      "https://www.your-company1.com":"pub.v2.99...",
      "https://www.your-company2.com":"pub.v2.99...",
      "https://www.your-company3.com":"pub.v2.99..."
   }
}

Recurring and subscription payments

If you have a subscription or recurring business model we recommend using our tokenization service.

You can tokenize the shopper's payment details when you make the payment. To do this, additionally pass paymentMethod.storeDetails as true. Also include a shopperReference, which is an id provided by you that will act as the container for the shopper's tokenized payment details. It will be stored when the token is created.

curl https://checkout-test.adyen.com/v40/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"Your order number",
  "paymentMethod":{
    "type":"scheme",
    "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "storeDetails":true
  },
  "shopperReference":"YourUniqueIdForTheShopper",
  "returnUrl":"https://your-company.com/checkout/",
  "merchantAccount":"YourMerchantAccount"
}'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.checkout.payments({
  :amount => array(
    :currency => "EUR",
    :value => 1000
  ),
  :reference => "Your order number",
  :paymentMethod => {
    :type => "scheme",
    :encryptedCardNumber => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryMonth => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedExpiryYear => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedSecurityCode => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :storeDetails => true
  },
  :shopperReference => "YourUniqueIdForTheShopper"
  :returnUrl => "https =>//your-company.com/checkout/",
  :merchantAccount => "YourMerchantAccount"
}) 
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
Amount amount = new Amount();
amount.setCurrency("USD");
amount.setValue(1000L);
paymentsRequest.setReference("Your order number");
paymentsRequest.setAmount(amount);
paymentsRequest.setPaymentMethod(new HashMap<String, String>());
paymentsRequest.putPaymentMethodItem("type", "scheme");
paymentsRequest.putPaymentMethodItem("encryptedCardNumber", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedExpiryMonth", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedExpiryYear", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("encryptedSecurityCode", "adyenjs_0_1_18$MT6ppy0FAMVMLH...");
paymentsRequest.putPaymentMethodItem("storeDetails", "true");
paymentsRequest.setShopperReference("YourUniqueIdForTheShopper");
paymentsRequest.setReturnUrl("https://your-company.com/...");
paymentsRequest.setMerchantAccount("YourMerchantAccount");
PaymentsResponse response = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "reference" => "Your order number",
  "paymentMethod" => array(
    "type" => "scheme",
    "encryptedCardNumber" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "storeDetails" => true
  ),
  "shopperReference" => "YourUniqueIdForTheShopper",
  "returnUrl" => "https://your-company.com/checkout/",
  "merchantAccount" => "YourMerchantAccount"
);
$result = $service->payments($params); 

If the payment is successful, the resultCode will be Authorised, the payment details will be tokenized, and a recurringDetailReference will be returned in the response. Save the recurringDetailReference, you will use this and your shopperReference to make future payments. For more information, see Making payments with tokens.

Next steps

Set up notifications

Receive confirmation when a payment is authorised or fails.

link

Payment modifications

Find out how to cancel, refund, or capture a payment using our API.

link