Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Apple Pay for API only

Add Apple Pay to an existing API-only integration.

Accept Apple Pay payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

Before you begin

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

You can either use Adyen's Apple Pay certificate which makes it quicker to set up Apple Pay, or you can also use your own Apple Developer account and certificate which requires extra configuration steps:

  1. Set up your back end implementation.
  2. Set up your server for secure communication with Apple Pay.
  3. Add Apple Pay in your test Customer Area, where you'll be asked for:
    • Shop website: your main website URL, for example https://www.mystore.com.
    • Additional shop websites: Optional. Add any other domains you use for your shop website, for example https://www.mystore1.com, or https://www.mystore2.com.
  1. Set up your back end implementation.
  2. Set up your server for secure communication with Apple Pay.
  3. Contact Support Team to enable Apple Pay for your account, and provide the domain names and shop name that you want to use.
  4. Enable Apple Pay using your own Apple Developer account and certificate.

Build your payment form for Apple Pay

After you have finished enabling Apple Pay, you can show Apple Pay as an available payment method in countries where Apple Pay is supported. When the shopper selects Apple Pay, they are presented with a prompt to verify the payment using Touch ID or Face ID.

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

You can also submit a /paymentMethods request from your server, specifying:

  • countryCode: Country where Apple Pay is supported. For example, NL.
  • amount.currency: Any supported currency. For example, EUR.
  • channel: Set this to Web if the payment is being initiated from Safari, or iOS for in-app payments.

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

{
    "brands": [
        "amex",
        "mc"
    ],
    "configuration": {
        "merchantId": "com.test.merchant",
        "merchantName": "Your Store"
    },
    "details": [
        {
            "key": "applepay.token",
            "type": "applePayToken"
        }
    ],
    "name": "Apple Pay",
    "type": "applepay"
}

If the shopper is using a Mac without Touch ID, they will be prompted to verify the payment using an iPhone or Apple Watch registered to the same iCloud account.

Complete payment session validation

When the shopper selects to pay with Apple Pay, you get the onvalidatemerchant event handler. You then need to complete the validation of the payment session using the completeMerchantValidation method.

You can do this while using Adyen's Apple Pay certificate or you can also use your own:

  1. Make an /applePay/sessions call to retrieve the payment session for enabling Apple Pay, and include:

    Parameters Description
    displayName The name you want to display on the payment sheet. It's the value of the configuration.merchantName field form the response of the /paymentMethods call.
    domainName The domain name you provided when you contacted Support to enable Apple Pay for your account.
    merchantIdentifier The value of configuration.merchantId field from the response of the /paymentMethods call.
    /applePay/sessions request
    curl https://checkout-test.adyen.com/checkout/v64/applePay/sessions \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -d '{
      "displayName": "YOUR_MERCHANT_ACCOUNT",
      "domainName": "test.x.x-test.test-checkout.store",
      "merchantIdentifier": "xxxxxxxxxxxxxxx"
    }'
  2. Take the blob in the data object you get in the response and pass it to the completeMerchantValidation method to complete the payment session validation.

    /applePay/sessions response
    {
      "data": "BASE_64_DATA_BLOB"
    }
  1. Request an Apple Pay payment session from Apple.

  2. Use the Apple Pay session object from the response to complete payment session validation

