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

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.

Parameter	Allowed Values/Data Type	Description
`authValidation`	`url`	Always send `url` in this field
`callbackUrl`	string	Send 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:

Parameter	Type	Description
`token`	string	This is the token to be used for charging once the 3DS validation is complete
`url`	URL	This is the URL to which you should redirect the user for authentication
`secureService`	String	Type of authentication, will be 3dsecure in the case of 3DS
`secureId`	String	The secureId obtained from the token request

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

To keep in mind

If you attempt to use the token to make the charge, bypassing 3DS validation, you will receive a decline with code K322 and subcode K328 (without security validation).

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:

Property	Type	Description
`success`	boolean	Indicates whether the 3DS validation process was completed and whether the charge or pre-authorization can proceed.
`token`	string	Token returned by Kushki to be used when making a charge in case 3D Secure authentication was successful
`message`	String	Generic 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:

The challenge was presented to the cardholder, and they successfully authenticated.

The 3DS provider determined that the card was reliable, and it was not necessary to present a challenge.

It was not possible to present the challenge to the cardholder. In this case, the charge or preauthorization may be declined.

The cardholder has exceded the limit of 3 attempts allowed for complete the authentication.

To keep in mind

It is possible that the charge may be subsequently rejected, even if the success parameter has a value of true. Click here for the complete catalog of 3DS rejection codes once the charge or pre-authorization is executed.

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:

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.

Force 3D Secure authentication on a specific transaction

By default, Kushki decides whether a transaction requires 3D Secure authentication based on the risk rules configured for your business. If you need to force 3DS validation on a specific transaction regardless of those rules, send the require3DS field in the token request.

Parameter	Type	Description
`require3DS`	boolean	Forces 3D Secure authentication on this transaction. Must be sent together with `authValidation` and `callbackUrl`.

Request example

{
  "card": {
    "name": "John Doe",
    "number": "4456528080389860",
    "expiryMonth": "02",
    "expiryYear": "32",
    "cvv": "200"
  },
  "totalAmount": 20,
  "currency": "USD",
  "require3DS": true,
  "authValidation": "url",
  "callbackUrl": "https://yourmerchant.com/3ds/callback"
}

Keep in mind

If you send require3DS without including both authValidation and callbackUrl, the API returns the error K001.

Configure your risk rules

require3DS only affects the specific transaction where you send it. To define when 3DS is requested automatically on the rest of your transactions, coordinate with Kushki's fraud prevention team to configure your risk rules.

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.

3DS Authentication Availability#

Collect User Information and Request a Single Payment Token#

callbackUrl Function#

If success= true#

If success= false#

Force 3D Secure authentication on a specific transaction#

Request example#

Test Your Integration#

3DS Authentication Availability

Collect User Information and Request a Single Payment Token

callbackUrl Function

If `success`= `true`

If `success`= `false`

Force 3D Secure authentication on a specific transaction

Request example

Test Your Integration