Apple Pay

Learn how to accept Apple Pay payments.


For a list of countries where Apple Pay is available, see Countries and regions that support Apple Pay. For a list of Apple Pay compatible devices, see Apple Pay compatibility list. Apple Pay supports liability shift for Mastercard, American Express, Discover, but not Visa.

Adyen does not currently support China UnionPay (CUP) cards through Apple Pay.

Payment Type Payment flow Recurring Refunds Partial Refunds Captures Partial Captures Chargebacks
Wallet No Yes Yes Yes Yes Yes Yes

You can accept Apple Pay payments with:

Prerequisites

Before you can accept Apple Pay payments, you'll need to:

  1. Create and configure an Apple Development Account.
  2. Create a Merchant Identity Certificate.
  3. Create a Payment Processing Certificate and send this to Adyen.

If you want to accept Apple Pay on your website, you'll also need to validate your domain.

For more information, see Enable Apple Pay.

Integrate with iOS SDK

The Adyen Checkout SDK for iOS provides built-in support for Apple Pay. All you need to accept Apple Pay payments is to install the corresponding package from Adyen, and enable Apple Pay in your mobile app's settings.

Prerequisites

Refer to the iOS SDK integration for Checkout page to learn how to build a checkout integration. 

Step 1: Install the Apple Pay package

By default, Apple Pay is not included in the Adyen package you install from CocoaPods. To enable Apple Pay, add the Adyen/ApplePay package to your Podfile:

pod 'Adyen'
pod 'Adyen/ApplePay'

Make sure to install the package after you change the Podfile:  

$ pod install

Step 2: Configure Apple Pay in Xcode

Apple Pay API calls require your app to have the proper entitlements. To enable Apple Pay and obtain the entitlements for your app:  

  1. In Xcode, choose View > Navigators > Show Project Navigator.

  2. Choose the target from the Project/Targets pop-up menu (or in the Target section of the second sidebar if it appears).

  3. Click Capabilities to view app services you can add to your app.

  4. Enable the Apple Pay capability.

  5. Click the Add button (+) at the bottom of the Apple Pay Identifiers table.

  6. In the dialog that appears, enter your merchant ID and click OK.  

For more information, see Apple documentation.

Step 3: Display company name in the summary line

To show the total in a summary line, you must send us your company name.

  • Add the company object to the request:
{
   ...
   "company":{
      "name":"My Company"
   },
   ...
} 

If it's not included, the company name will default to the value in the reference field.

Step 4 (optional): Display line items before the summary line

You can display line items in Apple Pay, as shown below:  

  • Include line items in the paymentSession request, for example:
{
   ...
   "lineItems":[
      {
         "description":"Oversized Tweed Scarf",
         "amountIncludingTax":2400,
         "amountExcludingTax":1984,
         "taxAmount":416
      },
      {
         "description":"Leather Messenger Bag",
         "amountIncludingTax":5870,
         "amountExcludingTax":4851,
         "taxAmount":1019
      }
   ],
   ...
}


If the description is missing for any of the line items, none of the line items will be shown.  

To display the amounts with tax included, use the amountIncludingTax parameter.

To display the amounts with tax excluded, use the amountExcludingTax and taxAmount parameters. In this case, an extra line item will be displayed containing the tax total.

The SDK will always give preference to the amountIncludingTax parameter, unless it's missing in any of the line items, or the total for all items does not add up to the total in the amount object. In this case, the SDK will default to amountExcludingTax/taxAmount. If these are also missing, or do not add up, the line items will not be displayed.

Integrate with Web SDK

Prerequisites

Step 1: Provide a MerchantSession - Web SDK

You will need to create a new MerchantSession for every payment. You can do this by implementing the moreDetailsRequired hook.

In the moreDetailsRequired hook:

  1. You call your server with the pExtraData.url (the validationUrl).
  2. Your server calls the validationUrl (as described in Requesting an Apple Pay Payment Session) to request a session from Apple Pay.
  3. Your server receives a new MerchantSession.
  4. You resolve a Promise from the moreDetailsRequired hook with that MerchantSession

Example:

chckt.hooks.moreDetailsRequired = function(pExplanation, pExtraData) {
    return new Promise(function(resolve, reject) {
        // Call URL on Merchant server that provides a POST endpoint to obtain a Merchant Session for Apple Pay.
        // pExtraData.url is the validationURL from the ApplePayValidateMerchantEvent - an (apple.com) URL the merchant's
        // server must use to request an Apple Pay Payment Session
        // Upon proving to be a vaild merchant the response will contain an opaque Merchant Session object which
        // can be used to resolve the Promise created below
        // Merchant validation is always carried out server side rather than on the client for security reasons.

        var xhr = new XMLHttpRequest();

        xhr.open(
            "POST",
            "YOUR_SERVER_URL"
        );

        xhr.onload = function() {
            if (this.status >= 200 && this.status < 300) {
                resolve(JSON.parse(xhr.response));
            } else {
                reject({
                    status: this.status,
                    statusText: xhr.statusText
                });
            }
        };

        xhr.onerror = function() {
            reject({
                status: this.status,
                statusText: xhr.statusText
            });
        };

        xhr.setRequestHeader("Content-Type", "application/json");

        var params = JSON.stringify({ url: pExtraData.url });

        xhr.send(params);
    });
};

