Pay with stored card details

Customers can request to store their card details during a payment, which you can then use for future payments without customers having to re-enter the details.

Information

Only you can access credentials stored in the Vault.

Customer details saved using Remember Me can be accessed by all merchants with Remember Me enabled, regardless of which merchant the customer saved them with.

You can use Remember Me to provide faster checkout for your customers with the Flow, Flow for mobile, Hosted Payments Page, and Payment Links solutions.

During a cardholder-initiated transaction (CIT), a customer may request to save their card details. This enables one-click payments and avoids the customer having to re-enter their details for subsequent payments.

To provide a seamless experience in these scenarios, the store_for_future_use field in payment requests is set to true by default. The payment is flagged to the card scheme as an action to add the card.

Note

To prevent card details from being stored, you must explicitly set "store_for_future_use": false in the payment request.

The payment request must also include the following:

payment_type field set to Regular
merchant_initiated field set to false

In regions that require Strong Customer Authentication (SCA), you must apply 3D Secure (3DS) authentication to payments by setting 3ds.enabled to true. For eligible payments, you can also use 3DS exemptions.

post

https://api.checkout.com/payments

Information

SAQ D and SAQ A are, respectively, the highest and lowest forms of PCI compliance.


1{
2  "source": {
3    "type": "card",
4    "number": 4242424242424242,
5    "expiry_month": 10,
6    "expiry_year": 2026,
7    "store_for_future_use": true
8  },
9  "amount": 5000,
10  "currency": "USD",
11  "payment_type": "Regular",
12  "merchant_initiated": false,
13  "3ds": {
14    "enabled": true,
15    "challenge_indicator": "challenge_requested"
16  }
17}


1{
2  "source": {
3    "type": "token",
4    "token": "tok_tokenguid",
5    "store_for_future_use": true
6  },
7  "amount": 5000,
8  "currency": "USD",
9  "payment_type": "Regular",
10  "merchant_initiated": false,
11  "3ds": {
12    "enabled": true,
13    "challenge_indicator": "challenge_requested"
14  }
15}


1{
2  "id": "pay_4hlqceyyib5ezpxtpdpwfhwtda",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "3ds": {
6    "downgraded": false,
7    "enrolled": "Y"
8  },
9  "_links": {
10    "self": {
11      "href": "https://api.sandbox.checkout.com/payments/pay_4hlqceyyib5ezpxtpdpwfhwtda"
12    },
13    "actions": {
14      "href": "https://api.sandbox.checkout.com/payments/pay_4hlqceyyib5ezpxtpdpwfhwtda/actions"
15    },
16    "redirect": {
17      "href": "https://api.sandbox.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
18    }
19  }
20}

Call the Get payment details endpoint and use the source.id value returned in the response in subsequent payment requests.

When the customer next pays with a saved card or uses a one-click payment option, provide the card's source.id instead of the full card details in the payment request.

The payment request must also include the payment_type field set to Regular.

If you are:

SAQ D PCI compliant and have stored the full card details for any payment type – Set source.stored to true.
SAQ A compliant and use a token or a source ID to request the payment – You do not need to provide any additional fields.

In regions that require SCA, you must set 3ds.enabled to true. For eligible payments, you can use 3DS exemptions.

Note

If you do not provide the required information, your request has a higher risk of being declined with a 20154 response code. Checkout.com automatically upgrades the payment to 3DS and retries the payment.


1{
2  "source": {
3    "type": "card",
4    "number": 4242424242424242,
5    "expiry_month": 10,
6    "expiry_year": 2026,
7    "stored": true
8  },
9  "amount": 5000,
10  "currency": "USD",
11  "payment_type": "Regular",
12  "3ds": {
13    "enabled": true,
14    "challenge_indicator": "no_challenge_requested"
15  }
16}


1{
2  "source": {
3    "type": "id",
4    "id": "src_instrumentguid"
5  },
6  "amount": 5000,
7  "currency": "USD",
8  "payment_type": "Regular",
9  "merchant_initiated": false,
10  "3ds": {
11    "enabled": true,
12    "challenge_indicator": "no_challenge_requested"
13  }
14}

The response returns the payment status and an approved field with one of the following values:

true – Authorization was successful.
false – Authorization was unsuccessful.

Authorization may fail if:

The card was invalid or expired.
The card was valid but had insufficient funds.
The payment was not permitted for the cardholder.
The payment was flagged for suspected fraud.

Payment requests with 3D Secure enabled return a 202 response. This means the payment requires a redirect.

For more information on the codes that can be returned in the response, see CVV response codes, AVS codes, and API response codes.


1{
2  "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6540,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "id": "src_y4pwpefkykre7ijbeyxjsxdkf4",
20    "type": "card",
21    "billing_address": {
22      "address_line1": "123 High St.",
23      "address_line2": "Flat 456",
24      "city": "London",
25      "zip": "SW1A 1AA",
26      "country": "GB"
27    },
28    "phone": {
29      "country_code": "+1",
30      "number": "415 555 2671"
31    },
32    "last4": "4242",
33    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
34    "bin": "424242"
35  },
36  "customer": {
37    "id": "cus_udst2tfldj6upmye2reztkmm4i",
38    "email": "[email protected]",
39    "name": "John Smith"
40  },
41  "processed_on": "2024-09-10T10:11:12Z",
42  "reference": "ORD-5023-4E89",
43  "processing": {
44    "retrieval_reference_number": "909913440644",
45    "acquirer_transaction_id": "440644309099499894406"
46  },
47  "eci": "06",
48  "scheme_id": "489341065491658",
49  "links": {
50    "self": {
51      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
52    },
53    "action": {
54      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
55    },
56    "void": {
57      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
58    },
59    "capture": {
60      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
61    }
62  }
63}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "John Smith"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "_links": {
15    "self": {
16      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
17    },
18    "redirect": {
19      "href": "https://api.sandbox.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4"
20    }
21  }
22}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Pay with stored card details

Information

Store the card details

Note

SCA requirements

Request example

Information

Response example

Request a payment with stored card details

SCA requirements

Note

Request example

Response example

Related topics

Recurring payments with stored card details

Unscheduled payments with stored card details

Pay with tokenized CVV