Headless Apple Pay

Embed Apple Pay in your own interface without routing users through the Transak widget.
View as Markdown

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.

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:

Full widget required

Partners must load the entire Transak widget to confirm order with Apple pay as payment method.

Multiple screens before payment

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

Disconnected payment experience

The payment flow feels separate from the partner’s own UI, breaking the continuity.

Limited partner control

Partners have no control over when or where Apple Pay appears as placement and styling are determined by the widget.

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:

Just the Apple Pay button

Embed only the Apple Pay button — no full widget required.

One tap to payment

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

Seamless checkout integration

The Apple Pay button sits inside the partner’s own checkout UI, keeping the experience continuous.

Full partner control

Partners decide where the button appears, how it looks, and what happens after payment.

How does it work?

Headless Apple Pay

Current Limitations

LimitationDetails
Headless Apple Pay APIs (Transaction Session API, Transaction Process API, Transaction Request Status API)

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.

No supported device detection

The module does not check whether the user’s device supports Apple Pay. Partners must verify availability before loading the Transak UI SDK.

Supported only for React Native integrations

The Transak UI SDK is currently available for React Native only. Web-based integrations are not supported at the moment.

Transaction Process API may timeout

The Transaction Process API can take time to process a request. In case of an API timeout or server error, poll the Transaction Request Status API to retrieve the current status of the transaction request.

How to integrate?

1

Whitelist Your API Key & Enable Headless Apple Pay

Action
Follow the steps in the 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
2

User Authentication

You can use either of the following authentication options:

OptionDescription
White-label AuthUse the standard Transak authentication flow to generate a user access token. Partners can do this by calling the Send User OTP API followed by the Verify User API to generate the access token.

Learn more
Auth RelianceUse 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.

3

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:

OptionDescription
White label KYCPartners can collect the required KYC information on their end and then forward it to Transak for review and approval. Learn more: Whitelabel KYC
KYC Reliance via SumsubPartners can share their KYC data from their platform with Transak using Sumsub. Learn more: KYC Reliance Guide
4

Generate a quote using the Quote API

Call the Get Quote API 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.

5

Create a transaction session (using Backend only)

Call the 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.

6

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.

$npm install @transak/ui-components-rn
1import { TransakApplePay } from ‘@transak/ui-components-rn’;
2
3<TransakApplePay
4 sessionId={sessionId} // sessionId from Previous Step
5 environment={environment} // ‘STAGING’ | ‘PRODUCTION’
6 onReady={() => {
7 // Component is ready
8 }}
9 onSuccess={({ requestId }) => {
10 // Payment data captured — use requestId in the next step
11 }}
12 onError={({ code }) => {
13 // Handle error
14 }}
15/>

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.

1{sessionId && !applePayErrorCode && (
2 <View
3 style={[
4 styles.card,
5 styles.applePayCard,
6 {
7 backgroundColor:
8 applePayConfig.colorMode ===DARK? ‘#000: ‘#fff’,
9 },
10 ]}
11 // First touch on the Apple Pay button bubbles up here (the
12 // WebView still consumes the press for its own click handler);
13 // we use that as the trigger to fade the blur in, since the
14 // SDK doesn’t expose a "sheet opened" event.
15 onTouchStart={() => {
16 if (isApplePayReady) setSheetActive(true);
17 }}
18 >
19 <View style={styles.applePayFrame}>
20 <TransakApplePay
21 sessionId={sessionId}
22 environment={environment} // ‘STAGING’ | ‘PRODUCTION’
23 onReady={() => {
24 setIsApplePayReady(true);
25 }}
26 onSuccess={(payload) => {
27 void handlePaymentCaptured(payload.requestId);
28 }}
29 onError={(error) => {
30 setApplePayErrorCode(error.code);
31 setSheetActive(false);
32 }}
33 />
34 {!isApplePayReady && (
35 <View style={styles.applePayOverlay}>
36 <ActivityIndicator size="small" color={tokens.primary} />
37 <Text style={styles.loadingPillText}>Loading Apple Pay</Text>
38 </View>
39 )}
40 </View>
41 </View>
42)}
State variablePurpose
isApplePayReadySet to true inside onReady — hides the loading overlay once the component has initialised
sheetActiveSet to true on the first touch — use this to fade in a blur/backdrop behind the Apple Pay sheet
applePayErrorCodePopulated 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:

CodeDescription
CONFIG_LOAD_FAILEDApple Pay configuration could not be loaded
MERCHANT_VALIDATION_FAILEDMerchant validation with Apple failed
PAYMENT_CAPTURE_FAILEDApple Pay payment capture failed
INVALID_OPTIONSInvalid or missing options passed to the SDK
IFRAME_LOAD_FAILEDThe embedded iframe failed to load
INVALID_STATESDK method called in an unexpected state

Here’s how the Apple Pay module appears :

Apple Pay - Embed UI
7

Process the payment with requestId (using Backend only)

Once the SDK fires onSuccess with a requestId, call the Transaction Process API from your backend to complete the payment and create the order.

A successful response returns the full order details.

8

Track the requestId (using Backend only)

Call the Transaction Request Status API to check whether the request has been processed. Poll this endpoint after calling the Transaction Process API until the status reaches a terminal state.

Once you receive an orderId, use the Get Order by ID API to fetch full order details.

API Overview

API Errors

HTTP StatusError CodeMessage
4011002Invalid or missing authentication token(Only for White-label Auth).
4226002KYC is not approved. Please complete KYC before creating a session.
4226003This feature is not enabled for your account. Please contact support.
4226005Quote not found or could not be loaded.
5006005Failed to create a session for the user.
4002030Your account has been disabled. Please get in touch with us at fraud@transak.com.
4226006The provided wallet address is invalid for the selected cryptocurrency and network.
HTTP StatusError CodeMessage
4224001Invalid wallet address. Please provide a valid wallet address to proceed.
4224002Please complete your KYC to place an order.
4224003Please upgrade your kyc to next level to proceed with this transaction.
4224005Order exists.
4224006Unable to create order.
4224013Minimum amount should be more than {amount}.
4224015Invalid payment method for currency combination.
4224016FCA criteria not met, Please complete the assessments.
4224021Something went wrong, try again later!
4046007Request ID not found.
4226012KYC requirement is not approved for this transaction.
4002030Your account has been disabled. Please get in touch with us at fraud@transak.com.
5006099Unable to process the order. Please try again.
HTTP StatusError CodeMessage
4046007Request ID not found.

Interactive Demo (Login + Existing user flow)