3DS integration with kushki.js library

Use this option if you have implemented or plan to implement kushki.js in your front-end and want to authenticate your transactions with 3DS.

Available transactions

Available ✅	Not available ⛔️
3DS authentication for one-time card charges
3DS authentication for preauthorizations

To perform 3DS authentication during card tokenization (subscription creation), see this guide.

1. Set-up your front-end

Configure your front-end according to your integration.

Kajita (payment form)

Follow our instructions for Kajita described in our guide to accept card payments.

Once you have configured 3DS for your merchant, Kajita will automatically request 3DS validation for each payment attempt where authentication is required. You do not need to perform anything else.

Kushki.js

Follow our instructions for Kushki.js described in our guide to accept card payments.

Now, before sending the data to the end-point in your back-end, we must perform the 3DS validation with the card issuer.

When 3DS is enabled, the response from the requestToken() method will be as shown below:

You can find the description of these variables below:

Parameter	Type	Description
`authRequired`	Boolean	This field indicates whether a 3DS challenge is required or not.
`acsURL`	URL	Refers to the URL of the challenge page that the user must pass (Access Control System).
`specificationVersion`	String	Refers to the applicable 3DS version.
`authenticationTransactionId`	String	Transaction ID verified from brands.
`paReq`	String	Stands for the Payer Authentication Request. It is a base64 encoded field containing your merchant and cardholder information that is sent to the issuer for authentication Note: In case of testing in UAT environment, `sandbox` must be sent.

Once you receive the response from the token with the above structure, you must send the security object to Kushki by consuming the requestValidate3DS method:

If the value of the authRequired variable is equal to true, the 3DS validation modal will be presented and your customer will then receive the value to enter by email or text message.

If the value of the authRequired variable is equal to false, the 3DS validation modal will not be presented.

The response you will receive in the callback function will be:

{
  "code":"3DS000",
  "message":"ok"
}

In case of error, the response of the callback function will be something like:

{ 
  "message":"error-message", 
  "code":"error-code",
  "error": "error-message" 
}

You will receive the authentication response in the charge. If the authentication is declined, you will receive a K322 code and any of the other subcodes specified in the Error codes guide.

The cardholder will have up to a maximum of 3 retries to complete the 3DS authentication.

Kushki.js Hosted Fields

When calling the requestToken() method to request a token, if a 3DS rule exists and the condition is met, the requestToken() method will display the modal so that the client can enter the 3DS validation data.

If the validation was incorrect, you may receive one of the following error codes:

CODE	MESSAGE	EXAMPLE	DESCRIPTION
E004	Error en solicitud de JWT	{ code: "E004", message: "Error en solicitud de JWT" }	If the merchant has a 3DS rule enabled and there was an error requesting the JWT, code E004 will be returned. Please try again; If the error persists, contact Kushki support.
E005	Campos 3DS inválidos	{ code: "E005", message: "Campos 3DS inválidos" }	If the merchant has a 3DS rule enabled and there was an error in 3DS authentication, the code E005 will be returned. Please try again making sure you enter the data correctly for 3DS validation.
E006	Error en solicitud de validación de token	{ code: "E006", message: "Error en solicitud de validación de token" }	If the merchant has a 3DS rule enabled and there was an error in the 3DS validation session, code E006 will be returned. Please try again making sure you enter the data correctly for 3DS validation; If the error persists, contact Kushki support.

See the reference for more information on 3DS validation.

2. Configure your back-end

Follow the instructions in our guide to accept card payments.

3. Test your integration

We have test cards that you can use in the test mode to ensure that your integration is ready. You can use them with any CVV, 1234 as OTP code and future expiration date.

Transaction approved with 3DS authentication required:

4456528080389860

4456529267234200

4456529165328302

4456524869770255

4456523340069956

Transaction approved without 3DS validation:

4456540000000063

4456543371713314

4456541982068615

4456541249811088

Important

To enable 3DS in test mode in your merchant, it is required to have an additional configuration performed by Kushki.

4. Prepare your certification

Follow the guidelines described in our guide to accept card payments.

3DS integration with kushki.js library

Available transactions#

1. Set-up your front-end#

Kajita (payment form)#

Kushki.js#

Kushki.js Hosted Fields#

2. Configure your back-end#

3. Test your integration#

4. Prepare your certification#

Available transactions

1. Set-up your front-end

Kajita (payment form)

Kushki.js

Kushki.js Hosted Fields

2. Configure your back-end

3. Test your integration

4. Prepare your certification