Authenticate payments

This guide will show you how to integrate 3D Secure (3DS) into your payment flows.

Information

We support all versions of the 3DS protocol up to and including 2.2.0.

You can authenticate online payments using any of the following integration options:

If you use integrated authentication, you can also leverage Google Secure Payment Authentication (SPA). Google SPA enables cardholders to complete biometric authentication directly from the merchant's domain, providing an enhanced user experience.

With the integrated authentication solution, Checkout.com will automatically route the customer to a 3DS or Google SPA authentication experience, depending on which is most likely to result in a successful completion. For the automatic routing to function, you must provide 3DS authentication data in all of your payment requests.

If the initial authentication experience fails or is declined by the customer, we automatically fall back to the alternative authentication experience to prevent a lost transaction.

When you submit a payment request with the 3ds.enabled field set to true, we'll redirect the customer to a Checkout.com page to gather the data required for 3DS authentication. We'll automatically add the required fields to your payment request.

If you host the payment page in an iframe, you must explicitly add payment permission to the iframe to allow payments to complete. Include the allow="payment *" attribute in all parent frames:


1<iframe src="https://example.com" allow="payment *"></iframe>

Exchange the customer's card details for a card token using the

post

/tokens endpoint.

When you have the card token, you can request a payment using the

post

/payments endpoint.

To request 3DS authentication for the card token payment, set the 3ds.enabled field in your request to true.

Information

You can choose to automatically downgrade your payment to a non-3DS payment if there are any technical issues during the 3DS authentication process that would otherwise cause the payment to fail. To do this, set the attempt_n3d field in your request to true and we'll automatically attempt to process the payment without 3DS authentication.


1{
2  "source": {
3    "type": "token",
4    "token": "tok_f6z4mnoububudpqnvhwa5ff27u"
5  },
6  "amount": 2000,
7  "currency": "USD",
8  "3ds": {
9    "enabled": true
10  },
11  "success_url": "https://example.com/payments/success",
12  "failure_url": "https://example.com/payments/failure"
13}

Information

Use our test cards in the sandbox environment to simulate 3DS and Google SPA authentication flows, and test transactions statuses.

If the card is enrolled for 3DS or eligible for Google SPA, you'll receive a 202 - Accepted response.

Redirect the customer to the URL returned in the previous response's _links.redirect.href field.


1{
2  "id": "pay_hehfmlkpykeupofyxf7nbr6yyy",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_u4a4zosnrw7ehhzr7jipbkdzo4"
6  },
7  "3ds": {
8    "downgraded": false,
9    "enrolled": "Y"
10  },
11  "_links": {
12    "self": {
13      "href": "https://api.sandbox.checkout.com/payments/pay_hehfmlkpykeupofyxf7nbr6yyy"
14    },
15    "redirect": {
16      "href": "https://api.sandbox.checkout.com/sessions-interceptor/sid_feixbit6us3utfedjulm6egnsu"
17    }
18  }
19}

In a 3DS authentication experience the customer may be prompted to verify their identity on a 3DS challenge screen. For example, using a password.

In a Google SPA authentication experience the customer will be prompted to verify their identity on their device using biometric authentication.

If the customer successfully completes the 3DS challenge or Google SPA biometric authentication, they will be redirected back to your site.

The success URL will contain a cko-session-id query string. For example:

http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q

If you've subscribed to webhook notifications, you can verify the status of the payment via webhooks:

if the payment was successful, you'll receive a payment_approved webhook
if the payment was unsuccessful, you'll receive a payment_declined webhook

Alternatively, you can verify whether the payment was authenticated and authorized by calling the

get

Get payment details endpoint.

Use the cko-session-id query string from the previous step as the {id} path parameter of the request.

get

https://api.checkout.com/payments/{id}

Check the 3ds.authentication_response field to see the result of the 3DS authentication. It will be one of the following values:

Y – Cardholder was successfully authenticated.
A – Authentication was processed by a stand-in service, and is classed as successful.
N – Authentication failed.
U – Authentication could not be completed owing to technical or other problems.

Check the approved field to see whether or not the authorization was successful ("approved": true). If the authorization was unsuccessful, the card might be invalid/expired, or have an insufficient balance.

Information

To view a summary of all of the actions performed during a payment's lifecycle, use the

get

Get payment actions endpoint.


