# Apple Pay for iOS

Accept Apple Pay payments in your iOS app with [Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md), our pre-built, customizable payment user interface that you can embed directly into your mobile application. Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

---

## How it works

1. The customer opens the checkout screen.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client side to create and render Flow for mobile.
4. Flow for mobile displays the Apple Pay payment method to the customer, if it's available on their device.
5. When the customer taps _Pay_, Flow for mobile requests authorization through Apple Pay and performs the payment request.
6. You receive a webhook notifying you of the payment status.

---

## Before you start

Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com.

Create a [public key and a secret key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) from the [Dashboard](https://dashboard.checkout.com), with the following key scopes:

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

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

Integrate with [Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/get-started-with-flow-for-mobile.md) before continuing.

> **Note**
>
> Apple Pay has [additional requirements](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md#Apple_Pay_and_Google_Pay_requirements) you must adhere to.

---

## Set up Apple Pay

To implement Apple Pay in your iOS app, you must:

1. Create an Apple Merchant ID and a payment processing certificate.
2. Link your certificate to your merchant ID.
3. Add your Apple merchant ID to your iOS app.

Follow these steps:

1. In your Apple Developer account, select _Merchant IDs_ to register for an Apple merchant ID.
Use the suggested format: `merchant.com.companyName.appName`.
2. Depending on the environment where you want to update the certificate, run the following command to receive a certificate signing request from Checkout.com:

> **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**

```bash
curl --location --request POST 'https://{prefix}.api.checkout.com/applepay/signing-requests' \
--header 'Authorization: Bearer pk_xxx' \
| jq -r '.content' > ~/Desktop/cko.csr
```

**Sandbox**

```bash
curl --location --request POST 'https://{prefix}.api.sandbox.checkout.com/applepay/signing-requests' \
--header 'Authorization: Bearer pk_sbox_xxx' \
| jq -r '.content' > ~/Desktop/cko.csr
```

The certificate downloads to your `~/Desktop` path.

3. In your Apple Developer account, go to your merchant ID, and then go to _Apple Pay Payment Processing Certificate_ > _Create Certificate_.
4. Upload the `cko.csr` certificate you created earlier, and select _Continue_.
5. Download the Apple Pay processing certificate you created.
6. On your terminal, go to the path where you downloaded Apple's processing certificate, and run the following command to upload it to Checkout.com's servers:

> **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**

```bash
curl --location --request POST 'https://{prefix}.api.checkout.com/applepay/certificates' \
--header 'Authorization: Bearer pk_xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
}'
```

**Sandbox**

```bash
curl --location --request POST 'https://{prefix}.api.sandbox.checkout.com/applepay/certificates' \
--header 'Authorization: Bearer pk_sbox_xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "content": "'"$(openssl x509 -inform der -in apple_pay.cer | base64)"'"
}'
```

> **Information**
>
> Ensure that the key you send in the `Authorization` header matches the environment you send the request to. For example, use your sandbox key for the request you send to the sandbox environment.

7. Go to your [Apple Developer portal](https://developer.apple.com/account/resources/identifiers/list/merchant), and ensure that the certificate that you created is active. <br>
You can manually activate it if not activated by default.
8. In Xcode, go to _Targets_ > _Signing & Capabilities_, and add an Apple Pay capability.
9. Select the merchant ID you created earlier to use it with your app.

For more information, see Apple Developer:

- [Setting up Apple Pay](https://developer.apple.com/documentation/passkit/setting-up-apple-pay#3735190)
- [Sandbox testing](https://developer.apple.com/apple-pay/sandbox-testing/)
- [Apple Pay human interface guide](https://developer.apple.com/design/human-interface-guidelines/apple-pay)

---

## Create a 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.

> **Note**
>
> Do not embed your secret key in your client-side code.

Call the [Create a Payment Session](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint.

Apple Pay is processed as a card payment. The `currency` and `billing.address.currency` must be supported by [Apple Pay](https://support.apple.com/en-gb/102775).

> **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",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_e21237b4-214a-4e35-a35d-f33wkwo158f6"
}
```

The payment session response also determines which payment methods can be displayed to the customer. The response is determined by the customer's device, the customer's region, and the payment methods activated for your account.

---

## Enable Apple Pay in Flow for mobile `Client side`

The client initializes an instance of `CheckoutComponents` with configuration information and the payment session data:

```swift
let configuration = try await CheckoutComponents.Configuration(
  paymentSession: paymentSession,
  publicKey: publicKey,
  environment: environment,
  callbacks: .init(
    onSuccess: { paymentMethod, paymentID in
      // Handle success
    },
    onError: { error in
      // Handle error
    }
  )
)

let checkoutComponentsSDK = CheckoutComponents(configuration: configuration)
```

Pass the `applePay` option, with your Apple merchant ID, when you create a `flow` component that displays all available payment methods for the payment session:

```swift
let flow = try checkoutComponentsSDK.create(
  .flow(options: [
    .applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE")
  ])
)
```

Check if the component is available, and render it:

```swift
if component.isAvailable {
    return component.render()
} else {
    return nil
}
```

Alternatively, if you only want to render Apple Pay, create a standalone Apple Pay component:

```swift
let applepayComponent = try checkoutComponentsSDK.create(
  .applePay(merchantIdentifier: "YOUR_MERCHANT_ID_HERE")
)
```

> **Note**
>
> Before you render a standalone component, check that `isAvailable` returns `true`. Flow performs this check automatically for the payment methods it renders.

---

## Handle the payment response `Client side`

You can listen to the existing `onSuccess` [callback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/ios/componentcallback.md#onSuccess(Describable,_PaymentID)) or `onError` [callback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/ios/componentcallback.md#onError(CheckoutComponents.Error)) to handle the payment response for Apple Pay, alongside card and other payment method outcomes:

```swift
let callbacks = CheckoutComponents.Callbacks(
  onSuccess: { component, paymentID in
    // Payment completed — navigate to confirmation screen
  },
  onError: { error in
    // Payment declined, failed, or cancelled — show error UI
  }
)
```

If the customer dismisses the Apple Pay screen, Flow for mobile calls `onError` with a `paymentCancelled` error.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process.

For payments submitted with Flow, the `PaymentSession` ID appears in the webhook payload's `data.metadata.cko_payment_session_id` field.

Flow for mobile also provides other callbacks so you can customize the payment flow further. For example, you can [dynamically adjust the payment amount](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/dynamically-adjust-the-payment-amount.md) or [retrieve card metadata](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/retrieve-card-metadata.md) and [card tokenization results](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration/retrieve-card-tokenization-results.md). For more information, see [Extend your Flow for mobile integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/extend-your-flow-for-mobile-integration.md).

---

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

You can check the status of a payment from the _Payments_ > _Processing_ > _All payments_ page in the [Dashboard](https://dashboard.checkout.com).

> **Information**
>
> If Apple Pay is enabled on the customer's device but their wallet does not contain a card scheme or type that matches the schemes you passed to the SDK, Flow for mobile shows the _Setup Apple Pay_ button. If the customer then adds a new, unaccepted card, the button remains _Setup Apple Pay_. When the customer adds an accepted card, the button changes to _Pay_.

---

## Next steps

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

Learn how to customize Flow for mobile.

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

See the configuration options and error handling steps for Flow for mobile on iOS.