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 have already built a Drop-in integration.

Set up Apple Pay

Enable Apple Pay with your own or Adyen's Apple Pay 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:

Include the applePayConfiguration object when creating a configuration object:

Optional configuration

This optional configuration parameter is only accepted on the dropin instance.

Instant payment button configuration

Use the instantPaymentTypes object to display the Apple Pay payment button at the top of the list of available payment methods. The sample below shows how to do this:

Optional Apple Pay configuration

You can do the following:

Button configuration

Property Description
buttonType The type of button you want to show 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.

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.

Recurring payments

recurringPaymentRequest

Required for recurring payments. Include to specify that the payment is a recurring payment.

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() to stop the payment flow.

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 enable recurring payments, you must include recurringPaymentRequest when configuring Apple Pay.

To make recurring Apple Pay payments, you have to 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:

  1. Download and unzip the domain association file.

  2. Host the domain association file on each domain you want to use, including subdomains. To host the file, use the exact file name apple-developer-merchantid-domain-association 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