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

Live

https://api.checkout.com/payments/

Sandbox

https://api.sandbox.checkout.com/payments/

Header and path parameters

Header
Value

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 parameters

Parameter
Description

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 3DS 1.0 requests
required for 3DS 2.0 Mastercard requests
optional for 3DS 2.0 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.

Request example

This code snippet is an example of the request body — not all fields are required, so you can custom build your request based on the information you need.

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

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

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 any help or support, then message our support team at support@checkout.com.

3D Secure payments with a third-party provider


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.