Apple Pay for web

Last updated: March 19, 2025

Accept Apple Pay payments on your website with Flow, our pre-built, customizable payment user interface.

Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

Set up your client-side and server-side configuration to integrate with Checkout.com's payment gateway and enable payments on your website.

The customer lands on the checkout page.
You perform a server-side request to create a payment session.
You use the payment session data on the client-side to mount Flow.
Flow displays the Apple Pay payment method to the customer.
When the customer clicks the Pay option, Flow performs a payment request and handles any additional actions. For example, additional actions required for 3D Secure (3DS) authentication, or a third-party payment page redirect.
You receive a webhook notifying you of the payment status.

To offer Apple Pay with Flow, you must:

Contact your Account Manager to onboard a custom domain with Apple Pay.
Comply with the Apple Pay payment method rules.

Make sure you have a test account with Checkout.com.

Create a public key and a secret key from the Dashboard, with the following key scopes:

Public key – payment-sessions:pay and vault-tokenization
Secret key – payment-sessions

To receive notifications for the payment events that may be triggered throughout the steps, configure your webhook receiver.

Information

Some operating systems may not fully support Apple Pay if you integrate Flow within a WebView.

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:


1connect-src, https://*.checkout.com
2frame-src, https://*.checkout.com
3script-src, https://*.checkout.com
4img-src, https://*.checkout.com

When the customer is ready to pay, you must send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle all steps of the payment flow.

In your request:

Set billing.address.country to a country supported by Apple Pay
Set currency to the selected country's currency code

Information

For the full API specification, see the API reference.

post

https://api.checkout.com/payment-sessions


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "display_name": "Online shop",
6  "payment_type": "Regular",
7  "billing": {
8    "address": {
9      "country": "GB"
10    }
11  },
12  "customer": {
13    "name": "Jia Tsang",
14    "email": "[email protected]"
15  },
16  "items": [
17    {
18      "reference": "0001",
19      "name": "Gold Necklace",
20      "quantity": 1,
21      "unit_price": 1000
22    }
23  ],
24  "success_url": "https://example.com/payments/success",
25  "failure_url": "https://example.com/payments/failure"
26}


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
4  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
5  "_links": {
6    "self": {
7      "href": "https://api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

You can install the @checkout.com/checkout-web-components package via npm:


1npm install @checkout.com/checkout-web-components --save

Alternatively, you can load the package directly via a script:


1<script src="https://checkout-web-components.checkout.com/index.js" />

Note

To remain PCI compliant, you should only ever load the script directly from https://checkout-web-components.checkout.com. Do not download or host the script yourself, or include it in a bundle.

The client side initializes an instance of CheckoutWebComponents with configuration information and the payment session data retrieved in step 1.


1// Insert your public key here
2const publicKey = '{YOUR_PUBLIC_KEY}';
3
4const checkout = await CheckoutWebComponents({
5  paymentSession,
6  publicKey,
7  environment: 'sandbox',
8});

You can use the following configuration options to instantiate an instance of CheckoutWebComponents:

JavaScript key	Description
`appearance`	Allows you to customize the visual appearance of the `CheckoutWebComponents` elements. To see the customization options, refer to the Appearance options documentation.
`componentOptions`	Allows you to customize the options for the individual Flow components. For example, you can change the position of the cardholder field in the `card` component. To see the customization options, refer to the component options documentation.
`environment`	Sets the environment that the library should point, and send requests to. Use `sandbox` for your test environment, or `production` for your live environment.
`locale`	Sets the customer's locale. Explicitly setting this value overrides the `locale` returned by the `PaymentSession`. To see a list of supported languages, refer to the localization documentation.
`paymentSession`	The response from the `PaymentSession`. This field is required.
`publicKey`	Your public API key. Your key is prefixed with `pk_`. This field is required.
`translations`	Allows you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow. To learn how to add translations, refer to the Add localization to your Flow integration documentation.

Use CheckoutWebComponents to create an applepay object.


1const applepayComponent = checkout.create("applepay");

Mount Flow to the website using the mount() method. The method takes an Element selector or an Element as an argument. For example, #flow-container or document.getElementById(#flow-container), respectively.


1if (await applepayComponent.isAvailable()) {
2  applepayComponent.mount('#applepay-container');
3}


1const applepayElement = document.getElementById('applepay-container');
2
3if (await applepayComponent.isAvailable()) {
4  applepayComponent.mount(applepayElement);
5}

Note

Embedding Flow within an iframe or onto a Shadow DOM is not supported.

The onPaymentCompleted event triggers when a payment is successfully completed. You can use the event data to notify the customer of the payment status.

Add the event handler to the Flow initialization code:


1const publicKey = '{YOUR_PUBLIC_KEY}';
2
3const checkout = await CheckoutWebComponents({
4  paymentSession,
5  publicKey,
6  environment: 'sandbox',
7
8  onPaymentCompleted: async (_self, paymentResponse) => {
9    // Handle synchronous payments
10    await handlePayment(paymentResponse.id);
11  },
12});

If you've set up your webhook receiver, we send a Gateway webhook to your server. The webhook we send depends on the status of the payment. Wait for the webhook callback before you trigger your order fulfillment process.

The PaymentSession ID is returned in the webhook payload's data.metadata.cko_payment_session_id field.

To test Apple Pay payments, you need:

A device compatible with Apple Pay
A sandbox Apple Pay wallet, which you have added a test card to – For more information, see the Apple Pay Sandbox testing documentation

Use our test cards to simulate different payment flows, to ensure your integration is set up correctly and behaving as expected.

To check the status of a payment:

Sign in to the Dashboard.
Go to Payments > Processing > All payments.
Select the test payment to view its details.

Customize your Flow integration

Learn how to customize your Flow integration.

Flow library reference

See the configuration options and error handling steps for Flow.

Apple Pay for web

Flow payment process

Before you start

Information

Content Security Policy

Step 1: Create a new Payment Session
Server side

Information

Request example

Response example

Step 2: Initialize and mount Flow
Client side

Note

Configuration options

Note

Step 3: Handle the payment response
Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Flow payment process

Before you start

Information

Content Security Policy

Step 1: Create a new Payment Session Server side

Information

Request example

Response example

Step 2: Initialize and mount Flow Client side

Note

Configuration options

Note

Step 3: Handle the payment response Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Step 1: Create a new Payment Session
Server side

Step 2: Initialize and mount Flow
Client side

Step 3: Handle the payment response
Client side