Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Amazon Pay for API-only

Add Amazon Pay to an existing API-only integration.

These instructions explain how to add Amazon Pay to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.

Before you begin

Before starting your Amazon Pay integration:

  1. Make sure that you have set up your back end implementation.
  2. Add Amazon Pay in your test Customer Area.
  3. Register with Amazon for an Amazon Pay account.
  4. Follow the steps on Amazon Pay's documentation to integrate with Amazon Pay.

Build your payment form for Amazon Pay

Show Amazon Pay as an available payment method in countries where Amazon Pay is supported. When the shopper selects Amazon Pay, they are presented with the payment form.

We provide logos for Amazon Pay which you can use on your payment form. For more information, refer to Downloading logos.

You can also submit a /paymentMethods request specifying:

  • countryCode: Country where Amazon Pay is supported. For example, NL.
  • amount.currency: You can only accept payments in the currency that you used when you registered with Amazon Pay. For example, EUR.

In the response, you receive paymentMethod.type: amazonpay.

/paymentMethods response 
{
    "details": [
        {
            "key": "amazonPayToken",
            "type": "text"
        }
    ],
    "name": "Amazon Pay",
    "type": "amazonpay",
    "configuration": {
            "merchantId": "YOUR_AMAZON_PAY_MERCHANT_ID",
            "publicKeyId": "YOUR_AMAZON_PAY_PUBLIC_KEY_ID",
            "storeId": "YOUR_AMAZON_PAY_STORE_ID"
        }
}

Make a payment

Refer to Amazon Pay's documentation to integrate with Amazon Pay.

  1. Start a checkout session and follow all subsequent steps as described in Amazon Pay’s documentation.
  2. Make a Get Checkout Session call to get the  amazonPayToken from the response.

  3. From your server, make a /payments request, providing:

    • paymentMethod.type: amazonpay
    • paymentMethod.amazonPayToken: This is the amazonPayToken that you obtained from the Get Checkout Session response.

    The /payments request is the step to "Process payment with your acquirer" in Amazon Pay's documentation.

curl https://checkout-test.adyen.com/v66/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "amazonpay",
    "amazonPayToken":"160583287597AMZN"
  },
  "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy..",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}'
# 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 => "amazonpay",
    :amazonPayToken => "160583287597AMZN"
  },
  :returnUrl => "https://your-company.com/checkout?shopperOrder=12xy..",
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})
// 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" => "amazonpay",
    "amazonPayToken" => "160583287597AMZN"
  ),
  "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);
#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
   'amount': {
      'value': 1000,
      'currency': 'EUR'
   },
   'reference': 'YOUR_ORDER_NUMBER',
   'paymentMethod': {
      'type': 'amazonpay',
      'amazonPayToken': '160583287597AMZN'
   },
   'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
   'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    amount: { currency: "EUR", value: 1000 },
    paymentMethod: {
        type: 'amazonpay',
        amazonPayToken: '160583287597AMZN'
    },
    reference: "YOUR_ORDER_NUMBER",
    merchantAccount: config.merchantAccount,
    returnUrl: "adyencheckout://your.package.name"
}).then(res => res);

The /payments response contains:

  • pspReference: Adyen's unique reference for the payment.
  • resultCode: Authorised
/payments response 
{
   "pspReference": "881539337151149C",
   "resultCode": "Authorised"
}

You can also enable 3D Secure as a part of the checkout process. However, the 3D Secure flow is handled outside of the Amazon Pay checkout flow. If the shopper uses a card that requires 3D Secure authentication before the payment can be completed, you receive an action.type redirect in the response.

/payments response for a card that requires 3D Secure authentication 
{
   "resultCode":"RedirectShopper",
   "action":{
      "data":{
         "MD":"NGNsQ2QzN3hxMGtVN2lueUV5QWo3UT..",
         "PaReq":"eNpVUttygjAQ/RXrB5CES1..",
         "TermUrl":"https://your-company.com/checkout?shopperOrder=12xy.."
      },
      "method":"POST",
      "paymentData":"Ab02b4c0!BQABAgA2ndtJW6...==",
      "paymentMethodType":"scheme",
      "type":"redirect",
      "url":"https://test.adyen.com/hpp/3d/validate.shtml"
   },
   "details":[
      {
         "key":"MD",
         "type":"text"
      },
      {
         "key":"PaRes",
         "type":"text"
      }
   ],
   ...
}
  1. If you received an action object, use the information in this object to redirect the shopper to another website to complete the 3D Secure authentication. Otherwise, proceed to presenting the payment result to your shopper.

Cards with 3D Secure. Handle the redirect

If the shopper used a card that requires 3D Secure authentication, you need to redirect the shopper to another website where they complete the authentication. To redirect the shopper for 3D Secure authentication:

  1. Get the action.url and the action.method from the /payments response.
  2. Redirect the shopper to the specified url using the HTTP POST, and include the contents of the data object in the request. For example: 
    curl https://test.adyen.com/hpp/3d/validate.shtml \