Make a payment

  1. After the shopper authorizes the payment, get the token from the Apple Pay framework. For more information on how to retrieve this, refer to Custom web and Custom in-app integration pages.
  2. Stringify and base64 encode the entire paymentData object.
  3. From your server, make a /payments request providing:

    • paymentMethod.type: applepay
    • applePayToken: The stringified and base64 encoded paymentData you retrieved from the Apple framework. 
    curl https://checkout-test.adyen.com/v66/payments \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -d '{
      "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
      "reference":"YOUR_ORDER_NUMBER",
      "amount":{
        "currency":"EUR",
        "value":1000
      },
      "paymentMethod":{
        "type":"applepay",
        "applePayToken": "QWIwMmI0YzAhQlFBQkFnQjMv.."
      },
      "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy.."
    }'
    # 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 => "applepay",
        :applePayToken => "QWIwMmI0YzAhQlFBQkFnQjMv.."
      },
      :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.
    // Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
        Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
        Checkout checkout = new Checkout(client);
    
        PaymentsRequest paymentsRequest = new PaymentsRequest();
    
        String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
        paymentsRequest.setMerchantAccount(merchantAccount);
    
        Amount amount = new Amount();
        amount.setCurrency("EUR");
        amount.setValue(15000L);
        paymentsRequest.setAmount(amount);
    
        ApplePayDetails applePayDetails = new ApplePayDetails();
    
        applePayDetails.setApplePayToken(QWIwMmI0YzAhQlFBQkFnQjMv..);
        paymentsRequest.setPaymentMethod(applePayDetails);
    
        paymentsRequest.setReference("YOUR_ORDER_NUMBER");
        paymentsRequest.setReturnUrl("my-app://");
    
        PaymentsResponse paymentsResponse = 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" => "applepay",
        "applePayToken" => "QWIwMmI0YzAhQlFBQkFnQjMv.."
      ),
      "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': 'applepay',
          'applePayToken': 'QWIwMmI0YzAhQlFBQkFnQjMv..'
       },
       '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.
    var client = new Client ("YOUR_X-API-KEY", Environment.Test);
    var checkout = new Checkout(client);
    
    var amount = new Model.Checkout.Amount("EUR", 1000);
    var details = new Model.Checkout.DefaultPaymentMethodDetails{
      Type = "applepay",
      ApplePayToken = "QWIwMmI0YzAhQlFBQkFnQjMv.."
    };
    var paymentRequest = new Adyen.Model.Checkout.PaymentRequest
    {
      Reference = "YOUR_ORDER_NUMBER",
      Amount = amount,
      ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
      MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
      PaymentMethod = details
    };
    
    var paymentResponse = checkout.Payments(paymentsRequest);
    // Set your X-API-KEY with the API key from the Customer Area.
    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: 'applepay',
            applePayToken: 'QWIwMmI0YzAhQlFBQkFnQjMv..'
        },
        reference: "YOUR_ORDER_NUMBER",
        merchantAccount: config.merchantAccount,
        returnUrl: "https://your-company.com/checkout?shopperOrder=12xy.."
    }).then(res => res);

    The response contains the result of the payment.

    {
      "pspReference": "881539337151149C",
      "resultCode": "Authorised"
    }

Present the payment result

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

The resultCode values you can receive for Apple Pay are:

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
Refused The payment was refused by the shopper's bank. Ask the shopper to try the payment again using a different payment method.

Recurring payments

To make recurring Apple Pay payments, you first need to create a shopper token and then make subsequent recurring transactions with the token.

Refer to Tokenization for more information and detailed instructions.

Test and go live

Use Apple's test card numbers to test your integration.

Card Type Card number Expiry date CVC/CID
Discover 6011 0009 9446 2780 11/2022 111
Mastercard 5204 2477 5000 1471 11/2022 111
Visa 4761 1200 1000 0492 11/2022 533

For a full list of test cards and instructions how to add these to your test device, see Sandbox testing on Apple's Developer website.

Check the status of an Apple Pay test payment in your Customer Area > Transactions >  Payments.

Going live

To process live Apple Pay payments, your API credential needs to have the API Clientside Encryption Payments role. You can check this in your live Customer Area or ask your Admin user to verify.

Make sure you follow Apple's guidelines on:

Enable Apple Pay either using Adyen's Apple Pay certificate, which is quicker, or you can also use your own Apple Developer account and certificate which requires extra configuration steps:

  1. Download and unzip the domain association file.
  2. Host the domain association file with the name apple-developer-merchantid-domain-association on each domain you want to use, under the following path:

    /.well-known/apple-developer-merchantid-domain-association
  3. Add Apple Pay in your live Customer Area , where you'll be asked for:
    • Shop website: your main website URL, for example https://www.mystore.com.
    • Additional shop websites: Optional. Add any other domains you use for your shop website, for example https://www.mystore1.com, or https://www.mystore2.com.
  1. Contact Support Team to enable Apple Pay for your live account, and provide the domain names and shop name that you want to use.
  2. Enable Apple Pay on your Apple Pay Developer account for your live merchant identifier.

See also