3DS API integration

December 16, 2024

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

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.

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:

2. Make sure to open in your browser the URL obtained in url to allow the payer to perform 3DS authentication if required.

3. 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:

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).