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.

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

1
import { createTransakCard } from '@transak/ui-components';
2
3
const card = createTransakCard({
4
  sessionId, // sessionId from previous step
5
  environment, // 'STAGING' | 'PRODUCTION'
6
  onReady: () => {
7
    // Component is ready
8
  },
9
  onChange: ({ isValid, errorCode }) => {
10
    // Fires on form-state changes
11
  },
12
  onSuccess: ({ requestId }) => {
13
    // Payment data captured — use requestId in the next step
14
  },
15
  onError: ({ code }) => {
16
    // Handle error
17
  },
18
});
19
20
await card.mount('checkout-slot');
21
card.submit(); // Partner-triggered tokenisation
22
23
// and then
24
card.unmount();

Error codes

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

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

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.