> For a complete page index, fetch https://docs.transak.com/llms.txt

# Headless Apple Pay

**Headless Apple Pay** is a lightweight, embeddable UI module that allows partners to offer Apple Pay as a payment method directly within their own application without loading any widget.

## Watch: How Headless Apple Pay Works

A short walkthrough of Headless Apple Pay and how it embeds the Apple Pay flow directly inside your own app.

## Problem Statement

Currently, Transak requires loading the full widget for Apple pay, which forces users to go through multiple screens before reaching payment module. This creates friction and limits the partner control over the payment experience.

Here are some of the **key challenges** with the current approach:

<table>
  <tbody>
    <tr>
      <td>
        **Full widget required**

        Partners must load the entire Transak widget to confirm order with Apple pay as payment method.
      </td>
    </tr>

    <tr>
      <td>
        **Multiple screens before payment**

        Users navigate through several Transak screens before they ever see the Apple Pay button, increasing drop-off risk.
      </td>
    </tr>

    <tr>
      <td>
        **Disconnected payment experience**

        The payment flow feels separate from the partner's own UI, breaking the continuity.
      </td>
    </tr>

    <tr>
      <td>
        **Limited partner control**

        Partners have no control over when or where Apple Pay appears as placement and styling are determined by the widget.
      </td>
    </tr>
  </tbody>
</table>

## Our Solution

Headless Apple Pay exposes just the Apple Pay button as a standalone, embeddable component. Partners control where it sits, how it looks, and what happens after payment. Transak handles all the payment infrastructure in the background.

Here are some of the **key benefits** of the Headless Apple Pay solution:

<table>
  <tbody>
    <tr>
      <td>
        **Just the Apple Pay button**

        Embed only the Apple Pay button — no full widget required.
      </td>
    </tr>

    <tr>
      <td>
        **One tap to payment**

        Users see the Apple Pay button immediately and complete payment in a single tap, reducing drop-off.
      </td>
    </tr>

    <tr>
      <td>
        **Seamless checkout integration**

        The Apple Pay button sits inside the partner's own checkout UI, keeping the experience continuous.
      </td>
    </tr>

    <tr>
      <td>
        **Full partner control**

        Partners decide where the button appears, how it looks, and what happens after payment.
      </td>
    </tr>
  </tbody>
</table>

## How does it work?

