Pay with stored card details

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.

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.

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.

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}


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}

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.


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.

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.

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.


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": true,
10  "3ds": {
11    "enabled": true,
12    "challenge_indicator": "no_challenge_requested"
13  }
14}

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 API response codes documentation.


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": "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}


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}

Recurring payments with stored card details

Learn how to request recurring payments with stored card details.

Unscheduled payments with stored card details

Learn how to request unscheduled payments with stored card details.

We've made some changes to our API

Pay with stored card details

Store card details

Note

SCA requirements

Request example

Information

Note

Response example

Request a payment with stored card details

SCA requirements

Note

Request example

Response example

Recurring payments with stored card details

Unscheduled payments with stored card details