SupportAPI referenceClassic API docs
Guides
Start typing to search…

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

POSThttps://api.checkout.com/payments/

Sandbox

POSThttps://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 [email protected].

Updated 5 months ago