Skip to content

3D Secure payments with a third-party provider

Last updated: 10th August 2022

Authorize a payment with us, using the authentication data from another 3DS provider.


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.