Authenticate payments
This guide will show you how to integrate 3D Secure 2 (3DS2) into your payment flows. Your integration will depend on the product you are using to process authentication. We support 3 different methods of authenticating online transactions:
- Using our integrated authentication
- Using our standalone Authentication product
- Using a third-party provider
Information
We currently support versions up to, and including, 2.2.0 of the 3D Secure protocol.
Submit a payment request with "3ds.enabled": true, and we'll redirect your customer to a Checkout.com page to gather all the 3DS2-relevant data and add the required fields to your request—meaning no extra work for you.
First, the customer needs to exchange their card details for a card token – tokenization.
Once you've got a card token, you can request a payment using the request a card payment endpoint.
The only difference between a standard card token payment and a 3DS one is the 3ds object. Set the enabled field to true to request a 3DS2 payment.
Downgrade a 3DS transaction
If you want to automatically attempt a transaction as non-3DS, use the attempt_n3d field.
3DS test cards
If you want to test 3DS authentication flows and transaction statuses in the sandbox environment, use our test cards.
If the card is enrolled for 3DS2, you'll receive a 202 - Accepted response containing a redirect link, to which you should redirect your customer.
3DS1 fallback
If the customer's card is not enrolled for 3DS2, we will automatically attempt to authenticate the payment with 3DS1.
The customer may then be prompted to verify their identity — generally with a password.
When the customer is redirected back to your site, a cko-session-id querystring parameter is provided at the end of the success URL. It will look something like this:
http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q
Once you've got the cko-session-id, you can use our get payment details endpoint to determine whether the payment was authenticated and authorized.
Note
The cko-session-id expires 15 minutes after being created.
For the full specification, as well as complete request and response examples, see our API reference.
get
https://api.checkout.com/payments/{id}
Check the 3ds.authentication_response field to see the result of the 3DS authentication. It will be one of the following values:
Y– Cardholder was successfully authenticated.A– Authentication was processed by a stand-in service, and is classed as successful.N– Authentication failed.U– Authentication could not be completed owing to technical or other problems.
Check the approved field to see whether or not the authorization was successful ("approved": true). If the authorization was unsuccessful, the card might be invalid/expired, or have an insufficient balance.
Information
The response includes an actions object, which only applies to 3D Secure payments. It gives you a summary of all the actions performed for that payment. This allows you to obtain the response code of the authorization if it was declined.
If you make a payment request without the 3ds object, or with "3ds.enabled": false, and the issuer does not require 3DS authorization for the transaction, the payment will complete successfully.
If, however, you make a payment request without the 3ds object, or with "3ds.enabled": false, and the issuer does require 3DS2 authorization for the transaction, you will receive a soft decline response (response code 20154). You will then need to resubmit the payment as a 3DS2 payment.
To handle cases where the customer's card is not enrolled for any version of 3DS, you can set the attempt_n3d field to true (see the example request below) to downgrade the transaction to non-3DS. This means that if the customer's bank does not support 3DS, we will automatically attempt to process the payment without 3DS authentication instead.
Note
If you downgrade the payment to non-3DS, the liability shift advantage of 3DS2 will not apply, meaning you will not be protected against potentially fraudulent payments or chargebacks.
Our standalone Authentication product allows you to authenticate online transactions with the EMV 3DS protocol and helps you to fulfil the Strong Customer Authentication (SCA) requirements.
If you're a user of our Authentication product, you can authorize payments using the identifier from the Sessions API response.
This simplified integration reduces the maintenance effort caused by regular 3DS protocol updates. It also ensures you do not need to handle any differences between local and global scheme requirements to perform a successful authorization.
Transactions made using this integration will appear as a single payment transaction line in your Dashboard.
If you want to authorize payments using the individual 3ds fields (such as eci, cryptogram, xid, version), you can do so using the authentication data from a third-party provider. Our standalone authentication product can be used as a third-party provider for authorizing payments.
For the full API specification, see the API reference.
post
https://api.checkout.com/payments
If the approved field is set to 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 422 Unprocessable entity response, your authentication was not successfully completed and approved. More information will be provided in the error_codes object.
Authenticate a payment using a third-party provider and authorize it with us.
For the full API specification, see the API reference.
post
https://api.checkout.com/payments
| Header | Value |
|---|---|
required |
Use the valid secret key of your Checkout.com account. You can find this in the Dashboard. |
required |
|
| Parameter | Description |
|---|---|
required object | Information required for 3D Secure payments. |
optional string | Indicates your preference for whether or not a 3DS challenge should be performed. The customer’s bank has the final say on whether the customer is challenged. If For more information about exemptions, see our SCA compliance guide. |
required string | Base-64 cryptographic identifier used by card schemes to validate the token verification result. Required unless the For more information, see Pay with stored card details. |
required string | The Electronic Commerce Indicator security level associated with the token. Required unless the For more information, see Pay with stored card details. |
required boolean | Whether to process this payment as a 3D Secure. Set this to |
optional string | Requests an SCA exemption for the transaction. The customer’s bank has the final say on whether or not it applies. If the requested For more information about exemptions, see our SCA compliance guide. |
required string | Indicates the version of 3D Secure used for authentication. Defaults to |
required (for 3DS1 requests, and 3DS2 requests for Mastercard and American Express)optional (for 3DS2 Visa requests)string | The 3D Secure transaction identifier. In 3DS2 with Mastercard, the value is the directory server transaction ID. |
required string | The URL that the cardholder is redirected to when 3DS authentication is successful. This overrides the default success redirect URL configured on your account. |
required string | The URL that the cardholder is redirected to when 3DS authentication has failed. This overrides the default failure redirect URL configured on your account. |
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.
Information
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.