1{
2  "id": "pay_5o3zluz2oh2u7gbonujy33765e",
3  "requested_on": "2024-01-23T14:45:55.1258Z",
4  "source": {
5    "type": "card",
6    "expiry_month": 12,
7    "expiry_year": 2029,
8    "name": "Jia Tsang",
9    "scheme": "Visa",
10    "last4": "6584",
11    "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
12    "bin": "448504",
13    "card_type": "CREDIT",
14    "card_category": "COMMERCIAL",
15    "issuer": "GE CAPITAL FINANCIAL, INC.",
16    "issuer_country": "US"
17  },
18  "amount": 100,
19  "currency": "EUR",
20  "payment_type": "Regular",
21  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
22  "status": "Pending",
23  "3ds": {
24    "downgraded": false,
25    "enrolled": "Y",
26    "version": "2.2.0"
27  },
28  "risk": {
29    "flagged": false,
30    "score": 0
31  },
32  "customer": {
33    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
34    "email": "[email protected]",
35    "name": "Jia Tsang"
36  },
37  "_links": {
38    "self": {
39      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e"
40    },
41    "actions": {
42      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/actions"
43    },
44    "redirect": {
45      "href": "https://api.checkout.com/sessions-interceptor/sid_6jih2nadzfvevi655gysadzkyq"
46    }
47  }
48}


1{
2  "id": "pay_5o3zluz2oh2u7gbonujy33765e",
3  "requested_on": "2024-01-23T14:45:55.1258Z",
4  "source": {
5    "id": "src_aqqoqgffnbqehoqekvttwfrr3a",
6    "type": "card",
7    "expiry_month": 12,
8    "expiry_year": 2029,
9    "name": "Jia Tsang",
10    "scheme": "Visa",
11    "last4": "6584",
12    "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
13    "bin": "448504",
14    "card_type": "CREDIT",
15    "card_category": "COMMERCIAL",
16    "issuer": "GE CAPITAL FINANCIAL, INC.",
17    "issuer_country": "US",
18    "product_type": "PURCHASING",
19    "avs_check": "G",
20    "cvv_check": "Y",
21    "payment_account_reference": "V001345447391180899"
22  },
23  "expires_on": "2024-01-24T14:46:26.6329548Z",
24  "amount": 100,
25  "currency": "EUR",
26  "payment_type": "Regular",
27  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
28  "status": "Authorized",
29  "approved": true,
30  "3ds": {
31    "downgraded": false,
32    "enrolled": "Y",
33    "authentication_response": "Y",
34    "cryptogram": "AAABAVIREQAAAAAAAAAAAAAAAAA=",
35    "xid": "347d50f2-c903-4a6a-a3dd-e9b1200f2ac4",
36    "version": "2.2.0",
37    "exemption": "none",
38    "challenged": false,
39    "exemption_applied": "none"
40  },
41  "balances": {
42    "total_authorized": 100,
43    "total_voided": 0,
44    "available_to_void": 100,
45    "total_captured": 0,
46    "available_to_capture": 100,
47    "total_refunded": 0,
48    "available_to_refund": 0
49  },
50  "risk": {
51    "flagged": false,
52    "score": 0
53  },
54  "customer": {
55    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
56    "email": "[email protected]",
57    "name": "Jia Tsang"
58  },
59  "processing": {
60    "acquirer_transaction_id": "226009856104463057233",
61    "retrieval_reference_number": "049179801690",
62    "merchant_category_code": "0742",
63    "scheme_merchant_id": "502177",
64    "scheme": "VISA",
65    "partner_response_code": "00",
66    "acquirer_name": "Checkout Visa",
67    "acquirer_country_code": "GB",
68    "aft": false,
69    "pan_type_processed": "fpan",
70    "cko_network_token_available": false
71  },
72  "eci": "05",
73  "scheme_id": "661856082822182",
74  "actions": [
75    {
76      "id": "act_wl5dv2xperdu5canyu2jz72mom",
77      "type": "Authorization",
78      "response_code": "10000",
79      "response_summary": "Approved"
80    }
81  ],
82  "_links": {
83    "self": {
84      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e"
85    },
86    "actions": {
87      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/actions"
88    },
89    "capture": {
90      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/captures"
91    },
92    "void": {
93      "href": "https://api.checkout.com/gateway/payments/pay_5o3zluz2oh2u7gbonujy33765e/voids"
94    }
95  }
96}