--data-urlencode 'PaReq=eNpVUttygjAQ/RXbDyAXBYRZ00HpTH3wUosPfe...' \
--data-urlencode 'TermUrl=https://example.com/checkout?shopperOrder=12xy..' \
--data-urlencode 'MD=OEVudmZVMUlkWjd0MDNwUWs2bmhSdz09...'
    The shopper is redirected to the issuer page to complete the 3D Secure authentication. In the test environment, this is the page: https://test.adyen.com/hpp/3d/validate.shtml, and you perform the authentication using the 3D Secure test credentials:
    • Username: user
    • Password: password
    After completing the 3D Secure authentication, the shopper is redirected back to your returnUrl with the same HTTP method. This will be appended with the MD and PaRes variables. 
        POST / HTTP/1.1
    Host: www.your-company.com/checkout?shopperOrder=12xy..
    Content-Type: application/x-www-form-urlencoded
    MD=Ab02b4c0%21BQABAgCW5sxB4e%2F%3D%3D..&PaRes=eNrNV0mTo7gS..
  3. URL-decode the MD and PaRes parameters, and pass the parameters to your server.
  4. From your server, make a /payments/details request, specifying:
    • paymentData: Value that you received in the /payments response.
    • details: Object that contains the URL-decoded MD and PaRes parameters.
    curl https://checkout-test.adyen.com/v66/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
     "paymentData":"Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...",
     "details":{
       "MD":"Ab02b4c0!BQABAgCW5sxB4e/==",
       "PaRes":"eNrNV0mTo7gS.."
     }
}'
    # 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({
  :paymentData => 'Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...',
  :details => {
        :MD => 'Ab02b4c0!BQABAgCW5sxB4e/==..',
        :PaRes => 'eNrNV0mTo7gS..'
  }
})
    // Set your X-API-KEY with the API key from the Customer Area.
Client client = new Client(xApiKey,Environment.TEST);

Checkout checkout = new Checkout(client);
PaymentsDetailsRequest paymentsDetailsRequest = new PaymentsDetailsRequest();
HashMap<String, String> details = new HashMap<>();
details.put("MD", "Ab02b4c0!BQABAgCW5sxB4e/==");
details.put("PaRes", "eNrNV0mTo7gS..");
paymentsDetailsRequest.setDetails(details);
paymentsDetailsRequest.setPaymentData("Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...");
PaymentsResponse paymentsResponse = checkout.paymentsDetails(paymentsDetailsRequest);
    // 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(
  "paymentData" => "Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...",
  "details" => array(
    "MD" => "Ab02b4c0!BQABAgCW5sxB4e/==",
    "PaRes" => "eNrNV0mTo7gS.."
  )
);
$result = $service->paymentsDetails($params);
    #Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments_details({
   'paymentData' : 'Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...',
   'details': {
      'MD': 'Ab02b4c0!BQABAgCW5sxB4e/==',
      'PaRes': "eNrNV0mTo7gS.."
   }
})
    // Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);
string paymentData = "Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...";
var details = new Dictionary<string, string>
{
  { "MD", "Ab02b4c0!BQABAgCW5sxB4e/==" },
  {"PaRes", "eNrNV0mTo7gS.."}
};
var paymentsDetailsRequest = new Model.Checkout.PaymentsDetailsRequest(Details: details, PaymentData: paymentData);
var paymentResponse = checkout.PaymentDetails(paymentsDetailsRequest);
    const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.paymentsDetails({
    details: { MD: "Ab02b4c0!BQABAgCW5sxB4e/==", PaRes: "eNrNV0mTo7gS.." },
    paymentData: "Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...",
}).then(res => res);
    import (
    "github.com/adyen/adyen-go-api-library/v2/src/checkout"
    "github.com/adyen/adyen-go-api-library/v2/src/common"
    "github.com/adyen/adyen-go-api-library/v2/src/adyen"
)

// Set your X-API-KEY with the API key from the Customer Area.
client := adyen.NewClient(&common.Config{
    ApiKey:      "[API_KEY]",
    Environment: common.TestEnv,
})

res, httpRes, err := client.Checkout.PaymentsDetails(&checkout.DetailsRequest{
    PaymentData: "Ab02b4c0!BQABAgAKspbjN8+5...",
    Details: map[string]interface{}{
        "MD": "Ab02b4c0!BQABAgCW5sxB4e/==",
        "PaRes": "eNrNV0mTo7gS..",
    },
})
    The response contains:
    /payments/details response 
      {
   "resultCode": "Authorised",
   "pspReference": "88154795347618C"
 }

Present the payment result

Use the resultCode that you received in the /payments or /payments/details response to present the payment result to your shopper.

The resultCode values you can receive for Amazon Pay are:

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
If you are using manual capture, you also need to capture the payment.
Cancelled The shopper cancelled the payment. Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
Error There was an error when the payment was being processed. For more information, check the refusalReason field. Inform the shopper that there was an error processing their payment.
Refused The payment was refused. For more information, check the refusalReason field. Redirect the shopper back to the payment page and ask them to try the payment again using a different card. For more information on how to do this, check Amazon Pay's documentation.
Additional resultCode values are possible in case of the 3D Secure authentication flow. For more information, refer to Result codes.

Test and go live

To test Amazon Pay, you must follow the Amazon Pay testing guidelines.
You can check the status of an Amazon Pay test payment in your Customer Area > Transactions > Payments.

Before you can accept live Amazon Pay payments, you need to submit a request for Amazon Pay in your live Customer Area.

For more information, see Amazon Pay's test environment setup.

See also