# Apple Pay for web

Accept Apple Pay payments on your website with [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website.md), 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.

---

## How it works

1. The customer lands on your checkout page.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client-side to mount Flow.
4. Flow displays the Apple Pay payment method to the customer.
5. When the customer selects _Pay_, Flow performs a payment request and handles any additional actions, such as a third-party payment page redirect.
6. You receive a webhook notifying you of the payment status.

---

## Before you start

To set up Apple Pay, you need the following:

- A domain with a valid TLS certificate
- A Checkout.com [test account](https://www.checkout.com/get-test-account)
- A [public and secret key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) with the following scopes:
  - Public key – `payment-sessions:pay` and `vault-tokenization`
  - Secret key – `payment-sessions` and `vault:apme-enrollment`

To offer Apple Pay with Flow, you must:

1. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) to onboard a custom domain with Apple Pay.
2. Call the [Enroll a merchant to the Apple Pay Service](https://api-reference.checkout.com/tag/Apple-Pay/#operation/ApplePayEnrollMerchant) endpoint, and set the `domain` field to the domain in which you want to process Apple Pay payments.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/applepay/enrollments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/applepay/enrollments`

### Request example

```json
{
  "domain": "yourdomain.com"
}
```

3. Make sure you comply with the Apple Pay [payment method rules](https://www.checkout.com/legal/payment-methods-rules).

4. To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

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

### Content Security Policy

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

```
connect-src, https://*.checkout.com
frame-src, https://*.checkout.com
script-src, https://*.checkout.com
img-src, https://*.checkout.com
```

---

## Create a new Payment Session `Server side`

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](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint.

In the request body:

- Set `billing.address.country` to a country [supported by Apple Pay](https://support.apple.com/en-gb/102775).
- Set `currency` to the selected country's [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payment-sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions`

### Request example

```json
{
  "amount": 1000,
  "currency": "GBP",
  "reference": "ORD-123A",
  "display_name": "Online shop",
  "payment_type": "Regular",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "items": [
    {
      "reference": "0001",
      "name": "Gold Necklace",
      "quantity": 1,
      "unit_price": 1000
    }
  ],
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}
```

---

## Initialize and mount Flow `Client side`

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

```bash
npm install @checkout.com/checkout-web-components --save
```

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

```html
<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.

```javascript
// Insert your public key here
const publicKey = '{YOUR_PUBLIC_KEY}';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',
});
```

### Configuration options

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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md#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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md#Initialization). |
| `environment` | Sets the environment that the library sends 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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/add-localization-to-your-flow-integration.md). |
| `onAuthorized` | [Inspect the payment details](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-payment-process.md#Inspect_wallet_payment_details) the customer provided in Apple Pay when they initiate a payment submission. |
| `paymentSession`<br><br>`required` | The response from the `PaymentSession`. |
| `publicKey`<br><br>`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.<br><br>For how to add translations, see [Add localization to your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/add-localization-to-your-flow-integration.md). |

Use `CheckoutWebComponents` to create an `applepay` object:

```javascript
const applepayComponent = checkout.create("applepay");
```

Mount Flow to your website using the `mount()` method. The method takes an [Element selector](https://developer.mozilla.org/en-US/docs/Web/API/Element) or an [Element](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors) as an argument. For example, `#flow-container` or `document.getElementById(#flow-container)`, respectively.

**Mount Flow to a Selector**

```javascript
if (await applepayComponent.isAvailable()) {
  applepayComponent.mount('#applepay-container');
}
```

**Mount Flow to an Element**

```javascript
const applepayElement = document.getElementById('applepay-container');

if (await applepayComponent.isAvailable()) {
  applepayComponent.mount(applepayElement);
}
```

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

---

## Handle the payment response `Client side`

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:

```javascript
const publicKey = '{YOUR_PUBLIC_KEY}';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',

  onPaymentCompleted: async (_self, paymentResponse) => {
    // Handle synchronous payments
    await handlePayment(paymentResponse.id);
  },
});
```

If you've [configured your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), we send a [Gateway](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#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.

---

## Test the integration

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](https://developer.apple.com/apple-pay/sandbox-testing/).

Use [test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md) to simulate different payment flows and ensure your integration is set up correctly and behaving as expected.

To check the status of a payment:

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Payments_ > _Processing_ > _All payments_.
3. Select the test payment to view its details.

---

## Next steps

**[Customize your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md)**

Learn how to customize your Flow integration.

**[Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference.md)**

See the configuration options and error handling steps for Flow.