No momento, esta página não está disponível em português
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 use Adyen's Apple Pay certificate if you have a web integration, which makes it quicker to set up Apple Pay. If you have a mobile integration, use your own Apple Developer account and certificate which requires extra configuration steps:

Set up Apple Pay

Enable Apple Pay with your own or Adyen's Apple Pay 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. You can download logos for Apple Pay which you can use on your payment form.

When the shopper selects Apple Pay, they are presented with a prompt to verify the payment using Touch ID or Face ID. 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.

  1. Make a /paymentMethods request, 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.
  2. In the response, you receive:

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

Complete the Apple Pay session validation

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

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

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

    Parameters Required Description
    displayName -white_check_mark- The value of the configuration.merchantName field from the /paymentMethods response.
    domainName -white_check_mark- The domain name you provided when you added Apple Pay in your Customer Area. This has to match the window.location.hostname of the web shop.
    merchantIdentifier -white_check_mark- The value of configuration.merchantId field from the /paymentMethods response.
  2. Decode the base64-encoded data object you get in the response:

  3. Pass the decoded data as an object to the completeMerchantValidation method to complete the Apple Pay session validation.

The Apple Pay session data expires after five minutes, so make sure you complete the Apple Pay session validation within this time.

If the Apple Pay session is successfully validated, Apple Pay prompts the shopper to authorize the payment using Touch ID or Face ID.

Make a payment

  1. After the shopper authorizes the payment, get the token from the Apple Pay framework and decrypt it in one of two ways:

  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. 

    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, first create a shopper token and then make subsequent recurring transactions with the token.

Test and go live

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

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, including subdomains, under the following path:

    /.well-known/apple-developer-merchantid-domain-association

    The file must:

    • Have Content-Type: text/plain in the header.
    • Be externally accessible.
    • Not be password protected.
    • Not be behind a proxy or redirect.
    • Be hosted with the Unix line ending.

    See an example of a working domain association file.

  3. Configure your firewall's allow-list:

    We do not provide a list of IP addresses for allow-listing, because over time the list may change for various reasons, for example, due to ISP configuration changes.

    If you are unable to configure your firewall with a domain allow-list, attempt to resolve our IP addresses by performing a DNS lookup on out.adyen.com, and then add those IP addresses to your allow-list. Beware that you still run the risk of a disruption if the IP addresses change.

  4. Add Apple Pay in your live Customer Area

    • You'll be asked for Shop websites: your website URLs, for example https://www.mystore.com. If you add more than one, separate them with a comma.

See also