3D Secure 2 API Integration
Last updated: April 29, 2022
This guide will show you how to integrate 3D Secure 2 (3DS2) into your payment flows.
Information
We currently support versions up to, and including, 2.2.0 of the 3D Secure protocol.
Simply submit a payment request with "3ds.enabled": true
, and then we'll redirect your customer to a Checkout.com page to gather all the 3DS2-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. You can create a card token with one of our integration options.
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 3DS2 payment.
You can see an example of a request below:
1{2"source": {3"type": "token",4"token": "tok_f6z4mnoububudpqnvhwa5ff27u"5},6"amount": 2000,7"currency": "USD",8"3ds": {9"enabled": true10}11}
If you want to automatically attempt a transaction as non-3DS, set attempt_n3d
to true
in the request.
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 3DS2 you'll receive a 202 - Accepted
response containing a redirect
link to which you should redirect your customer.
Information
If the customer's card is not enrolled for 3DS2, we will automatically attempt to authenticate the payment with 3DS1.
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://sandbox.checkout.com/api2/v2/3ds/acs/sid_feixbit6us3utfedjulm6egnsu"17}18}19}
The customer may then be prompted to verify their identity — generally with a password.
Information
You can configure redirection success and redirection failure URLs in your Hub dashboard or in the payment request itself by setting the success_url
and failure_url
fields.
When the customer is redirected back to your site, a cko-session-id
querystring parameter is provided at the end of the success URL. It will look something like this:
http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q
Once you've got the cko-session-id
, you can use our get payment details endpoint to determine whether the payment was authenticated and authorized.
Note
The cko-session-id
expires 15 minutes after being created.
For the full specification, as well as complete request and response examples, see our API reference.
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
The response includes an actions
object, which only applies to 3D Secure payments. It gives you a summary of all the actions performed for that payment. This allows you to obtain the response code of the authorization if it was declined.
1{2"id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",3"requested_on": "2019-01-16T22:08:06Z",4"source": {5"type": "card",6"id": "src_wmlfc3zyhqzehihu7giusaaawu"7},8"amount": 6540,9"currency": "USD",10"approved": false,11"status": "Declined",12"3ds": {13"downgraded": false,14"authentication_response": "Y",15"cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",16"xid": "89936bf2-e971-49e5-b82c-6656bab50870",17"version": "2.1.0"18},19"eci": "06",20"actions": [21{22"id": "act_y3oqhf46pyzuxjbcn2giaqnb44",23"type": "Authorization",24"response_code": "20005",25"response_summary": "Declined - Do Not Honour"26}27],28"_links": {29"self": {30"href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"31},32"actions": {33"href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"34}35}36}
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 3DS2 authorization for the transaction, you will receive a soft decline response (response code 20154). You will then need to resubmit the payment as a 3DS2 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 3DS2 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}