Apple Pay Component

Our Apple Pay Component renders Apple Pay in your payment form. When the shopper selects Apple Pay, the Component 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 Components integration. The Web Components integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your Apple Pay integration:

1. Make sure that you have set up your back end implementation, and created an instance of AdyenCheckout.
2. Sign up for Apple Pay in your Apple Developer account and submit the merchant identifier and payment processing certificate to our Support Team. For more information and detailed instructions, see Enable Apple Pay.
3. Register and validate your merchant domain with Apple.
4. Create a merchant identity certificate.
5. Add Apple Pay in your test Customer Area.

Show Apple Pay in your payment form

To present the Apple Pay Component in your payment form:

1. Make a POST /paymentMethods request specifying:
   • countryCode: Country where Apple Pay is supported. For example, NL.
   • amount.currency: Any supported currency. For example, EUR.

2. Pass the full response to the paymentMethodsResponse object when creating an instance of the AdyenCheckout.

3. Add the Apple Pay Component:

   a. Create a DOM element, placing it where you want the Apple Pay button to be rendered:

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

   b. Create an instance of the Apple Pay Component, specifying:

   • currencyCode: The three-character currency code.
   • amount: The amount of the transaction.
   • countryCode: The two-letter country code of your merchant account.
   • configuration.merchantName: The merchant name that you want displayed on the Apple Pay payment sheet.
   • configuration.merchantIdentifier: Your Apple Merchant ID.
   • onValidateMerchant: Event called when the payment sheet is displayed. For more information, see Apple Pay documentation.

   const appleNode = document.getElementById("applepay-field");
   const applepay = checkout.create("applepay", {
       currencyCode: "EUR",
       amount: 1000,
       countryCode: "DE",
       configuration: {
          merchantName: "Adyen Test merchant",
          merchantIdentifier: "adyen.test.merchant"
       },
       // Button config
       buttonType: "plain", // Optional. The type of button you want to be displayed in the payments form
       buttonColor: "black", // Optional. Specify the color of the button
       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.
       }
   });

   c. Check whether Apple Pay is available to the shopper. If it is, mount the Component:

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

   Do not mount the Component if Apple Pay is not available to the shopper.

Optional Component configuration

With the Apple Pay Component, 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

Payment request data

The following configuration options are supported from Components V 2.5.0 unless specified.

Events

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

Event	Required	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.
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.

    //onSubmit or onChange defined in your AdyenCheckout instance
    const applepay = checkout.create("applepay", {
        ...
        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, the Component calls the onChange event, which contains a state.data.

1. If state.isValid is true, collect the state.data and pass this to your server.

2. From your server, make a /payments, specifying:

   • paymentMethod: The state.data.paymentMethod from the onChange event from your front end.
   https://docs.adyen.com/payment-methods/apple-pay/web-component#apple-pay-api

   • curl
   • Ruby
   • Java
   • PHP
   • Python
   • C#
   • NodeJS

   curl Ruby Java PHP Python C# NodeJS

   curl https://checkout-test.adyen.com/v52/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 onChange or onSubmit}paymentMethod{/hint}":{
       "type":"applepay",
       "applepay.token": "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",
       :applepay.token => "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);
   
       DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
       paymentMethodDetails.setType("applepay");
       paymentMethodDetails.setApplepayToken("QWIwMmI0YzAhQlFBQkFnQjMv..");
       paymentsRequest.setPaymentMethod(paymentMethodDetails);
   
       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",
       "applepay.token" => "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',
         'applepay.token': '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',
           applepay.token: 'QWIwMmI0YzAhQlFBQkFnQjMv..'
       },
       reference: "YOUR_ORDER_NUMBER",
       merchantAccount: config.merchantAccount
   }).then(res => res);

   The response contains the result of the payment.

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

   /payments response

   {
     "pspReference": "881539337151149C",
     "resultCode": "Authorised"
   }

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:

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.

Check the status of an Apple Pay test payment in your Customer Area > Transactions > Payments.

Before you can go live, you need to have the API Clientside Encryption Payments role enabled for your web service user. Check this in your live Customer Area or ask your Admin user to verify.

See also