1{
2  "id": "pay_ggiqdmmp7m6ehl5rcjxzw46hgq",
3  "requested_on": "2024-01-23T14:49:25.2151969Z",
4  "source": {
5    "id": "src_h2xxsn5unfzedlrbmxnh3s7n2m",
6    "type": "card",
7    "expiry_month": 12,
8    "expiry_year": 2029,
9    "name": "Jia Tsang",
10    "scheme": "Visa",
11    "last4": "7863",
12    "fingerprint": "3D91433E7E3218ED2447E8EA0E8CDEA03085786D0DE7746EB6EA4E513C684CD6",
13    "bin": "453962",
14    "card_type": "DEBIT",
15    "card_category": "CONSUMER",
16    "issuer": "BANC INTERNACIONAL DANDORRA, S.A.",
17    "issuer_country": "AD",
18    "product_type": "ELECTRON"
19  },
20  "amount": 100,
21  "currency": "EUR",
22  "payment_type": "Regular",
23  "reference": "a19c5c40-a5be-4307-a14c-d8ebd9ef995a",
24  "status": "Declined",
25  "approved": false,
26  "3ds": {
27    "downgraded": false,
28    "enrolled": "Y",
29    "authentication_response": "N",
30    "authentication_status_reason": "01",
31    "version": "2.2.0"
32  },
33  "risk": {
34    "flagged": false,
35    "score": 0
36  },
37  "customer": {
38    "id": "cus_gd2oabkekwru3fckbb2b5xdqbe",
39    "email": "[email protected]",
40    "name": "Jia Tsang"
41  },
42  "actions": [
43    {
44      "id": "act_7dkwh4uflaeuvhdjwrnhnpc7c4",
45      "type": "Authorization",
46      "response_code": "20151",
47      "response_summary": "Cardholder failed 3D-Secure authentication"
48    }
49  ],
50  "_links": {
51    "self": {
52      "href": "https://api.checkout.com/gateway/payments/pay_ggiqdmmp7m6ehl5rcjxzw46hgq"
53    },
54    "actions": {
55      "href": "https://api.checkout.com/gateway/payments/pay_ggiqdmmp7m6ehl5rcjxzw46hgq/actions"
56    }
57  }
58}

If you make a payment request without the 3ds object, or with "3ds.enabled": false, and the issuer does not require 3DS authorization for the transaction, the payment will complete successfully.

If, however, you make a payment request without the 3ds object, or with "3ds.enabled": false, and the issuer does require 3DS authorization for the transaction, you will receive a soft decline response (response code 20154). You will then need to resubmit the payment as a 3DS payment.

To handle cases where the customer's card is not enrolled for any version of 3DS, you can set the attempt_n3d field to true (see the example request below) to downgrade the transaction to non-3DS. This means that if the customer's bank does not support 3DS, we will automatically attempt to process the payment without 3DS authentication instead.

Note

If you downgrade the payment to non-3DS, the liability shift advantage of 3DS will not apply, meaning you will not be protected against potentially fraudulent payments or chargebacks.


1{
2  "source": {
3    "type": "token",
4    "token": "tok_vtvlbgpyoaaubmldynpm32bali"
5  },
6  "amount": 2000,
7  "currency": "USD",
8  "3ds": {
9    "enabled": true,
10    "attempt_n3d": true
11  }
12}

Our standalone Authentication product allows you to authenticate online transactions with the EMV 3DS protocol and helps you to fulfil the Strong Customer Authentication (SCA) requirements.

If you're a user of our Authentication product, you can authorize payments using the identifier from the Sessions API response.

This simplified integration reduces the maintenance effort caused by regular 3DS protocol updates. It also ensures you do not need to handle any differences between local and global scheme requirements to perform a successful authorization.

Transactions made using this integration will appear as a single payment transaction line in your Dashboard.

If you want to authorize payments using the individual 3ds fields (such as eci, cryptogram, xid, version), you can do so using the authentication data from a third-party provider. Our standalone authentication product can be used as a third-party provider for authorizing payments.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "card",
4    "number": "5436031030606378",
5    "expiry_month": 12,
6    "expiry_year": 2025
7  },
8  "amount": 257,
9  "currency": "USD",
10  "3ds": {
11    "enabled": true,
12    "authentication_id": "sid_y3oqhf46pyzuxjbcn2giaqnb441"
13  }
14}

If the approved field is set to true, your authorization was successful. If unsuccessful, the card used for the payment may be invalid/expired or the account has an insufficient available balance.


