Headless Cards

Whitelist Your API Key & Enable Headless Cards

User Authentication

You can use either of the following authentication options:

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:

Generate a quote using the Quote API

Call the Get Quote API to get a quote for the transaction. Pass the apiKey, fiat amount, fiat currency, crypto currency, network, and order type.

A successful response returns a quoteId.

Check for saved cards (using Backend only)

Call the Get Saved Cards API to check whether the user has any previously saved credit/debit cards. A successful response returns a cards array.

Place order using the saved card (using Backend only)

If the user picks one of the saved cards, call the Create Order (with Saved Card) API from your backend using the quoteId, walletAddress, and the selected card’s paymentIdentifierId.

A successful response returns the full order details with redirectUrl. Continue with the Open the redirectUrl in a browser or WebView step below.

Create a transaction session (using Backend only)

Call the Transaction Session API from your backend using the quoteId, successUrl, failureUrl and the user’s wallet address. You can optionally pass a config and billingAddress object to customise the look and feel of the card component and billing details.

A successful response returns a sessionId.

Load the Card Component via Transak UI SDK

Use the Transak UI SDK to render the card payment component. Pass the sessionId received in the previous step.

npm install @transak/ui-components

import { createTransakCard } from '@transak/ui-components';
const card = createTransakCard({
  sessionId, // sessionId from previous step
  environment, // 'STAGING' | 'PRODUCTION'
  onReady: () => {
    // Component is ready
  },
  onChange: ({ isValid, errorCode }) => {
    // Fires on form-state changes
  },
  onSuccess: ({ requestId }) => {
    // Payment data captured — use requestId in the next step
  },
  onError: ({ code }) => {
    // Handle error
  },
});
await card.mount('checkout-slot');
card.submit(); // Partner-triggered tokenisation
// and then
card.unmount();

Error codes

The onChange callback fires repeatedly as the user types and receives isValid and an optional errorCode:

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

Place order using the new card (using Backend only)

Once the SDK fires onSuccess with a requestId, call the Create Order (with New Card) API from your backend using the requestId to complete the payment and create the order.

A successful response returns the full order details with redirectUrl. Continue with the Open the redirectUrl in a browser or WebView step below.

Track the requestId (using Backend only)

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

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

Open the redirectUrl in a browser or WebView

Open the redirectUrl returned in the previous step in the browser or webview to complete any 3DS or bank authentication required by the payment provider.

Upon completing the transaction, the user will be redirected to either the successUrl or failureUrl you passed in the Transaction Session API in case of a new card, or the Create Order (with Saved Card) API in case of a saved card.