Retrieve wallet tokenization results

Last updated: September 23, 2026

By default, the applepay and googlepay components submit a payment after the customer authorizes it in their wallet. To retrieve a Checkout.com token for the authorized wallet payment without submitting a payment, set the component to tokenize mode. In tokenize mode, the component exchanges the wallet token for a Checkout.com token and returns it through the onTokenized event, without submitting a payment. For example, you can use this token to request the payment from your server through the Payments API.

Information

Follow the Apple Pay and Google Pay Flow guides before you update your integration with the steps outlined on this page.

Note

This feature is not available in Kuwait and Qatar.

Tokenize mode is only available for the applepay and googlepay components.

Set mode to tokenize in the component options when you create the component. The default value is pay, which submits a payment after the customer authorizes it.


1// Component creation
2const applepayComponent = checkout.create('applepay', {
3  mode: 'tokenize',
4  onTokenized,
5});
6
7const googlePayComponent = checkout.create('googlepay', {
8  mode: 'tokenize',
9  onTokenized,
10});

To display the amount and currency in the wallet's payment screen, you must provide a paymentSession.

Set mode in componentOptions when you initialize CheckoutWebComponents.


1const checkout = await CheckoutWebComponents({
2  publicKey: 'pk_01234',
3  paymentSession,
4  environment: 'sandbox',
5  componentOptions: {
6    applepay: { mode: 'tokenize' },
7    googlepay: { mode: 'tokenize' },
8  },
9  onTokenized,
10});

The onTokenized event triggers when the customer authorizes the payment in their wallet and the wallet token is exchanged for a Checkout.com token. You must configure the onTokenized event when the component is in tokenize mode. If you do not, the component does not tokenize the payment and returns an on_tokenized_callback_required error through the onError event.

Implement the event logic to provide the tokenization result to your server-side integration:


1const onTokenized = async (self, tokenizeResult) => {
2  // tokenizeResult.type is 'applepay' or 'googlepay'
3  // Provide the token details to your server-side integration
4  await sendTokenToYourServer(tokenizeResult.data);
5};

The tokenizeResult object contains the following information:

type – The component that produced the result – Either applepay or googlepay.
data.token – The Checkout.com token. Use it to request a payment through the Payments API.
data.expires_on – The date and time the token expires, as an ISO 8601 timestamp.

data also contains the other fields returned by the Create a token endpoint, such as the underlying card's scheme, last four digits, and expiry date, if available.


1{
2  "type": "googlepay",
3  "data": {
4    "type": "googlepay",
5    "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
6    "expires_on": "2026-08-12T10:15:00Z",
7    "expiry_month": 6,
8    "expiry_year": 2028,
9    "scheme": "VISA",
10    "last4": "4242",
11    "bin": "424242"
12  }
13}

Unlike card tokenization, Flow does not use the return value of the onTokenized event in tokenize mode. There is no payment to cancel, and the wallet's payment screen completes with a success state when the token is created. Returning { continue: false } has no effect.

In tokenize mode, the component does not submit a payment. As a result:

The onPaymentCompleted and handleSubmit events do not trigger.
The wallet's payment screen closes with a success state once the token is created. The onTokenized event confirms that tokenization succeeded.
If the tokenization request fails, the component returns a tokenize_request_failed error through the onError event, and the wallet's payment screen shows a declined state.

Provide the token to your server-side integration and use it to request a payment with a source.type of token:


1{
2  "source": {
3    "type": "token",
4    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
5  },
6  "amount": 6540,
7  "currency": "USD",
8  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq"
9}

Information

Tokens are single use and expire after a short period of time. Request the payment before the time given in expires_on.

Retrieve wallet tokenization results

Information

Note

Enable tokenize mode
Client side

Add the onTokenized event
Client side

Result example

Handle the wallet tokenization result
Client side

Use the wallet token
Server side

Information

Information

Note

Enable tokenize mode Client side

Add the onTokenized event Client side

Result example

Handle the wallet tokenization result Client side

Use the wallet token Server side

Information

Enable tokenize mode
Client side

Add the onTokenized event
Client side

Handle the wallet tokenization result
Client side

Use the wallet token
Server side