Accept payments with stored card credentials

Last updated: October 14, 2026

With Vault, you can store your customers' payment card details as payment instruments. You can then reuse them in future payments, so customers do not have to enter their details each time they buy from you.

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:

Information

You can enable Remember Me alongside the stored card functionality to also make the cardholder's stored cards available for faster checkout with Remember Me. To enable Remember Me, contact your account manager or request support.

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

Also provide either customer.email or customer.id.

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  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "email": "jia.tsang@example.com"
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": "jia.tsang@example.com"
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://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

Information

After a successful payment, call the Get payment details endpoint providing the payment ID as the {id} path parameter. Store the returned customer.id value to use in future payments.

For a returning customer, provide their stored customer ID in payment_method_configuration.stored_card.customer_id when you request a payment session. Flow displays the card details stored for the customer, and collects the card verification value (CVV) if the payment needs it.

If you have payment instruments that are not stored under a customer, provide them in payment_method_configuration.stored_card.instrument_ids 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": "jia.tsang@example.com"
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": "jia.tsang@example.com"
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://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
8    }
9  }
10}

Some regions and card schemes, such as Mada, require the CVV for a stored card payment. When a customer selects such a card, Flow captures the CVV and converts it to a token.

To always capture the CVV, set componentOptions.stored_card.captureCardCvv to true when you initialize CheckoutWebComponents:


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');

By default, customers can pay with the cards you stored for them but cannot delete them. To let customers delete a stored card from the payment form, set componentOptions.stored_card.allowRemoveInstrument to true when you initialize CheckoutWebComponents:


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      allowRemoveInstrument: true,
11    },
12  },
13});
14
15const flowComponent = checkout.create('flow');
16
17flowComponent.mount('#flow-container');

You can set the option in any of the following places, and the most specific one takes precedence:

componentOptions.flow.allowRemoveInstrument – Applies to the stored cards shown in the Flow component.
componentOptions.stored_card.allowRemoveInstrument – Applies to all stored cards, as in the previous example.
checkout.create('stored_card', { allowRemoveInstrument: true }) – Applies to the options you pass when you create the stored card component.

Accept payments with stored card credentials

Information

Store card credentials

Information

Request examples

Response example

Information

Display stored cards

Request examples

Response example

Capture CVV for stored card

Enable customers to delete stored cards