Accept payments with stored card credentials

Last updated: September 29, 2025

With Vault, you can store your customers' payment card details as Payment instruments, which you can later reuse in future payments so they do not have to input their details every time they make a purchase.

Flow enables customers to store their card credentials in Vault during checkout. The next time the customer shops with you, we display their stored card details.

Stored card payments are available for the following integrations:

For new customers, call the Request a Payment Session and set the payment_method_configuration.card.store_payment_details field to collect_consent. This value displays the option to store card credentials for future payments. If you have already collected consent from the customer, you can provide payment_method_configuration.card.store_payment_details: "enabled" instead.

You must also provide either the customer.email or customer.id fields.

post

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


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "email": "[email protected]"
12  },
13  "payment_method_configuration": {
14    "card": {
15      "store_payment_details": "collect_consent"
16    }
17  },
18  "success_url": "https://example.com/payments/success",
19  "failure_url": "https://example.com/payments/failure"
20}


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "email": "[email protected]"
12  },
13  "payment_method_configuration": {
14    "card": {
15      "store_payment_details": "enabled"
16    }
17  },
18  "success_url": "https://example.com/payments/success",
19  "failure_url": "https://example.com/payments/failure"
20}


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}

Information

When you receive the payment ID for successful payment, you can call the Get payment details endpoint and provide the payment ID as the {id} path parameter. You can store the customer.id field for use in future payments.

You can provide the stored customer ID for a returning customer using the payment_method_configuration.stored_card.customer_id field when you Request a Payment Session.

Flow displays the card details stored for the customer to reuse, as well as the card verification value (CVV) if needed for payment.

Alternatively, if you already have payment instruments that are not stored under any customer, you can provide them using the payment_method_configuration.stored_card.instrument_ids field instead.


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "email": "[email protected]"
12  },
13  "payment_method_configuration": {
14    "card": {
15      "store_payment_details": "collect_consent"
16    },
17    "stored_card": {
18      "customer_id": "cus_qeoewolfowrexgjwvpjujgaize"
19    }
20  },
21  "success_url": "https://example.com/payments/success",
22  "failure_url": "https://example.com/payments/failure"
23}


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "email": "[email protected]"
12  },
13  "payment_method_configuration": {
14    "card": {
15      "store_payment_details": "collect_consent"
16    },
17    "stored_card": {
18      "instrument_ids": [
19        "src_7r7eitazpleuxeqk5eeo6elcni ",
20        "src_nts3p7anttkehivcfqady4pygi "
21      ],
22      "default_instrument_id": "src_7r7eitazpleuxeqk5eeo6elcni "
23    }
24  },
25  "success_url": "https://example.com/payments/success",
26  "failure_url": "https://example.com/payments/failure"
27}


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}

Some regions or card schemes, such as Mada, require the CVV when performing a stored card payment. Flow captures and tokenizes the CVV from the customer when such stored card details are selected.

Optionally, you can set the componentOptions.stored_card.captureCardCvv field to true when initializing CheckoutWebComponents to always capture CVV from the customer:


1// Insert your public key here
2const publicKey = '{YOUR_PUBLIC_KEY}';
3
4const checkout = await CheckoutWebComponents({
5  paymentSession,
6  publicKey,
7  environment: 'sandbox',
8  componentOptions: {
9    stored_card: {
10      captureCardCvv: true,
11    },
12  },
13});
14
15const flowComponent = checkout.create('flow');
16
17flowComponent.mount('#flow-container');

Accept payments with stored card credentials

Store card credentials

Request examples

Response example

Information

Display stored cards

Request examples

Response example

Capture CVV for stored card