Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

3D Secure payments with a third-party provider

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

https://api.checkout.com/payments/
https://api.sandbox.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

STRING

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

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