Authenticate payments
This guide shows you how to integrate 3D Secure (3DS) into your payment flows.
Information
Checkout.com supports all versions of the 3DS protocol up to and including 2.2.0.
You can authenticate online payments using any of the following integration options:
- Integrated authentication
- Standalone Sessions authentication
- Third-party authentication
With the integrated authentication solution, Checkout.com automatically routes the customer to 3DS authentication or Google Secure Payment Authentication (SPA), depending on which is most likely to result in a successful completion. Google SPA enables cardholders to complete biometric authentication directly from your domain, which enhances the user experience.
For the automatic routing to function, you must provide 3DS authentication data in all of your payment requests.
If the initial authentication experience fails or is declined by the customer, we automatically fall back to the alternative authentication experience to prevent a lost transaction.
When you submit a payment request with the 3ds.enabled field set to true, we redirect the customer to a Checkout.com page to gather the data required for 3DS authentication. We automatically add the required fields to your payment request.
If you host the payment page in an iframe, you must explicitly add payment permission to the iframe to allow payments to complete. Include the allow="payment *" attribute in all parent frames:
Follow these steps:
- Create a card token.
- Request a card token payment
- Redirect your customer.
- Verify the payment.
To exchange the customer's card details for a card token, call the Request a token endpoint.
post
https://api.checkout.com/tokens
The response returns the token, which you need for the payment request.
Call the Request a payment or payout endpoint, and set source.type to token.
To request 3DS authentication for the payment, set the 3ds.enabled field in your request to true.
Information
You can automatically downgrade your payment to a non-3DS payment if there are any technical issues during the 3DS authentication process that would otherwise cause the payment to fail. Set the attempt_n3d field in the request to true and we automatically attempt to process the payment without 3DS authentication.
post
https://api.checkout.com/payments
The response returns the URL to redirect your customer to in the _links.redirect.href field.
If the card is enrolled for 3DS or eligible for Google SPA, you receive a 202 - Accepted response.
Information
Use test cards in the sandbox environment to simulate 3DS and Google SPA authentication flows, and test transactions statuses.
Redirect the customer to the URL returned in the Request a payment response.
In a 3DS authentication experience, the customer may be prompted to verify their identity on a 3DS challenge screen. For example, using a password.
In a Google SPA authentication experience, the customer is prompted to verify their identity on their device using biometric authentication.
If the customer successfully completes the 3DS challenge or Google SPA biometric authentication, they are redirected back to your site.
The success URL contains a cko-session-id query string. For example:
http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7q
If you've set up your webhook receiver, you can verify the status of the payment using the following webhooks:
- Successful payment – You receive a Payment approved webhook.
- Unsuccessful payment – You receive a Payment declined webhook.
Alternatively, you can check if the payment was authenticated and authorized by calling the Get payment details endpoint.
Provide the cko-session-id query string from the Redirect your customer step as the {id} path parameter.
get
https://api.checkout.com/payments/{id}
The result of the 3DS authentication is returned in the 3ds.authentication_response field. This can be one of:
Y– The cardholder was successfully authenticated.A– The authentication was processed by a stand-in service, and is classed as successful.N– The authentication failed.U– The authentication could not be completed due to technical or other problems.
The result of the authorization is returned in the approved boolean. This can be one of:
true– The payment was successfully authorized.false– The payment was not authorized. The card may be invalid, expired, or have an insufficient balance.
You receive separate Electronic Commerce Indicator (ECI) values for the authorization and authentication in the response, which indicate the transaction's security level and liability shift:
- Authorization – The
ecifield represents the final ECI security level received from the issuer to authorize the payment. - Authentication – The
3ds.ecifield represents the final ECI security level received from the issuer to authenticate the payment.
Information
To retrieve a summary of all actions performed during a payment's lifecycle, call the Get payment actions endpoint.
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 completes successfully.
If you make a payment request without the 3ds object, or with "3ds.enabled": false, and the issuer does require 3DS authorization for the transaction, you receive soft decline response code 20154. You must re-request the payment with 3DS.
If the customer's card is not enrolled for any version of 3DS, you can set the attempt_n3d field to true to downgrade the transaction to non-3DS. This means that if the customer's bank does not support 3DS, we automatically attempt to process the payment without 3DS authentication instead.
Note
If you downgrade the payment to non-3DS, liability shift no longer applies. This means you're not be protected against potentially fraudulent payments or chargebacks.
Standalone Sessions authentication enables you to authenticate online transactions with the EMV 3DS protocol and helps you fulfil Strong Customer Authentication (SCA) requirements.
You can authorize payments using the identifier returned in the 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.
Payments requested using this integration display as a single payment transaction line in your Dashboard.
If you want to authorize payments using fields in the 3ds object (such as eci, cryptogram, xid, version), you can do so using the authentication data from a third-party provider. You can also use Standalone Sessions as a third-party provider for authorizing payments.
Call the Request a session endpoint.
post
https://api.checkout.com/sessions
If the approved field returns:
true– The authorization was successful.false– The authorization was unsuccessful. The card may be invalid, expired, have insufficient funds.
If you receive a 422 Unprocessable entity response, the authentication was not successfully completed.
For more information, see the error_codes object.
Authenticate a payment using a third-party provider and authorize it with Checkout.com.
Call the Request a payment or payout endpoint.
In the request body:
| 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 Mastercard and American Express requests)optional (for Visa requests)string | The 3D Secure transaction identifier. In 3DS with Mastercard, the value is the directory server transaction ID. |
post
https://api.checkout.com/payments
If the approved field returns:
true– The authorization was successful.false– The authorization was unsuccessful. The card may be invalid, expired, have insufficient funds.
If you receive a 202 response, the payment requires a redirect.
Information
If the card scheme provided us with an eci value, it is returned in the response. The value indicates the security level that the card scheme decided to authorize the payment with.