SupportAPI referenceClassic API docs
Guides

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

HeaderValue
AuthorizationRequired

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type\ Requiredapplication/json

Additional parameters

ParameterDescription
3dsObjectrequiredInformation required for 3D Secure payments.
3ds.enabled\ String\ requiredWhether 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 requestsThe 3D Secure transaction identifier.
3ds.version\ String\ requiredIndicates 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 over 1 year ago