Skip to content

Authenticate payments

Last updated: 31st August 2022

This guide will show you how to integrate 3D Secure 2 (3DS2) 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:

We currently support versions up to, and including, 2.2.0 of the 3D Secure protocol.


Authenticate payments using our integrated authentication

Submit a payment request with "3ds.enabled": true, and 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.

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

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.

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

    Authenticate payments using our standalone Authentication product

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


    Endpoints

    For the full API specification, see the API reference.

      post

      https://api.checkout.com/payments

      Request example

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

      Response example

      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
      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
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
      69
      {
      "id":"pay_7a4355cden2upo2pkve6sxzzwm",
      "action_id":"act_rkzwx7sagtyuxnqnu3hbyld2ay",
      "amount":100,
      "currency":"GBP",
      "approved":true,
      "status":"Authorized",
      "auth_code":"124203",
      "response_code":"10000",
      "response_summary":"Approved",
      "balances":{
      "total_authorized":100,
      "total_voided":0,
      "available_to_void":100,
      "total_captured":0,
      "available_to_capture":100,
      "total_refunded":0,
      "available_to_refund":0
      },
      "risk":{
      "flagged":false
      },
      "source":{
      "id":"src_lflzuabkdlkevaopjpk27ex3w4",
      "type":"card",
      "expiry_month":12,
      "expiry_year":2023,
      "scheme":"Mastercard",
      "last4":"3276",
      "fingerprint":"CF79B91401CB4BF771BD423DBE275C2D85C39728874D15528B06F75D4B63C7C6",
      "bin":"539704",
      "card_type":"CREDIT",
      "card_category":"CONSUMER",
      "issuer":"PUBLIC JOINT STOCK COMPANY PROMSVYAZBANK",
      "issuer_country":"RU",
      "product_id":"MCG",
      "product_type":"Gold MasterCard(r) Card",
      "avs_check":"S",
      "cvv_check":"Y",
      "payment_account_reference":""
      },
      "customer":{
      "id":"cus_xoar4xyvwbpeph2m2besbp52rq",
      "email":"testemail@test.com",
      "name":"Mr Test"
      },
      "processed_on":"2022-08-02T14:48:34.371324Z",
      "reference":"Reference",
      "scheme_id":"435166469706885",
      "processing":{
      "acquirer_transaction_id":"067757716527430582022",
      "retrieval_reference_number":"456111356278"
      },
      "expires_on":"2022-09-01T14:48:34.371324Z",
      "_links":{
      "self":{
      "href":"https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm"
      },
      "actions":{
      "href":"https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/actions"
      },
      "capture":{
      "href":"https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/captures"
      },
      "void":{
      "href":"https://api.sandbox.checkout.com/payments/pay_7a4355cden2upo2pkve6sxzzwm/voids"
      }
      }
      }

      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 payments using a third-party provider

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

      The request

      For the full API specification, see the API reference.

        post

        https://api.checkout.com/payments

        Header parameters

        HeaderValue

        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

        Additional body parameters

        ParameterDescription

        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 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 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 3DS1 requests, and 3DS2 requests for Mastercard and Amex)
        optional
        (for 3DS2 Visa requests)
        string

        The 3D Secure transaction identifier. In 3DS2 with Mastercard, the value is the directory server transaction ID.

        Request example

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

        The response

        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.

        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.