![headless-apple-pay](https://files.buildwithfern.com/visual-editor-images/docs.transak.com/2026-07-06T06:51:18.275Z/features/headless-apple-pay/headless-apple-pay.png "headless-apple-pay")

## Current Limitations

<table>
  <thead>
    <tr>
      <th>
        Limitation
      </th>

      <th>
        Details
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Headless Apple Pay APIs ([Transaction Session API](/api/headless-apple-pay/transaction-session-api), [Create Order API](/api/headless-apple-pay/create-order-for-apple-pay), [Transaction Request Status API](/api/headless-apple-pay/transaction-request-status-api))**
      </td>

      <td>
        APIs are to be called only from the partner backend and subjected to the whitelisting of partner IP addresses. We don't support API calls from the frontend due to security restrictions.
      </td>
    </tr>

    <tr>
      <td>
        **No supported device detection**
      </td>

      <td>
        The module does not check whether the user's device supports Apple Pay. Partners must verify availability before loading the Transak UI SDK.
      </td>
    </tr>

    <tr>
      <td>
        **Apple pay availability**
      </td>

      <td>
        Apple Pay payments are only supported if the [Get Fiat Currencies API](/api/whitelabel/lookup/get-fiat-currencies) response includes payment method `apple_pay` for that particular fiat currency.
      </td>
    </tr>
  </tbody>
</table>

## How to integrate?

#### Whitelist Your API Key & Enable Headless Apple Pay

| Action                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------- |
| Follow the steps in the [Need help in Integration](/getting-started/help-and-support#need-help-in-integration) section |
| Request **API key whitelisting** and ask to **enable Headless Apple Pay** for your API key                             |
| Share your public IP addresses with Transak for whitelisting to use our APIs in your backend                           |

#### User Authentication

You can use either of the following authentication options:

| Option               | Description                                                                                                                                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **White-label Auth** | Use the standard Transak authentication flow to generate a user access token. Partners can do this by calling the [Send User OTP API](/api/whitelabel/user/send-user-otp) followed by the [Verify User API](/api/whitelabel/user/verify-user-otp) to generate the access token. Learn more  |
| **Auth Reliance**    | Use [Auth Reliance](/features/auth-reliance) by passing these headers with every request: `x-user-identifier` and `x-access-token`                                                                                                                                                          |

Please refer to the tutorial on [how to create partner access token](/guides/how-to-create-partner-access-token).

#### User KYC

KYC is a mandatory step in compliance with regulatory requirements. Each user should be

KYC Approved

. You can use either of the following KYC options:

| Option                      | Description                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **White label KYC**         | Partners can collect the required KYC information on their end and then forward it to Transak for review and approval. Learn more: [Whitelabel KYC](/integration/api#kyc) |
| **KYC Reliance via Sumsub** | Partners can share their KYC data from their platform with Transak using Sumsub. Learn more: [KYC Reliance Guide](/features/kyc-reliance#using-sumsub)                    |

#### Generate a quote using the Quote API

Call the [Get Quote API](https://docs.transak.com/api/whitelabel/lookup/get-quote) to get a quote for the transaction. Pass the `apiKey`, `fiatAmount`, `fiatCurrency`, `cryptoCurrency`, `network`, and `paymentMethod`.

Set `paymentMethod` to `apple_pay` while creating a quote.

A successful response returns a `quoteId`.

#### Create a transaction session (using Backend only)

Call the [Transaction Session API](/api/headless-apple-pay/transaction-session-api) from your backend using the `quoteId` and the user's wallet address. You can optionally pass a `config` object to customise the look and feel of the Apple Pay component.

A successful response returns a `sessionId`.

#### Load the Apple Pay Component via Transak UI SDK

Use the Transak UI SDK to render the Apple Pay component. Pass the `sessionId` received in previous Step.

#### JS

```bash
npm install @transak/ui-components
```

```typescript
import { createTransakApplePay } from ‘@transak/ui-components’;

const applePay = createTransakApplePay({
  sessionId, // sessionId from Previous Step
  environment, // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onSuccess: ({ requestId }) => {
    // Payment data captured — use requestId in the next step
  },
  onError: ({ code }) => {
    // Handle error
  },
});

await applePay.mount(‘checkout-slot’);
```

#### React

```bash
npm install @transak/ui-components-react
```

```tsx
import { TransakApplePay } from ‘@transak/ui-components-react’;

<TransakApplePay
  sessionId={sessionId} // sessionId from Previous Step
  environment={environment} // 'STAGING' | 'PRODUCTION'
  onReady={() => {
    // Component is ready
  }}
  onSuccess={({ requestId }) => {
    // Payment data captured — use requestId in the next step
  }}
  onError={({ code }) => {
    // Handle error
  }}
/>
```

#### React Native

```bash
npm install @transak/ui-components-rn
```

```tsx
import { TransakApplePay } from ‘@transak/ui-components-rn’;

<TransakApplePay
  sessionId={sessionId} // sessionId from Previous Step
  environment={environment} // ‘STAGING’ | ‘PRODUCTION’
  onReady={() => {
    // Component is ready
  }}
  onSuccess={({ requestId }) => {
    // Payment data captured — use requestId in the next step
  }}
  onError={({ code }) => {
    // Handle error
  }}
/>
```

##### Recommended implementation

The code snippet below wraps `TransakApplePay` in a view that supports dark/light mode, displays a loading spinner until the component is ready, and fades in a blur overlay when the Apple Pay sheet opens.

```tsx

{sessionId && !applePayErrorCode && (
  <View
    style={[
      styles.card,
      styles.applePayCard,
      {
        backgroundColor:
          applePayConfig.colorMode === ‘DARK’ ? ‘#000’ : ‘#fff’,
      },
    ]}
    // First touch on the Apple Pay button bubbles up here (the
    // WebView still consumes the press for its own click handler);
    // we use that as the trigger to fade the blur in, since the
    // SDK doesn’t expose a "sheet opened" event.
    onTouchStart={() => {
      if (isApplePayReady) setSheetActive(true);
    }}
  >
    <View style={styles.applePayFrame}>
      <TransakApplePay
        sessionId={sessionId}
        environment={environment} // ‘STAGING’ | ‘PRODUCTION’
        onReady={() => {
          setIsApplePayReady(true);
        }}
        onSuccess={(payload) => {
          void handlePaymentCaptured(payload.requestId);
        }}
        onError={(error) => {
          setApplePayErrorCode(error.code);
          setSheetActive(false);
        }}
      />
      {!isApplePayReady && (
        <View style={styles.applePayOverlay}>
          <ActivityIndicator size="small" color={tokens.primary} />
          <Text style={styles.loadingPillText}>Loading Apple Pay</Text>
        </View>
      )}
    </View>
  </View>
)}
```

| State variable      | Purpose                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `isApplePayReady`   | Set to `true` inside `onReady` — hides the loading overlay once the component has initialised     |
| `sheetActive`       | Set to `true` on the first touch — use this to fade in a blur/backdrop behind the Apple Pay sheet |
| `applePayErrorCode` | Populated inside `onError` — use it to conditionally hide the card and surface an error UI        |

\


##### SDK Error codes

The `onError` callback receives a `code` value. Use it to handle specific failure scenarios:

| Code                         | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `CONFIG_LOAD_FAILED`         | Apple Pay configuration could not be loaded  |
| `MERCHANT_VALIDATION_FAILED` | Merchant validation with Apple failed        |
| `PAYMENT_CAPTURE_FAILED`     | Apple Pay payment capture failed             |
| `INVALID_OPTIONS`            | Invalid or missing options passed to the SDK |
| `IFRAME_LOAD_FAILED`         | The embedded iframe failed to load           |
| `INVALID_STATE`              | SDK method called in an unexpected state     |

Here’s how the Apple Pay module appears :

#### Place the order (using Backend only)

Once the SDK fires `onSuccess` with a `requestId`, call the [Create Order API](/api/headless-apple-pay/create-order-for-apple-pay) from your backend using the `requestId` to complete the payment and create the order.

A successful response returns the full order details.

#### Track the \`requestId\` (using Backend only)

Call the [Transaction Request Status API](/api/headless-apple-pay/transaction-request-status-api) to check whether the request has been processed. Poll this endpoint after calling the [Create Order API](/api/headless-apple-pay/create-order-for-apple-pay) until the status reaches a terminal state.

Once you receive an `orderId`, use the [Get Order by ID](https://docs.transak.com/api/public/get-order-by-order-id) API to fetch full order details.

#### Test the integration in Sandbox

Apple Pay in Sandbox requires a **real Apple device** and a **Whitelisted Sandbox Apple ID**.

#### [How to Test Apple Pay in Sandbox](/guides/how-to-test-apple-pay-in-sandbox)

Follow the step-by-step guide to set up the Sandbox Apple ID, add a test card, and run an end-to-end test transaction.

## API Overview

#### [Transaction Session API](/api/headless-apple-pay/transaction-session-api)

Creates a transaction session using a quote ID and wallet address, returns a `sessionId` to initialise the Apple Pay component.

#### [Create Order API](/api/headless-apple-pay/create-order-for-apple-pay)

Places the order using the `requestId` returned by the SDK's onSuccess callback, completing the order creation.

#### [Transaction Request Status API](/api/headless-apple-pay/transaction-request-status-api)

Polls the status of the `requestId` until it reaches a terminal state.

## API Errors

#### Transaction Session API

| HTTP Status | Error Code | Message                                                                                                       |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| 401         | 1002       | Invalid or missing authentication token(Only for White-label Auth).                                           |
| 422         | 6002       | KYC is not approved. Please complete KYC before creating a session.                                           |
| 422         | 6003       | This feature is not enabled for your account. Please contact support.                                         |
| 422         | 6005       | Quote not found or could not be loaded.                                                                       |
| 500         | 6005       | Failed to create a session for the user.                                                                      |
| 400         | 2030       | Your account has been disabled. Please get in touch with us at [fraud@transak.com](mailto:fraud@transak.com). |
| 422         | 6006       | The provided wallet address is invalid for the selected cryptocurrency and network.                           |

#### Create Order API

| HTTP Status | Error Code | Message                                                                                                       |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| 422         | 4001       | Invalid wallet address. Please provide a valid wallet address to proceed.                                     |
| 422         | 4002       | Please complete your KYC to place an order.                                                                   |
| 422         | 4003       | Please upgrade your kyc to next level to proceed with this transaction.                                       |
| 422         | 4005       | Order exists.                                                                                                 |
| 422         | 4006       | Unable to create order.                                                                                       |
| 422         | 4013       | Minimum amount should be more than \{amount}.                                                                 |
| 422         | 4015       | Invalid payment method for currency combination.                                                              |
| 422         | 4016       | FCA criteria not met, Please complete the assessments.                                                        |
| 422         | 4021       | Something went wrong, try again later!                                                                        |
| 404         | 6007       | Request ID not found.                                                                                         |
| 422         | 6012       | KYC requirement is not approved for this transaction.                                                         |
| 422         | 6014       | Unable to process request. User location data is required for this transaction.                               |
| 400         | 2030       | Your account has been disabled. Please get in touch with us at [fraud@transak.com](mailto:fraud@transak.com). |
| 400         | 6010       | Unable to create user account.                                                                                |
| 500         | 6099       | Unable to process the order. Please try again.                                                                |

#### Transaction Request Status API

| HTTP Status | Error Code | Message               |
| ----------- | ---------- | --------------------- |
| 404         | 6007       | Request ID not found. |

## Interactive Demo

> Embed Apple Pay in your own interface without routing users through the Transak widget.