Apple Pay for web

Last updated: October 22, 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 our payment gateway and enable payments on your website.

The customer lands on your 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 selects Pay, 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 set up Apple Pay, you need the following:

A domain starting with https that has a valid TLS certificate
Access to a Secure Shell (SSH) terminal
Access to upload files to your server
A Checkout.com test account

To offer Apple Pay with Flow, you must:

Contact your account manager or request support to onboard a custom domain with Apple Pay.
You receive an apple-developer-merchantid-domain-association.txt file.
Upload the .txt file to your server so that it's accessible at the following location:
https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association – Replace yourdomain.com with the URL of your domain.
Call the Enroll a merchant to the Apple Pay Service endpoint, and set the domain field to the domain in which you want to process Apple Pay payments.

post

https://api.checkout.com/applepay/enrollments


1{
2  "domain": "https://yourdomain.com"
3}

Make sure you comply with the Apple Pay payment method rules.

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

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

To receive webhooks for the payment events, configure your webhook server.

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, 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.

Call the Create a Payment Session endpoint.

In the request body:

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

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, 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 returned in the Create a Payment Session response.


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`	Enables you to customize the visual appearance of the `CheckoutWebComponents` elements. For customization options, see Appearance options.
`componentOptions`	Enables 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. For customization options, see Component options.
`environment`	Sets the environment that the library should point to 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`. For supported languages, see Add localization to your Flow integration.
`onAuthorized`	Inspect the payment details the customer provided in Apple Pay when they initiate a payment submission.
`paymentSession` required	The response from the `PaymentSession`.
`publicKey` required	Your public API key, prefixed with `pk_`.
`translations`	Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow. For how to add translations, see Add localization to your Flow integration.

Use CheckoutWebComponents to create an applepay object:


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

Mount Flow to your 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

You cannot embed Flow within an iframe or onto a Shadow DOM.

The onPaymentCompleted event is raised 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 configured your webhook server, 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 start your order fulfillment process.

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

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 Apple Developer – Sandbox testing.

Use test cards to simulate different payment flows and 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 begin

Request example

Information

Content Security Policy

Create a new Payment Session
Server side

Request example

Response example

Initialize and mount Flow
Client side

Note

Configuration options

Note

Handle the payment response
Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Flow payment process

Before you begin

Request example

Information

Content Security Policy

Create a new Payment Session Server side

Request example

Response example

Initialize and mount Flow Client side

Note

Configuration options

Note

Handle the payment response Client side

Test the integration

Next steps

Customize your Flow integration

Flow library reference

Create a new Payment Session
Server side

Initialize and mount Flow
Client side

Handle the payment response
Client side