Apple Pay Component

Add Apple Pay to an existing Components integration.

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

Before you begin

This page assumes you've already built a Components integration.

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.
Apple Pay enabled by default for your Pay by Link integration, if you have one.

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.
Add Apple Pay in your test 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.
- You cannot use http://localhost to test.

Make sure that you are using Components 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.

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:

/sessions: This is the default with Components v5.0.0 or later.
/payments: If you implemented an additional use case.

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

Component configuration

Step 1: Create a DOM element

Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered:

 <div id="applepay-container"></div>

Step 2: Create an instance of the Component

Select which endpoint you're integrating:

This is the default with Components 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 the Apple Pay Component if you're using your own Apple Pay certificate:

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();
            });
    }
};

https://docs.adyen.com/payment-methods/apple-pay/web-component#apple-pay-configuration

Use the create method of your AdyenCheckout instance, in this case checkout, to create the Component. Pass the configuration object if you created one:

const applePayComponent = checkout.create('applepay', applePayConfiguration);

If you implemented an additional use case.

Parameter name	Required	Description
`amount.value`		The value of the payment, in minor units.
`amount.currency`		The currency code of the payment.
`countryCode`		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 the Apple Pay Component if you're using Adyen's Apple Pay certificate:

const applePayConfiguration = {
    amount: {
        value: 1000,
        currency: "EUR"
    },
    countryCode: "DE"
};

https://docs.adyen.com/payment-methods/apple-pay/web-component#apple-pay-configuration

Use the create method of your AdyenCheckout instance, in this case checkout, to create an instance of the Component. Pass the configuration object that you created above:

const applePayComponent = checkout.create('applepay', applePayConfiguration);

Use your own Apple Pay certificate

The following example shows how to configure the Apple Pay Component if you're using your own Apple Pay certificate and Components v3.17.0 or earlier.

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]
};

https://docs.adyen.com/payment-methods/apple-pay/web-component#apple-pay-configuration

Use the create method of your AdyenCheckout instance, in this case checkout, to create an instance of the Component. Pass the configuration object that you created above:

const applePayComponent = checkout.create('applepay', applePayConfiguration);

Step 3: Mount the Component

Mount the Component only after checking that Apple Pay is available to the shopper:

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

Optional configuration

You can do the following:

Configure the appearance of the Apple Pay button.
Include additional data such as transaction information, fields for billing and shipping contact information.
Add logic for specific events on your payment form.

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.
	`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.
Requested billing and shipping contact information	`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.
Known contact information	`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.

Use the create method of your AdyenCheckout instance, in this case checkout, to create an instance of the Component. Add the configuration object if you created one.

const applePayComponent = checkout.create('applepay', applePayConfiguration).mount('#applepay-container');

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.

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:

Designing your Apple Pay integration.

Download and unzip the domain association file.
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.
Add the following IP addresses to your firewall's allow list:
- Allow Apple IP Addresses for Domain Verification
- Any IP originating from *.adyen.com
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.

Are you looking for test card numbers?

Would you like to contact support?

Apple Pay Component

Before you begin

Set up Apple Pay

API reference

Component configuration

Step 1: Create a DOM element

Step 2: Create an instance of the Component

Use Adyen's Apple Pay certificate

Use your own Apple Pay certificate

Step 3: Mount the Component

Optional configuration

Button configuration

Payment request data

Events

Recurring payments

Test and go live

Going live

See also