Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

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. Make sure that you have already added the Components JavaScript file and the required configuration on your payments page.

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

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

    • currencyCode: The three-character currency code.
    • amount
    • countryCode: The two-letter country code of your merchant account.
    • configuration.merchantName: The 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
    });
  4. 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.

  5. 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" }
    }
  6. 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: 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 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 and the payment form. You can include additional data such as transaction information, fields for billing and shipping contact information, and add logic for specific events on your payment form.

  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.
    • buttonColor: Specify 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) => {
            resolve();
        },
        onValidateMerchant: (resolve, reject, validationURL) => {
           resolve(MERCHANT_SESSION)
        }
    });

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

  2. Aside from the Apple Pay button, you can also provide additional Apple Pay payment request data within your Component configuration.

    The following configuration options are supported from Components version 2.5.0 and later unless specified.

    For more information on the properties, click on the property names to see the related Apple Pay documentation.

    • Transaction information

      • version : Defaults to 3. Indicates the Apple Pay Web version that the Component will load. Check the Apple Pay on the Web documentation for version features and compatibility details.
      • totalPriceStatus : Default value is final. Indicates if the line item is final or pending.
      • totalPriceLabel : String description of the line item.
      • lineItems : A set of line items that explain recurring payments, additional charges, and discounts. See Apple Pay documentation for sample values.
      • merchantCapabilities :The payment capabilities supported by the merchant. Default value is [`supports3DS`]. See Apple Pay documentation for other options.
      • shippingMethods : A list of available methods for shipping physical goods. See Apple Pay documentation for sample values.
      • shippingType : An optional value that indicates how purchased items are to be shipped. See Apple Pay documentation for available options.
      • supportedCountries : Specify the ISO 3166 country codes if you only support payments from cards issued in specific countries.
      • supportedNetworks : Supported from Components version 2.4.1. The payment networks you support, for example, visa. See Apple Pay documentation for more information.
    • Requested billing and shipping contact information

      • requiredBillingContactFields : Billing information fields that you require from the shopper to process the transaction. See Apple Pay documentation for sample values.
      • requiredShippingContactFields : Shipping information fields that you require from the shopper to fulfill the order. See Apple Pay documentation for sample values.
    • Known contact information

    • Custom data

      • applicationData : A Base64-encoded string used to contain your application-specific data. For example, a shopping cart identifier or an order number that you will need to identify this transaction.
  3. Our Apple Pay Component supports the following event handlers on the payment form. Click on the event handler names to see the related Apple Pay documentation.

    The following event handlers are supported from Components version 2.5.0 and later.

    /*
    * @param resolve(ApplePayPaymentMethodUpdate update) Completes the selection of a payment method with an update. This will call https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1777995-completepaymentmethodselection.
    * @param reject(ApplePayPaymentMethodUpdate update)
    * @param event The event parameter contains the paymentMethod attribute.
    */
    onPaymentMethodSelected: (resolve, reject, event) => {}
    /*
    * @param resolve(ApplePayShippingContactUpdate update) Completes the selection of a shipping contact with an update. This will call https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778008-completeshippingcontactselection.
    * @param reject(ApplePayShippingContactUpdate update) 
    * @param event The event parameter contains the shippingContact attribute.
    */
    onShippingContactSelected: (resolve, reject, event) => {}
    /*
    * @param resolve(ApplePayShippingMethodUpdate update) Completes the selection of a shipping method with an update. Will call https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778024-completeshippingmethodselection
    * @param reject(ApplePayShippingMethodUpdate update) 
    * @param event The event parameter contains the shippingMethod attribute.
    */
    onShippingMethodSelected: (resolve, reject, event) => {}

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