This page explains how to add Apple Pay to your existing Web Drop-in integration.
Requirements
Select which endpoint you are using:
Requirement | Description |
---|---|
Integration type | Make sure that you have built a Sessions flow Web Drop-in integration. |
API credential roles | To process live Apple Pay payments make sure that you have the following role:
|
Limitations | To show Apple Pay in an iFrame, the iFrame origin must match the top-level origin. Make sure that the protocols, hosts, and ports are the same for both. |
Setup steps | Before you begin, make sure that you have:
|
API reference
You do not 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 Drop-in 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.
Drop-in configuration
Select which endpoint you are using:
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 do not 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 are using your own Apple Pay certificate:
const applePayConfiguration = { //onValidateMerchant is required if you are 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:
const configuration = { // ... other required configuration paymentMethodsConfiguration: { applepay: applePayConfiguration } };
Pass the Drop-in configuration object when creating your instance of AdyenCheckout
:
const checkout = await AdyenCheckout(configuration);
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:
const dropin = checkout.create('dropin', { // ... other optional configuration instantPaymentTypes: ['applepay'] }).mount('#dropin-container');
Optional Apple Pay 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 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 |
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 |
Billing information fields that you require from the shopper to process the transaction. Refer to Apple Pay documentation for sample values. |
|
Shipping information fields that you require from the shopper to fulfill the order. Refer to Apple Pay documentation for sample values. |
||
Known contact information |
Set an up-to-date billing contact information for the shopper. |
|
Set an up-to-date shipping contact information for the shopper. |
||
Custom data |
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 |
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. |
onPaymentAuthorized
|
Also called after the shopper authorizes the payment with Apple Pay. This contains all the raw event from Apple Pay. |
onPaymentMethodSelected
|
Called when the shopper selects a new payment method. |
onShippingContactSelected
|
Called when the shopper selects a shipping contact. |
onShippingMethodSelected
|
Called when the shopper selects a shipping method. |
Optional Apple Pay Wallet Order Tracking
Supported in v6.0.0 or later.
You can use Apple Pay Wallet Order Tracking to give your shopper order tracking through Apple Pay. For more information, refer to the following resources from Apple:
- Apple Pay Wallet Order Tracking Demo
- Apple Pay Tech Talk about implementing Apple Pay with order management
- Example Order Packages
-
Implement
onOrderTracking
:Implement order trackingExpand viewCopy link to code blockCopy codeconst applepay = new ApplePay(checkout, { onOrderTrackingRequest: async (resolve, reject) => { try { // Request the order details from your server. const order = await server.getOrder(); // Pass the order details to Drop-in. const orderDetails = { orderTypeIdentifier: order.orderTypeIdentifier, orderIdentifier: order.orderIdentifier, webServiceURL: order.webServiceURL, authenticationToken: order.authenticationToken }; resolve(orderDetails); } catch (error) { // If you cannot get the order, call the reject function. reject(); } } }); -
When
onOrderTracking
is called depends on which server-side flow your integration uses.After the payment is complete, Drop-in calls
onOrderTracking
. -
From your server, get the order details and pass it as
orderDetails
to your client side.
If an error occurs, the Apple Pay payment overlay is closed, and the payment is successfully completed without creating an order in the shopper's Apple Wallet app.
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.
-
Download and unzip the domain association file.
-
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.
See an example of a working domain association file.
- Have
-
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.
- You'll be asked for Shop websites: your website URLs, for example