Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Apple Pay Drop-in integration

Add Apple Pay to an existing Drop-in integration.

On this page, you can find additional configuration for adding Apple Pay to your Drop-in integration.

Before you begin

This page assumes you've already:

Set up Apple Pay

You don't need to create your own Apple Pay certificate for your web integration because you can process payments through Adyen's Apple Pay certificate. The benefits of using Adyen's Apple Pay certificate are:

  • A faster way to add Apple Pay to your integration.
  • There is less configuration required.
  • You get access to new features.
  • Apple Pay enabled by default for your Pay by Link integration, if you have one.
  1. Set up your server for secure communication with Apple Pay.
    • All pages that include Apple Pay must be served over HTTPS.
    • Your domain must have a valid SSL certificate.
  2. 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.
    • You cannot use https://localhost to test.
  1. Make sure that you're using Drop-in version 3.18.0 or later.
The option to use Adyen's Apple Pay certificate is only available on web. If you have a native mobile integration, you need to use your own Apple Pay certificate.
  1. Set up your server for secure communication with Apple Pay.
  2. Enable Apple Pay using your own Apple Developer account and certificate.

API reference

You don't need to send additional fields for Apple Pay. To see optional fields that you can send for all payment methods, choose the endpoint you integrated:

If you run into an error, refer to Handle Apple Pay errors.

Drop-in configuration

Select which endpoint you're integrating:

This is the default with Drop-in v5.0.0 or later. If you are using /sessions together with Adyen's Apple Pay certificate, you don't need to add any additional configuration for Apple Pay. If using your own Apple Pay certificate, you need to include:
  • onValidateMerchant: Required for displaying the Apple Pay payment sheet. For more information, see Apple Pay documentation.
The following example shows how to configure Drop-in if you're using your own Apple Pay certificate:
Apple Pay configuration
const applePayConfiguration = {
    //onValidateMerchant is required if you're using your own Apple Pay certificate
    onValidateMerchant: (resolve, reject, validationURL) => {
        // Your server uses the validation URL to request a session from the Apple Pay server.
        // Call resolve(MERCHANTSESSION) or reject() to complete merchant validation.
        validateMerchant(validationURL)
            .then(response => {
            // Complete merchant validation with resolve(MERCHANTSESSION) after receiving an opaque merchant session object, MerchantSession
            resolve(response);
            })
            .catch(error => {
            // Complete merchant validation with reject() if any error occurs
            reject();
            });
    }
};
Include the applePayConfiguration object when creating a configuration object:
AdyenCheckout configuration
const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    applepay: applePayConfiguration
  }
};
If you implemented an advanced use case, or integrated Drop-in before v5.0.0.
Parameter name Required Description
amount.value -white_check_mark- The value of the payment, in minor units.
amount.currency -white_check_mark- The currency code of the payment.
countryCode -white_check_mark- The two-letter country code of your merchant account.
onValidateMerchant Required if you're using your own Apple Pay certificate. Required for displaying the Apple Pay payment sheet. For more information, see Apple Pay documentation.
configuration.merchantName Required for v3.17.0 or earlier Specifies the name that will be displayed on the form.
In v3.17.1 and later, the Component takes the value from the paymentMethodsResponse in the AdyenCheckout instance configuration.
configuration.merchantIdentifier Required for v3.17.0 or earlier, or if you want to offer Pay by Link Specifies your Apple merchantId.
In v3.17.1 and later, the Component takes the value from the paymentMethodsResponse in the AdyenCheckout instance configuration.
supportedNetworks Required for v3.19.0 or earlier Specifies the card networks you support. Use values from Apple Pay documentation. For v3.20.0 or later, the supported networks are configured automatically based on your Adyen Merchant account settings, but you can override them here.

Use Adyen's Apple Pay certificate

The following example shows how to configure Drop-in if you're Adyen's Apple Pay certificate:
Apple Pay configuration
const applePayConfiguration = {
    amount: {
        value: 1000,
        currency: "EUR"
    },
    countryCode: "DE"
};
Include the applePayConfiguration object when creating a configuration object:
AdyenCheckout configuration
const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    applepay: applePayConfiguration
  }
};

Use your own Apple Pay certificate

