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.

3DS 2 payments with a third-party provider are only supported for Visa and Mastercard. If processing Amex payments, make sure to use 3DS 1 instead.

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

OBJECT

REQUIRED

Information required for 3D Secure payments.

3ds.enabled

STRING

REQUIRED

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

3ds.eci

STRING

REQUIRED

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

STRING

REQUIRED

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

STRING

REQUIRED (for all 3DS1 requests, and for 3DS2 Mastercard requests)

OPTIONAL (for 3DS2 Visa requests)

The 3D Secure transaction identifier.

3ds.version

STRING

REQUIRED

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

If 3ds.version is set to 2.x.x for an Amex request, you'll receive a 3ds_version_not_supported error. You should set it to 1.x.x instead.

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.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.