Pay with stored card details
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": true8},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": true8},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": true17},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}