Authenticate payments
This guide will show you how to integrate 3D Secure (3DS) into your payment flows. Your integration will depend on the product you are using to process authentication. We support 3 different methods of authenticating online transactions:
- Using our integrated authentication
- Using our standalone Authentication product
- Using a third-party provider
Information
We currently support versions up to, and including, 2.2.0 of the 3D Secure protocol.
Submit a payment request with "3ds.enabled": true
, and we'll redirect your customer to a Checkout.com page to gather all the 3DS-relevant data and add the required fields to your request—meaning no extra work for you.
First, the customer needs to exchange their card details for a card token – tokenization.
Once you've got a card token, you can request a payment using the request a card payment endpoint.
The only difference between a standard card token payment and a 3DS one is the 3ds
object. Set the enabled
field to true
to request a 3DS payment.
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": true10},11"success_url": "https://example.com/payments/success",12"failure_url": "https://example.com/payments/failure"13}
Information
If you want to test 3DS authentication flows and transaction statuses in the sandbox environment, use our test cards.
If the card is enrolled for 3DS, you'll receive a 202 - Accepted
response containing a redirect
link, to which you should redirect your customer.
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}
The customer may be prompted to verify their identity on a 3DS challenge screen. For example, using a password.
![3d Secure 2 challenge prompt screen](/docs/docs/Risk management/3ds2_challenge.png)
If the customer successfully completes the challenge 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": 031},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}
![Diagram of successful non-3DS authorization request flow](/docs/docs/Risk management/Non-3DS-authorization.png)
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.
![Diagram of non-3DS authorization flow with soft decline](/docs/docs/Risk management/Non-3DS-authorization-with-soft-decline.png)
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": true11}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": 20257},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": 019},20"risk": {21"flagged": false22},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 |
---|---|
required |
Use the valid secret key of your Checkout.com account. You can find this in the Dashboard. |
required |
|
Parameter | Description |
---|---|
required object | Information required for 3D Secure payments. |
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 For more information about exemptions, see our SCA compliance guide. |
required string | Base-64 cryptographic identifier used by card schemes to validate the token verification result. Required unless the For more information, see Pay with stored card details. |
required string | The Electronic Commerce Indicator security level associated with the token. Required unless the For more information, see Pay with stored card details. |
required boolean | Whether to process this payment as a 3D Secure. Set this to |
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 For more information about exemptions, see our SCA compliance guide. |
required string | Indicates the version of 3D Secure used for authentication. Defaults to |
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. |
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. |
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": 20257},8"amount": 257,9"currency": "USD",10"3ds": {11"enabled": true,12"eci": "06",13"cryptogram": "123feb70-d16b-4da6-b07f-98c0",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.