Tokenize credentials

Last updated: May 20, 2026

You can use Flow and Flow for mobile to securely collect and tokenize card details without going through the complete payment flow.

You receive a single-use token that you can use to:

Forward to a third-party payment service provider (PSP).
Request 3D Secure (3DS) authentication in a standalone session.

Make sure you have a Checkout.com test account.

Create a public key and a secret key in the Dashboard, with the following key scopes:

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

Create a Payment Session.
Initialize and mount Flow.
Tokenize the card details.

Send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle the card tokenization.

Call the Request a Payment Session endpoint with your secret key:

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.

post

https://{prefix}.api.checkout.com/payment-sessions


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "display_name": "Online shop",
6  "billing": {
7    "address": {
8      "country": "GB"
9    }
10  },
11  "customer": {
12    "name": "Jia Tsang",
13    "email": "jia.tsang@example.com"
14  },
15  "success_url": "https://example.com/payments/success",
16  "failure_url": "https://example.com/payments/failure"
17}


1{
2  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
3  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
4  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
5  "_links": {
6    "self": {
7      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

Send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle the card tokenization.


1const createPaymentSession = async (req, res) => {
2  const response = await fetch("https://{prefix}.api.checkout.com/payment-sessions", {
3    method: "POST",
4    headers: {
5      Authorization: `Bearer ${secretKey}`,
6      "Content-Type": "application/json",
7    },
8    body: JSON.stringify({
9      amount: 1000,
10      currency: "GBP",
11      reference: "ORD-123A",
12      display_name: "Online Shop",
13      billing: {
14        address: { country: "GB" },
15      },
16      customer: {
17        name: "Jia Tsang",
18        email: "jia.tsang@example.com",
19      },
20      success_url: "https://example.com/payments/success",
21      failure_url: "https://example.com/payments/failure",
22    }),
23  });
24
25  const paymentSession = await response.json();
26  res.json(paymentSession);
27};

Send a server-side request to securely create a PaymentSession object. The PaymentSession contains the information required to handle the card tokenization.


1const createPaymentSession = async (req, res) => {
2  const response = await fetch("https://{prefix}.api.checkout.com/payment-sessions", {
3    method: "POST",
4    headers: {
5      Authorization: `Bearer ${secretKey}`,
6      "Content-Type": "application/json",
7    },
8    body: JSON.stringify({
9      amount: 1000,
10      currency: "GBP",
11      reference: "ORD-123A",
12      display_name: "Online Shop",
13      billing: {
14        address: { country: "GB" },
15      },
16      customer: {
17        name: "Jia Tsang",
18        email: "jia.tsang@example.com",
19      },
20      success_url: "https://example.com/payments/success",
21      failure_url: "https://example.com/payments/failure",
22    }),
23  });
24
25  const paymentSession = await response.json();
26  res.json(paymentSession);
27};

Install the @checkout.com/checkout-web-components package via npm:


1npm install @checkout.com/checkout-web-components --save

Alternatively, load the package directly using a script:


1<script src="https://checkout-web-components.checkout.com/index.js" />

Note

To remain PCI compliant, only ever load the script directly from https://checkout-web-components.checkout.com. Do not download or host the script yourself, or include it in a bundle.

Use CheckoutWebComponents to create a card object:


1const cardComponent = checkout.create('card', {
2  showPayButton: false,
3});

Check that the card component is available and mount it:


1if (await cardComponent.isAvailable()) {
2  cardComponent.mount('#card-container');
3}

Note

Embedding Flow within an iframe or onto a Shadow DOM is not supported.

Add the Flow dependency to your app:


1// app gradle file
2implementation("com.checkout:checkout-android-components:<latest_version>")
3
4// project gradle file
5repositories {
6    mavenCentral()
7}

Configure Flow with your public key and the payment session data returned from the server.

You must also provide the onTokenized callback in the configuration to receive tokens from Flow.


1val config = CheckoutComponentConfiguration(
2  context = context,
3  paymentSession = paymentSessionResponse,
4  publicKey = PUBLIC_KEY,
5  environment = Environment.PRODUCTION,
6  componentCallback = ComponentCallback(
7    onTokenized = { tokenDetails ->
8      handleTokenDetails(tokenDetails);
9    }
10  )
11)
12
13CoroutineScope(Dispatchers.IO).launch {
14  try {
15    val checkoutComponents = CheckoutComponentsFactory(config).create()
16  } catch (checkoutError: CheckoutError) {
17    handleError(checkoutError)
18  }
19}

Create a card component to capture the card details:


1val cardComponent = checkoutComponents.create(
2    componentName = PaymentMethodName.Card,
3)

Alternatively, you can create a card component and hide the built-in payment button if you want to control when the tokenization is initiated:


1// Create a Card component without the built-in payment button
2val cardComponent = checkoutComponents.create(
3    componentName = PaymentMethodName.Card,
4    specificOptions = ComponentOption(showPayButton = false)
5)
6
7// Alternatively, create a Flow component without the built-in payment button
8val flowComponent = checkoutComponents.create(
9    componentName = ComponentName.Flow,
10    specificOptions = ComponentOption(showPayButton = false)
11)

Check that the card component is available and mount it:


1// Check that Card component is available before mounting
2if (cardComponent.isAvailable()) {
3  // Render in Compose
4  cardComponent.Render()
5
6  // Render in a container View
7  cardComponent.provide(containerView)
8}

In Xcode, go to Project > Package Dependencies and add https://github.com/checkout/checkout-ios-components.

Configure Flow with your public key and the payment session data returned from the server:

You must also provide the onTokenized callback in the configuration to receive tokens from Flow.


1import CheckoutComponentsSDK 
2
3let configuration = try await CheckoutComponents.Configuration(
4  paymentSession: paymentSession,
5  publicKey: publicKey,
6  environment: environment,
7  callbacks: .init(
8    onSuccess: { paymentMethod, paymentID in
9      // Handle success
10    },
11    onError: { error in
12      // Handle error
13    },
14    onTokenized: { token in
15      handleToken(token)
16    }
17  )
18)
19
20// Initialize the Flow for mobile payment component:
21try checkoutComponentsSDK.create(.flow())

Create a card component to capture the card details:


1let componentsSDK = CheckoutComponents(configuration: configuration)
2let component = componentsSDK.create(.card())

Alternatively, you can create a card component and hide the built-in payment button if you want to control when the tokenization is initiated:


1// Create a Card component without the built-in payment button
2let cardComponent = componentsSDK.create(.card(showPayButton: false))
3
4// Alternatively, create a Flow component without the built-in payment button
5let flowComponent = componentsSDK.create(.flow(options: [
6    .card(showPayButton: false)
7]))

Check that the card component is available and mount it:


1if component.isAvailable { 
2  component.render()
3}

Display a submit button that initiates the card tokenization:


1<div id="card-container"></div>
2<button id="card-pay-button" type="button">Pay</button>

Use the tokenize() method to initiate card tokenization.

The tokenization response is returned as the data object. You can access the generated card token within the data.token property.


1const cardPayButton = document.getElementById('card-pay-button');
2
3cardPayButton.addEventListener('click', async () => {
4  const { data } = await cardComponent.tokenize();
5
6  await utilizeToken(data.token);
7});

If you did not hide the built-in payment button when you created the card component, the card details are tokenized when the customer taps the payment button.

If you hid the built-in payment button, call the tokenize() method to initiate the card tokenization.


1// Initiate tokenization if you created a Card component
2cardComponent.tokenize()
3
4// Initiate tokenization if you created a Flow component
5flowComponent.tokenize()

Use the onTokenized event handler you passed in the Flow configuration to handle the card token string.

If you did not hide the built-in payment button when you created the card component, the card details are tokenized when the customer taps the payment button.

If you hid the built-in payment button, call the tokenize() method to initiate the card tokenization.


1// Initiate tokenization if you created a Card component
2cardComponent.tokenize()
3
4// Initiate tokenization if you created a Flow component
5flowComponent.tokenize()

Use the onTokenized event handler you passed in the Flow configuration to handle the card token string.

You can retrieve the details of an active token without consuming it. The token remains usable after retrieving its' metadata.

Call the Get token metadata endpoint, and provide the token ID as the {tokenId} path parameter.

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.

get

https://{prefix}.api.checkout.com/tokens/{tokenId}/metadata


1{
2  "token": "tok_4gzeau5o2uqubbk6fudbloo47a",
3  "type": "card",
4  "expires_on": "2026-05-14T10:11:12Z",
5  "expiry_month": 12,
6  "expiry_year": 2030,
7  "scheme": "Visa",
8  "last4": "4242",
9  "bin": "424242",
10  "card_type": "CREDIT",
11  "card_category": "CONSUMER",
12  "issuer": "Test Bank",
13  "issuer_country": "US",
14  "product_id": "A",
15  "product_type": "Visa Traditional",
16  "billing_address": {
17    "city": "Anytown",
18    "country": "US"
19  }
20}

Forward stored credentials

Forward the token to a third-party payment services provider (PSP).

Standalone sessions

Use the token to request 3D Secure authentication in a standalone session.

Tokenize credentials

Before you start

How it works

Create a Payment Session
Server side

Information

Request example

Response example

Initialize and mount Flow
Client side

Note

Note

Tokenize the card details
Client side

Get token metadata

Information

Response example

Next steps

Forward stored credentials

Standalone sessions

Before you start

How it works

Create a Payment Session Server side

Information

Request example

Response example

Initialize and mount Flow Client side

Note

Note

Tokenize the card details Client side

Get token metadata

Information

Response example

Next steps

Forward stored credentials

Standalone sessions

Create a Payment Session
Server side

Initialize and mount Flow
Client side

Tokenize the card details
Client side