1{
2  "id": "pay_7a4355cden2upo2pkve6sxzzwm",
3  "action_id": "act_rkzwx7sagtyuxnqnu3hbyld2ay",
4  "amount": 100,
5  "currency": "GBP",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "124203",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "balances": {
12    "total_authorized": 100,
13    "total_voided": 0,
14    "available_to_void": 100,
15    "total_captured": 0,
16    "available_to_capture": 100,
17    "total_refunded": 0,
18    "available_to_refund": 0
19  },
20  "risk": {
21    "flagged": false
22  },
23  "source": {
24    "id": "src_lflzuabkdlkevaopjpk27ex3w4",
25    "type": "card",
26    "expiry_month": 12,
27    "expiry_year": 2023,
28    "scheme": "Mastercard",
29    "last4": "3276",
30    "fingerprint": "CF79B91401CB4BF771BD423DBE275C2D85C39728874D15528B06F75D4B63C7C6",
31    "bin": "539704",
32    "card_type": "CREDIT",
33    "card_category": "CONSUMER",
34    "issuer": "Test Bank",
35    "issuer_country": "US",
36    "product_id": "MCG",
37    "product_type": "Gold MasterCard(r) Card",
38    "avs_check": "S",
39    "cvv_check": "Y",
40    "payment_account_reference": ""
41  },
42  "customer": {
43    "id": "cus_xoar4xyvwbpeph2m2besbp52rq",
44    "email": "[email protected]",
45    "name": "John Smith"
46  },
47  "processed_on": "2022-08-02T14:48:34.371324Z",
48  "reference": "Reference",
49  "scheme_id": "435166469706885",
50  "processing": {
51    "acquirer_transaction_id": "067757716527430582022",
52    "retrieval_reference_number": "456111356278"
53  },
54  "expires_on": "2022-09-01T14:48:34.371324Z",
55  "_links": {
56    "self": {
57      "href": "https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm"
58    },
59    "actions": {
60      "href": "https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/actions"
61    },
62    "capture": {
63      "href": "https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/captures"
64    },
65    "void": {
66      "href": "https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/voids"
67    }
68  }
69}

If you received a 422 Unprocessable entity response, your authentication was not successfully completed and approved. More information will be provided in the error_codes object.

Authenticate a payment using a third-party provider and authorize it with us.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

Header Value

Header	Value
`Authorization` required	`secret key` Use the valid secret key of your Checkout.com account. You can find this in the Dashboard.
`Content-Type` required	`application/json`

Authorization

required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Dashboard.

Content-Type

required

application/json

Parameter	Description
`3ds` required object	Information required for 3D Secure payments.
`3ds.challenge_indicator` optional string	Indicates your preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether the customer is challenged. If `3ds.exemption` and `3ds.challenge_indicator` are provided, then `3ds.exemption` overrides `3ds.challenge_indicator`. For more information about exemptions, see our SCA compliance guide.
`3ds.cryptogram` required string	Base-64 cryptographic identifier used by card schemes to validate the token verification result. Required unless the `previous_payment_id` is specified. For more information, see Pay with stored card details.
`3ds.eci` required string	The Electronic Commerce Indicator security level associated with the token. Required unless the `previous_payment_id` is specified. For 3D Secure payments the ECI must be provided in the `3ds` payment field. For more information, see Pay with stored card details.
`3ds.enabled` required boolean	Whether to process this payment as a 3D Secure. Set this to `true`.
`3ds.exemption` optional string	Requests an SCA exemption for the transaction. The customer’s bank has the final say on whether or not it applies. If the requested `3ds.exemption` is not supported or enabled, `3ds.challenge_indicator` is used as a fallback. For more information about exemptions, see our SCA compliance guide.
`3ds.version` required string	Indicates the version of 3D Secure used for authentication. Defaults to `1.0.2` if not provided.
`3ds.xid` required (for Mastercard and American Express requests) optional (for Visa requests) string	The 3D Secure transaction identifier. In 3DS with Mastercard, the value is the directory server transaction ID.
`success_url` required string	The URL that the cardholder is redirected to when 3DS authentication is successful. This overrides the default success redirect URL configured on your account.
`failure_url` required string	The URL that the cardholder is redirected to when 3DS authentication has failed. This overrides the default failure redirect URL configured on your account.


1{
2  "source": {
3    "type": "card",
4    "number": "5436031030606378",
5    "expiry_month": 12,
6    "expiry_year": 2025
7  },
8  "amount": 257,
9  "currency": "USD",
10  "3ds": {
11    "enabled": true,
12    "eci": "06",
13    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=",
14    "xid": "79f6205c-ff5c-4a4c-8fca-90f67f3a6470",
15    "version": "2.0.1"
16  }
17}

If the approved field is true, your authorization was successful. If unsuccessful, the card used for the payment may be invalid/expired or the account has an insufficient available balance.

If you received a 202 response, the payment requires a redirect.

Information

If the card scheme provided us with an eci value, it will be included in the response. The value indicates the security level that the card scheme decided to authorize the payment with.

Authenticate payments

Information