Skip to content

Last updated: February 15, 2023

If a customer requests to store their card during a transaction, you can use the saved details to perform future payments without requiring them to input their details again.


Store card details

To enable one-click payments, or to avoid having to input their card details again for future payments, a customer may request to save their card details during a cardholder-initiated transaction (CIT).

To provide a seamless experience in these scenarios, store_for_future_use is set to true by default.

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 a payment_type field set to Regular, and a merchant_initiated field set to false.

SCA requirements

In Strong Customer Authentication (SCA) mandated regions, you must enable 3D Secure (3DS) authentication for the transaction by setting 3ds.enabled to true. If the transaction qualifies, you can also make use of 3DS exemptions.

Request example

post

https://api.checkout.com/payments

Information

SAQ D and SAQ A are, respectively, the highest and lowest forms of PCI compliance. Learn more about 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
}

Note

When the store_for_future_use flag is set to true, the transaction is flagged to the scheme as an action to add the card.

Response example

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
}

Use the /payments/{id} endpoint to retrieve the payment details and use the source.id value returned in the response in future payment requests.


Request a payment with stored card details

If your customer pays with a saved card or uses a one-click payment option, you can use the card's source.id instead of the full card details in the payment request.

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

If you are SAQ D PCI-compliant and have stored the full card details for any payment type, you must set source.stored to true in the request.

If you are SAQ A compliant, and used a token or a source ID to request a payment, you do not need to include any additional fields.

SCA requirements

In Strong Customer Authentication (SCA) mandated regions, you must enable 3D Secure authentication for the transaction by setting 3ds.enabled to true. If the transaction qualifies, you can also make use of 3DS exemptions.

Note

If you do not supply the required information, your request has a higher risk of being declined with a 20154 response code. If this happens, we automatically upgrade the payment to 3DS and retry the transaction.

See our SCA compliance guide for more information.

Request example

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
}

The response returns an approved field with true if authorization was successful, or false if unsuccessful, along with a payment status.

Authorization may fail if:

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

Payment requests sent with 3D Secure will return a 202 response, meaning the payment requires a redirect.

For more information on the various codes returned in the response, see our CVV codes, AVS codes, and response codes documentation.

Response example

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": "johnsmith@example.com",
39
"name": "John Smith"
40
},
41
"processed_on": "2019-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
}