Tokenize credentials

Last updated: March 12, 2025

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, one-time 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 test account with Checkout.com.

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

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

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

Call the following endpoint with your secret key:

post

https://api.checkout.com/payment-sessions

For the full API specification, see the API reference.


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": "[email protected]"
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://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://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: "[email protected]",
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://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: "[email protected]",
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 via a script:


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

Note

To remain PCI compliant, you should 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.

Include the Flow dependency in 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 triggered:


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 triggered:


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 will trigger the card tokenization:


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

Use the tokenize() method to trigger 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 trigger the card tokenization.


1// Trigger tokenization if you created a Card component
2cardComponent.tokenize()
3
4// Trigger 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 trigger the card tokenization.


1// Trigger tokenization if you created a Card component
2cardComponent.tokenize()
3
4// Trigger 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.

Forward stored credentials

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

Standalone sessions

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

Tokenize credentials

Before you start

Create a Payment Session
Server side

Request example

Response example

Initialize and mount Flow
Client side

Note

Note

Tokenize the card details
Client side

Next steps

Forward stored credentials

Standalone sessions

Before you start

Create a Payment Session Server side

Request example

Response example

Initialize and mount Flow Client side

Note

Note

Tokenize the card details Client side

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