Skip to content

3D Secure payments with a third-party provider

Last updated: 6th July 2022

To benefit from a streamlined integration process, we recommend using Checkout.com to authenticate 3D Secure payments. If you wish you to use a third-party provider, you will need to include additional fields in your request.


The request

Use the details below to set up your request.

Endpoints

For the full specification, as well as complete request and response examples, see our 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 Hub.

    Content-Type

    required

    application/json

    Additional body parameters

    ParameterDescription

    3ds

    required
    object

    Information required for 3D Secure payments.

    3ds.enabled

    required
    boolean

    Whether to process this payment as a 3D Secure. Set this to true.

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

    3ds.version

    required
    string

    Indicates the version of 3D Secure used for authentication. Defaults to 1.0.0 if not provided.

    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.