The following example shows how to configure Drop-in if you're using your own Apple Pay certificate and Drop-in v3.17.0 or earlier.
Apple Pay configuration
const applePayConfiguration = {
    amount: {
        value: 1000,
        currency: "EUR"
    },
    //onValidateMerchant is required if you're using your own Apple Pay certificate
    onValidateMerchant: (resolve, reject, validationURL) => {
        // Your server uses the validation URL to request a session from the Apple Pay server.
        // Call resolve(MERCHANTSESSION) or reject() to complete merchant validation.
        validateMerchant(validationURL)
            .then(response => {
            // Complete merchant validation with resolve(MERCHANTSESSION) after receiving an opaque merchant session object, MerchantSession
            resolve(response);
            })
            .catch(error => {
            // Complete merchant validation with reject() if any error occurs
            reject();
            });
    },
    configuration: {
        // Name to be displayed on the form.
        merchantName: "Adyen Test merchant",
        // Your Apple merchant identifier as described in https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrequest/2951611-merchantidentifier
        merchantIdentifier: "adyen.test.merchant"
    },
    // Required for v3.19.0 or earlier. The networks you support. Use the values from https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/1916122-supportednetworks
    supportedNetworks: [amex, discover, visa]
};
Include the applePayConfiguration object when creating a configuration object:
AdyenCheckout configuration
const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    applepay: applePayConfiguration
  }
};

Optional configuration

You can add optional configuration to do the following:

Button configuration

Property Description
buttonType The type of button you want displayed on your payments form. Possible values:
- 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

The following types are supported from Web Components v4.1.0:
- add-money: Add money with Apple Pay
- contribute: Contribute with Apple Pay
- order: Order with Apple Pay
- reload: Reload with Apple Pay
- rent: Rent with Apple Pay
- support: Support with Apple Pay
- tip:Tip with Apple Pay
- top-up: Top Up with Apple Pay
buttonColor Specify the color of the button you want displayed on the payment form. Possible values:
- black: Black button
- white: White button with no outline
- white-with-line: White button with black outline

Payment request data

Payment request data Configuration object Description
Transaction information version Check the Apple Pay on the Web documentation for version features and compatibility details.
totalPriceStatus Default value is final. Indicate 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. Refer to Apple Pay documentation for sample values.
merchantCapabilities Payment capabilities supported by the merchant. Default value is [`supports3DS`]. Refer to Apple Pay documentation for other options.
shippingMethods List of available methods for shipping physical goods. Refer to Apple Pay documentation for sample values.
shippingType Optional value that indicates how purchased items are to be shipped. Refer to Apple Pay documentation for available options.
supportedCountries Specify the ISO 3166 country codes if you only support payments from cards issued in specific countries.
Requested billing and shipping contact information requiredBillingContactFields Billing information fields that you require from the shopper to process the transaction. Refer to Apple Pay documentation for sample values.
requiredShippingContactFields Shipping information fields that you require from the shopper to fulfill the order. Refer to Apple Pay documentation for sample values.
Known contact information billingContact Set an up-to-date billing contact information for the shopper.
shippingContact Set an up-to-date shipping contact information for the shopper.
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.

Events

The following event handlers are supported for Apple Pay. Select the event handler names to see the related Apple Pay documentation.

Event Description
onClick(resolve,reject) Called when the shopper clicks the Apple Pay button. Call resolve() to continue or reject() stop the payment flow. You must create the Apple Pay session from a user gesture handler.
onValidateMerchant Called when the payment sheet is displayed. For more information, see Apple Pay Documentation.
onAuthorized Also called after the shopper authorizes the payment with Apple Pay. This contains all the raw event from Apple Pay. For more information, see Apple Pay Documentation.
onPaymentMethodSelected Called when the shopper selects a new payment method. For more information, see Apple Pay Documentation.
onShippingContactSelected Called when the shopper selects a shipping contact. For more information, see Apple Pay Documentation.
onShippingMethodSelected Called when the shopper selects a shipping method. For more information, see Apple Pay Documentation.

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 TypeCard numberExpiry dateCVC/CID
Discover6011 0009 9446 278011/2022111
Mastercard5204 2452 5000 148811/2022111
Visa4761 1200 1000 049211/2022533

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.

To create an Apple Pay sandbox environment and test payments, you need an Apple Developer account. This also applies if you're using Adyen's Apple Pay certificate.

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:

  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.
    • The file cannot be behind a proxy or redirect.
    See an example of a working domain association file.
  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: Add any other domains you use for your shop website, for example https://www.mystore1.com, or https://www.mystore2.com. You must register all top-level domains and subdomains.
  1. Enable Apple Pay on your Apple Pay Developer account for your live merchant identifier.
  2. Set up your server for secure communication with Apple Pay.

See also