Step 2: Display company name in the summary line

To show the total in a summary line, you must send us your company name.

  • Add the company object to the request:
{
   ...
   "company":{
      "name":"My Company"
   },
   ...
}

Step 3 (optional): Display line items

You can also display line items before the summary, as shown below:

Include line items in the paymentSession request, for example:

{
   ...
   "lineItems":[
      {
         "description":"Oversized Tweed Scarf",
         "amountIncludingTax":2400,
         "amountExcludingTax":1984,
         "taxAmount":416
      },
      {
         "description":"Leather Messenger Bag",
         "amountIncludingTax":5870,
         "amountExcludingTax":4851,
         "taxAmount":1019
      }
   ],
   ...
}

If the description is missing for any of the line items, none of the line items will be shown.

To display the amounts with tax included, use the amountIncludingTax parameter.

To display the amounts with tax excluded, use the amountExcludingTax and taxAmount parameters. In this case, an extra line item will be displayed containing the tax total.

The SDK will always give preference to the amountIncludingTax parameter, unless it's missing in any of the line items, or the total for all items does not add up to the total in the amount object. In this case, the SDK will default to amountExcludingTax/taxAmount. If these are also missing, or do not add up, the line items will not be displayed.

Integrate with API

Before you begin this section, make sure you read and understand our API Integration guide.

In this section, we show how you use our API to integrate Apple Pay into your iOS app or website.

Step 1: Generate Apple Pay token

To generate an Apple Pay token, you can either:

Generate token with Apple Pay Component 

To add the Apple Pay Component to your payments form:

  1. Create a DOM element, placing it where you want the Apple Pay button to be rendered:

    <div id="applepay"></div>
  2. Create an instance of the Apple Pay Component, specifying:

    • currencyCodeThe three-character currency code.

    • amount

    • countryCode: The two-letter country code of your merchant account.

    • configuration.merchantNameThe merchant name that you want displayed on the Apple Pay payment sheet.

    • configuration.merchantIdentifier: Your Apple Merchant ID.

    • onValidateMerchant

    const appleNode = document.getElementById("applepay-field");
    const applepay = checkout.create("applepay", {
    
        currencyCode: "EUR",
        amount: 1000,
        countryCode: "DE",
        configuration: {
           merchantName: "Adyen Test merchant",
           merchantIdentifier: "adyen.test.merchant"
        },
        onValidateMerchant: (resolve, reject, validationURL) => {
            // Call the validation endpoint with validationURL.
            // Call resolve(MERCHANTSESSION) or reject() to complete merchant validation.
        },
        onChange: handleOnChange
    });
  3. Check whether Apple Pay is available to the shopper. If it is, mount the Component:

    applepay
        .isAvailable()
        .then(() => {
            applepay.mount("#applepay");
        })
        .catch(e => {
            // Apple Pay is not available
        });

    Do not mount the Component if Apple Pay is not available to the shopper.

  4. Create a function to listen to and handle the onChange event triggered by the Component:

    function handleOnChange(state, component) {
        state.isValid // true or false.
        state.data
        // { "type": "applepay", "applepay.token": "APPLEPAY_TOKEN" }
    }
  5. When state.isValid is true, collect the values passed in the state.data. You'll use these to make the payment.

To configure how the Apple Pay Component renders in your payment form, see Configuring the Component.

 

Generate token with your own payment form 

Call  /paymentMethods, specifying: 

  • countryCode: The shopper's locale, either: AUBRCACHDKESFIFRGBHKIEITNZSESG, or US.
  • amount
  • channel: Set this to Web if the payment is being initiated from Safari, or iOS for in-app payments.
{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "countryCode":"IE",
   "amount":{
      "currency":"EUR",
      "value":1000
   },
   "channel":"Web"
}


This returns a list of supported payment methods, including Apple Pay, and a token to use for the payment:

{
   "details":[
      {
         "key":"applepay.token",
         "type":"applePayToken"
      }
   ],
   "name":"Apple Pay",
   "type":"applepay"
}

 When the shopper selects Apple Pay, they will be 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.

Step 2: Make a payment

