3DS API integration

Authenticate your one-time card payments with 3DS by consuming our API

If you are a PCI-certified merchant, you can authenticate your one-time card charges with 3DS by consuming our API as indicated below.

3DS Authentication Availability

Available ✅No available ⛔️
- 3DS Authentication for one-time card charges
- 3DS Authentication for pre-authorizations
- Authentication when creating scheduled or one-click subscriptions
- Authentication in execution of one-click charges (on-demand charges)

Collect User Information and Request a Single Payment Token

  1. When collecting user payment information and card data, make sure to include the authValidation and callbackUrl parameters in the token request. These parameters are mandatory for 3DS authentication if required.
ParameterAllowed Values/Data TypeDescription
authValidationurlAlways send url in this field
callbackUrlstringSend the URL to which the user should be redirected when 3DS authentication is completed

Here is an example of a token request including these fields:

{
"card": {
"name": "John Doe",
"number": "5451951574925480",
"expiryMonth": "08",
"expiryYear": "28",
"cvv": "121"
},
"totalAmount": 160000,
"currency": "COP",
"authValidation": "url",
"callbackUrl": "https://www.tutienda.com"
}

If 3DS validation is not required, you will receive the token as the only parameter, and you can proceed with the chargeor preauthorization. If 3DS validation is required, the response will include the token, URL, and variables secureService and secureId as shown in the following example:

{
"token": "g9m2XG100000uut73n085881SMOP3bP1",
"url": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=A",
"secureService": "3dsecure",
"secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
}

Here is a description of these variables:

ParameterTypeDescription
tokenstringThis is the token to be used for charging once the 3DS validation is complete
urlURLThis is the URL to which you should redirect the user for authentication
secureServiceStringType of authentication, will be 3dsecure in the case of 3DS
secureIdStringThe secureId obtained from the token request
  1. Make sure to open in your browser the URL obtained in url to allow the payer to perform 3DS authentication if required.
  1. Once the user completes the authentication, the client will be returned with a GET call to the callbackUrl you specified when requesting the token.

callbackUrl Function

The callback function will allow you to know if the 3D Secure validation process was completed successfully or if there was any problem during the process. This URL will be automatically called after performing the authentication through a 301 redirect by making a GET request to the URL sent in the callbackUrl field, sending the response parameters in the URL (path parameters).

Here is a description of the parameters for this function:

PropertyTypeDescription
successbooleanIndicates whether the 3DS validation process was completed and whether the charge or pre-authorization can proceed.
tokenstringToken returned by Kushki to be used when making a charge in case 3D Secure authentication was successful
messageStringGeneric error message

If success= true

The boolean type parameter success=true, will be returned in the following scenarios, in all of which you can proceed to perform the charge or preauthorization:

  1. The challenge was presented to the cardholder, and they successfully authenticated.
  2. The 3DS provider determined that the card was reliable, and it was not necessary to present a challenge.
  3. It was not possible to present the challenge to the cardholder. In this case, the charge or preauthorization may be declined.
  4. The cardholder has exceded the limit of 3 attempts allowed for complete the authentication.
https://www.tutienda.com/?success=true&token=cfa0bfec88324bd7a5c6c1ad9135a846

If success= false

In case the success parameter is returned as false it is possible that it is because the cardholder entered the challenge incorrectly.

Example of a callback with authentication problem:

https://www.tutienda.com/?success=false&message=Error%20en%20la%20validación%20de%203DS&token=cfa0bfec88324bd7a5c6c1ad9135a846

If this parameter remains false, the token must in any case be generated again by sending the card data because if a charge or pre-authorization is made, these will be declined.

Test Your Integration

There are test cards that you can use in test mode (Kushki Sandbox enabled) to ensure that your integration is ready. Use them with any CVV, 1234 as OTP code, and a future expiration date.

Auth required false - approved charge

  • 4456540000000063
  • 4456543371713314
  • 4456541982068615
  • 4456541249811088

Auth required true - declined charge

  • 4456530000000031
  • 4456530000000106
  • 4456536583667765
  • 4456536501449767
  • 4456532705848821

Auth required true - approved charge

  • 4456528080389860
  • 4456529267234200
  • 4456529165328302
  • 4456524869770255
  • 4456523340069956

3DS authentication failed:

  • 9999 (enter this value when the modal is displayed).

3DS error codes

Check the main error codes when transactions are rejected due to problems with 3DS authentication.