Skip to content

3D Secure 2 API Integration

Last updated: 13th January 2022

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

We currently support version 2.1.0 of the 3DS protocol.


Request a 3DS2 payment with a card token

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.


Step 1: Collect a card token

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.

Step 2: Create a card token payment request

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:

Downgrade a 3DS transaction

If you want to automatically attempt a transaction as non-3DS, use the attempt_n3d field.

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

3DS test cards

If you want to test 3DS authentication flows and transaction statuses in the sandbox environment, use our test cards.

Step 3: Redirect your customer

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.

3DS1 fallback

If the customer's card is not enrolled for 3DS2, we will automatically attempt to authenticate the payment with 3DS1.

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

The customer may then be prompted to verify their identity — generally with a password.

3d secure 2 challenge

Redirection URLs

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.

Step 4: Verify the payment with the session ID

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.

The cko-session-id expires 15 minutes after being created.

Endpoints

For the full specification, as well as complete request and response examples, see our API reference.

    get

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

    Response example

    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 attempted but could not be completed.
    • 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.

    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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    {
    "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
    "requested_on": "2019-01-16T22:08:06Z",
    "source": {
    "type": "card",
    "id": "src_wmlfc3zyhqzehihu7giusaaawu",
    },
    "amount": 6540,
    "currency": "USD",
    "approved": false,
    "status": "Declined",
    "3ds": {
    "downgraded": false,
    "authentication_response": "Y",
    "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=",
    "xid": "89936bf2-e971-49e5-b82c-6656bab50870",
    "version": "2.1.0"
    },
    "eci": "06",
    "actions": [
    {
    "id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
    "type": "Authorization",
    "response_code": "20005",
    "response_summary": "Declined - Do Not Honour"
    }
    ],
    "_links": {
    "self": {
    "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "actions": {
    "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44/actions"
    }
    }
    }

    Non-3DS authorization request flows

    Successful non-3DS authorization request flow

    Non-3DS authorization

    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.

    Non-3DS authorization request flow with soft decline

    Non-3DS authorization with soft decline

    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.

    Handling non-enrolled cards

    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.

    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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {
    "source": {
    "type": "token",
    "token":"tok_vtvlbgpyoaaubmldynpm32bali"
    },
    "amount": 2000,
    "currency": "USD",
    "3ds": {
    "enabled": true,
    "attempt_n3d": true
    }
    }