Skip to content

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.


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:

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

If you want to automatically attempt a transaction as non-3DS, set attempt_n3d to true in the request.

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
"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.

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.

Note

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 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
    }

    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.

    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": true
    11
    }
    12
    }