Our Web Drop-in renders Apple Pay in your payment form. When the shopper selects Apple Pay, Drop-in invokes the payment sheet, where shoppers select the card they want to use, provide contact details and shipping address, and then authenticate the payment through Face ID or Touch ID.
Before you begin
This page explains how to add Apple Pay to your existing Web Drop-in integration. The Web Drop-in integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Drop-in integration guide.
You can either use Adyen's Apple Pay certificate which makes it quicker to set up Apple Pay, or you can also use your own Apple Developer account and certificate which requires extra configuration steps:
-
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
, orhttps://www.mystore2.com
.
-
Shop website: your main website URL, for example
- Make sure that you have set up your back end implementation, and added Drop-in to your payments form.
- Set up your server for secure communication with Apple Pay.
- Enable Apple Pay using your own Apple Developer account and certificate.
- Make sure that you have set up your back end implementation, and added Drop-in to your payments form.
Show Apple Pay in your payment form
After you have finished enabling Apple Pay, you can show Apple Pay in your payment form:
-
Drop-in uses the
countryCode
and theamount.currency
from your /paymentMethods request to show the available payment methods to your shopper. From your server, make a /paymentMethods request specifying:- countryCode: Country where Apple Pay is supported. For example, NL.
- amount.currency: Any supported currency. For example, EUR.
-
When creating an instance of Drop-in, add the required Apple Pay configuration:
amount
: The currency and value of the payment, in minor units.countryCode
: The two-letter country code of your merchant account.configuration
: Object that specifies themerchantName
(name that will be displayed on the form) and your ApplemerchantId
.- Required if you're using an Web Drop-in version earlier than v3.17.1.
- In 3.17.1 and later versions, you can omit this object. By default, Drop-in takes the values from the
paymentMethodsResponse
in theAdyenCheckout
instance configuration.
onValidateMerchant
: Event called when the payment sheet is displayed.- Required if you're using your own Apple Pay certificate, if you're using a Web Drop-in version earlier than 3.16.0, or if you want to call the event manually. Follow the code samples to learn how to call
onValidateMerchant
manually. For more information, see Apple Pay documentation. - If you're using Adyen's Apple Pay certificate or if you're using 3.16.0 and later versions, you can omit this because Drop-in calls the event by default.
If your integration is set up correctly, Drop-in renders Apple Pay. Otherwise, check if you are receiving correct values in the configuration object from the /paymentMethods response and if you are passing the object to your front end as part of thepaymentMethodsResponse
in theAdyenCheckout
instance configuration.
- Required if you're using your own Apple Pay certificate, if you're using a Web Drop-in version earlier than 3.16.0, or if you want to call the event manually. Follow the code samples to learn how to call
onSubmit
: Event called after shopper authorizes the payment with Apple Pay.
const dropin = checkout .create('dropin', { paymentMethodsConfiguration: { // Required configuration for Apple Pay applepay: { amount: { value: 1000, currency: "EUR" }, countryCode: "DE", // Configuration object is required if using version earlier than v 3.17.1. // Omit this object when using version 3.17.1 and later. 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 merchantId: 'adyen.test.merchant' }, // onValidateMerchant is required if using your own Apple Pay certificate or Web Drop-in earlier than v3.16.0. // Omit this object when using version 3.16.0 and later. 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(); }); }, onSubmit: (state) => { // Call your server to make `/payments` request makePayment(state.data) .then(response => { // Your function to show the final result to the shopper showFinalResult(response); }) .catch(error => { throw Error(error); }); } } }, ... }) .mount('#dropin');
Optional Drop-in configuration
When creating an instance of Drop-in, you can also:
- 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. Possible values:
|
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. | |
supportedNetworks |
The payment networks you support. Possible values: amex, discover, elo, interac, maestro, masterCard, visa. From version 3.20.0 of Web Components the supported networks are automatically configured based on your account settings, but you can override this here. | |
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 | |
---|---|---|
onChange or onSubmit
|
![]() |
Called after the shopper authorizes the payment with Apple Pay. The first parameter (state ) of this function contains all the necessary data to make a payment using the /payments API. |
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. | |
onAuthorized
|
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. |
const dropin = checkout
.create('dropin', {
paymentMethodsConfiguration: {
applepay: {
...
onChange: (state) => {},
onSubmit: (state) => {},
onValidateMerchant: (resolve, reject, validationURL) => {
// Calls your server with validationURL, which then requests a payment session from Apple Pay servers.
// Your server then receives the session and calls resolve(MERCHANTSESSION) or reject() to complete merchant validation.
},
onAuthorized: (resolve, reject, event) => {},
/*
* @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) => {}
...
Make a payment
When the shopper selects to pay, Drop-in calls the onSubmit
event, which contains a state.data
.
-
Pass the
state.data
to your server. -
From your server, make a /payments request, specifying:
paymentMethod
: Thestate.data.paymentMethod
from theonSubmit
event from your front end.
curl https://checkout-test.adyen.com/v66/payments \ -H "x-API-key: YOUR_X-API-KEY" \ -H "content-type: application/json" \ -d '{ "merchantAccount":"YOUR_MERCHANT_ACCOUNT", "reference":"YOUR_ORDER_NUMBER", "amount":{ "currency":"EUR", "value":1000 }, "{hint:state.data.paymentMethod from onSubmit}paymentMethod{/hint}":{ "type":"applepay", "applePayToken": "QWIwMmI0YzAhQlFBQkFnQjMv.." } }'
# Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen::Client.new adyen.api_key = "YOUR_X-API-KEY" response = adyen.checkout.payments({ :amount => { :currency => "EUR", :value => 1000 }, :reference => "YOUR_ORDER_NUMBER", :paymentMethod => { :type => "applepay", :applePayToken => "QWIwMmI0YzAhQlFBQkFnQjMv.." }, :merchantAccount => "YOUR_MERCHANT_ACCOUNT" })
// Set YOUR_X-API-KEY with the API key from the Customer Area. // Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments. Client client = new Client("YOUR_X-API-KEY", Environment.TEST); Checkout checkout = new Checkout(client); PaymentsRequest paymentsRequest = new PaymentsRequest(); String merchantAccount = "YOUR_MERCHANT_ACCOUNT"; paymentsRequest.setMerchantAccount(merchantAccount); Amount amount = new Amount(); amount.setCurrency("EUR"); amount.setValue(15000L); paymentsRequest.setAmount(amount); ApplePayDetails applePayDetails = new ApplePayDetails(); applePayDetails.setApplePayToken(state.data.paymentMethod.applePayToken); paymentsRequest.setPaymentMethod(applePayDetails); paymentsRequest.setReference("YOUR_ORDER_NUMBER"); PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area. $client = new \Adyen\Client(); $client->setXApiKey("YOUR_X-API-KEY"); $service = new \Adyen\Service\Checkout($client); $params = array( "amount" => array( "currency" => "EUR", "value" => 1000 ), "reference" => "YOUR_ORDER_NUMBER", "paymentMethod" => array( "type" => "applepay", "applePayToken" => "QWIwMmI0YzAhQlFBQkFnQjMv.." ), "merchantAccount" => "YOUR_MERCHANT_ACCOUNT" ); $result = $service->payments($params);
#Set your X-API-KEY with the API key from the Customer Area. adyen = Adyen.Adyen() adyen.client.xapikey = 'YOUR_X-API-KEY' result = adyen.checkout.payments({ 'amount': { 'value': 1000, 'currency': 'EUR' }, 'reference': 'YOUR_ORDER_NUMBER', 'paymentMethod': { 'type': 'applepay', 'applePayToken': 'QWIwMmI0YzAhQlFBQkFnQjMv..' }, 'merchantAccount': 'YOUR_MERCHANT_ACCOUNT' })
// Set your X-API-KEY with the API key from the Customer Area. var client = new Client ("YOUR_X-API-KEY", Environment.Test); var checkout = new Checkout(client); var amount = new Model.Checkout.Amount("EUR", 1000); var details = new Model.Checkout.DefaultPaymentMethodDetails{ Type = "applepay", ApplePayToken = "QWIwMmI0YzAhQlFBQkFnQjMv.." }; var paymentRequest = new Adyen.Model.Checkout.PaymentRequest { Reference = "YOUR_ORDER_NUMBER", Amount = amount, MerchantAccount = "YOUR_MERCHANT_ACCOUNT", PaymentMethod = details }; var paymentResponse = checkout.Payments(paymentsRequest);
// Set your X-API-KEY with the API key from the Customer Area. const {Client, Config, CheckoutAPI} = require('@adyen/api-library'); const config = new Config(); // Set your X-API-KEY with the API key from the Customer Area. config.apiKey = '[API_KEY]'; config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]'; const client = new Client({ config }); client.setEnvironment("TEST"); const checkout = new CheckoutAPI(client); checkout.payments({ amount: { currency: "EUR", value: 1000 }, paymentMethod: { type: 'applepay', applePayToken: 'QWIwMmI0YzAhQlFBQkFnQjMv..' }, reference: "YOUR_ORDER_NUMBER", merchantAccount: config.merchantAccount }).then(res => res);
The response contains the result of the payment.
Present the payment result
Use the resultCode
that you received in response to your /payments call to present the payment result to your shopper.
The resultCode
values you can receive for Apple Pay are:
resultCode | Description | Action to take |
---|---|---|
Authorised | The payment was successful. | Inform the shopper that the payment has been successful. |
Refused | The payment was refused by the shopper's bank. | Ask the shopper to try the payment again using a different payment method. |
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 Type | Card number | Expiry date | CVC/CID |
---|---|---|---|
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.
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:
- 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, under the following path:
/.well-known/apple-developer-merchantid-domain-association
-
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: Optional. Add any other domains you use for your shop website, for example
https://www.mystore1.com
, orhttps://www.mystore2.com
.
-
Shop website: your main website URL, for example
- Enable Apple Pay on your Apple Pay Developer account for your live merchant identifier.
- Set up your server for secure communication with Apple Pay.