Make a request to the /payments  providing:

  • amount.

  • paymentMethod.type: Set to applepay.
  • additionalData.applepay.token: The token you retrieve from the Apple framework. 

To retrieve this token:

  1. Follow the Apple Pay documentation to retrieve paymentData.
  2. Base64 encode this data and set additionalData.applepay.token to this value.

To store the payment details for future use, include a shopperReference, and paymentMethod.storeDetails. 

{
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "reference": "Your order number",
  "paymentMethod": {
    "type": "applepay",
    "additionalData.applepay.token": "VNRWtuNlNEWkRCSm1xWndjMDFFbktkQU..."
  },
  "returnUrl": "https://your-company.com/...",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}

For information on retrieving your Apple Pay token, see the Apple documentation on implementing Apple Pay.

Step 3: Present payment result

You'll receive a response which contains the result of the payment.

{
  "pspReference": "881539337151149C",
  "resultCode": "Authorised"
}
Use the  resultCode to display the payment result to shopper. For more information on how to handle the resultCode, see  Result codes.

Apple Pay notifications

Notifications for Apple Pay work in the same way as card payments. See our notifications section for more information.

Make a recurring Apple Pay payment

If you have a recurring or subscription business model we recommend tokenizing the shopper's payment details.

When you create a shopper token from a card payment, we store their payment details with the token. The token can be used to make recurring payments for the shopper.

You can create a shopper token with either the SDK or API integrations, but to make recurring payments with the token you'll need to use the  /payments endpoint.

Maestro cards and card payments authenticated with 3D Secure don't support recurring payments.

Create shopper token

Tokenize the shopper's payment details when you make the initial card payment. The steps for doing this depend on whether you integrated with our Checkout SDKs or our API integration.

Checkout SDKs

  1. When you call /paymentSession to create a payment session, additionally include:

    • shopperReference: Your unique ID for this shopper.

    • enableRecurringtrue.

  2. If the shopper's payment details were successfully tokenized, you'll receive a successful payment notification that includes a recurringDetailReference. This is the token you will need to make recurring payments for this shopper.

API integration

  1. When you call /payments to make a payment, additionally include:
    • shopperReference: Your unique ID for this shopper.
    • paymentMethod.storeDetailstrue.
  2. If the shopper's payment details were successfully tokenized, you'll receive a successful payment notification that includes a recurringDetailReference. This is the token you will need to make recurring payments for this shopper.

Make recurring payment

For each recurring payment for this shopper:

  • Make a cards payment with a /payments call, and additionally include :
    • recurringDetailReference: Token you received back in the initial payment.
    • shopperReference: The shopper ID you provided when created the shopper token.
    • shopperInteractionContAuth.
    {
       "merchantAccount":"YourMerchantAccount",
       "reference":"Your Reference Here",
       "amount":{
          "value":1000,
          "currency":"EUR"
       },
       "paymentMethod":{
          "type":"scheme",
          "recurringDetailReference":"7219687191761347"
       },
       "returnUrl":"https://your-company.com/...",
       "shopperReference":"yourShopperId",
       "shopperInteraction":"ContAuth"
    }

    If the payment was successful you'll receive an Authorised resultCode and a pspReference , our unique identifier for this transaction. 

Configuring the Component

Our Apple Pay Component allows you to configure the Apple Pay button presented to the shopper:

  1. When instantiating the Apple Pay Component, you can optionally specify the:

    • buttonType: The type of button you want displayed on your payments form. Set to either:

      • plain: Apple Pay.

      • buy: Buy with Apple Pay.

      • donate: Donate with Apple Pay.

      • check-out: Check out with Apple Pay.

      • book: Book with Apple Pay.

      • subscribe: Subscribe with Apple Pay.

    • buttonColorSpecify the color of the button you want displayed on the payment form. Set to either:
      • black: Black button.
      • white: White button with no outline.
      • white-with-line: White button with black outline.
    const appleNode = document.getElementById("applepay-field");
    const applepay = checkout.create("applepay", {
    
        // Payment info
        currencyCode: "EUR",
        amount: 1000,
        countryCode: "DE",
    
        // Merchant config
        configuration: {
           merchantName: "Adyen Test merchant",
           merchantIdentifier: "06946223745213860250"
        },
    
        // Button config
        buttonType: "plain",
        buttonColor: "black",
     
        // Events
        onAuthorized: (resolve, reject, event) {
           return resolve();
        },
        onValidateMerchant: (resolve, reject, validationURL) {
           resolve(MERCHANT_SESSION)
        }
    });

    This will render a black Apple Pay button in your payment form.

Testing Apple Pay

Before going live, use Apple's test card numbers to test your integration.

Card Type Card number Expiry date CVC/CID

Amex

3499 569590 41362 12/2022 1111
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.

See also