Migrate to Kushki.js 2.0

Below are the steps and services available in kushki.js to migrate from version 1.0 to version 2.0.

For more detailed information, visit the Kushki.js 1.0 and Kushki.js 2.0 documentation.

Services available for migration

These are the services currently available in version 2.0 of the Kushki.js library. More services will be added over time.

Note

Before migrating the library version, make sure the services you have integrated are available so you can keep the functionality you have implemented.

SERVICE	AVAILABLE IN 2.0	COMMENTS
One-time payment token	✅
OTP validation for one-time payment	✅
3DS validation for one-time payment	✅
Sift Science validation for one-time payment	?
Deferred options for one-time payment	✅
Bin info for one-time payment	❌
Recurring charges	❌	Recurring charges are not yet available in version 2.0
ONE-CLICK payments	❌	No method available for this operation
Web Pay (Chile)	❌	No method available for this operation
Bank transfer payments	❌	Bank transfer payments are not yet available
Cash payments	❌	Cash payments are not yet available
Cash payouts	❌	Cash payouts are not yet available
Gateway Status	❌	No method available for this operation
Commissions	❌	No method available for this operation
3DS validation via API	❌	No method available to obtain the JWT
Recurring charges via API	❌	No method available to obtain the JWT

Migrating the one-time payment token

To migrate your integration from Kushki.js 1.0 to 2.0, follow these steps to obtain the one-time payment token.

Step 1. Update the library import source

Update the source you import the Kushki.js library from into your application.

Note

Do not pack or host the library yourself.

CDN

NPM

If you import from the CDN, update the import script from

Step 2. Library initialization

In version 2.0, both the object where the merchant configuration is initialized and its attributes change. Here are the details across versions:

KUSHKI.JS 1.0	KUSHKI.JS 2.0	COMMENTS
Kushki	KushkiOptions	The name of the object to instantiate for initialization with the merchant information changed from `Kushki` to `KushkiOptions`
merchantId	publicCredentialId	The name of the property that holds the merchant's public key changed from `merchantId` to `publicCredentialId`
inTestEnvironment	inTest	The name of the property that specifies the working environment changed from `inTestEnvironment` to `inTest`
regional	Not available	The `regional` property is no longer available in Kushki.js 2.0

In your application, create an instance of the KushkiOptions object, which will replace the previous Kushki instance.

Kushki.js 1.0

Kushki.js 2.0

Step 3. Update the payment form

Because Kushki.js 2.0 implements hosted fields, you need to make the following changes to your payment form.

Replace your application's form fields with the following:

Review all available fields here.

Note

If you use custom styles in your current payment form, review how to style hosted fields.

Step 4. Token request

To request the token in Kushki.js 2.0, you must create a CardOptions object that will hold the payment information as well as the transaction data (amount, currency, etc.), instead of passing this data directly to the requestToken() method as in version 1.0. Then, you must create a card instance with the initCardToken method.

Kushki.js 1.0

The requestToken() method is called on the Kushki instance created earlier, with the card information and the transaction data (amount, currency, etc.).

Kushki.js 2.0

Then, call the requestToken() method available on the card instance created earlier.

Response

The information returned in the response has changed in Kushki.js 2.0. Below you can see the information returned across versions:

KUSHKI.JS 1.0	KUSHKI.JS 2.0	COMMENTS
token	token	Token with the transaction information
secureId	Not available	OTP and 3DS validations are now performed internally in the `requestToken()` method
secureService	Not available	OTP and 3DS validations are now performed internally in the `requestToken()` method
security	Not available	OTP and 3DS validations are now performed internally in the `requestToken()` method
Not available	deferred	Object with deferred payment information returned in Kushki.js 2.0 (if available for the merchant)

Step 5. Certification

Once you have made the changes in your application to migrate to Kushki.js 2.0, you must complete a certification to validate that everything works correctly.

OTP validation for one-time payment

In Kushki.js 2.0, you no longer need to perform OTP validation by sending information obtained from the token. This validation is now performed automatically when calling the requestToken() method, which will render the modal for the customer to enter the OTP. You can check the OTP validation status with the onOTPValidation() method. If you have OTP validation enabled, follow these steps to migrate to Kushki.js 2.0.

Note

The previous implementation of the requestSecureServiceValidation() method found in Kushki.js 1.0 is no longer needed in version 2.0, so you now only need to check the validation status.

To implement OTP in Kushki.js, follow these steps:

Step 1. Add the hosted field for OTP

Add a <div> with the id id_otp to the payment form so that the OTP field is rendered if required.

Step 2. Identify the OTP status

To check the transaction's OTP status and see whether it is required, you can call the onOTPValidation() method, which will return three callbacks (onSuccess, onError, onRequired) indicating whether the OTP field is required, whether it completed successfully, or whether there was an error. If the onRequired callback is returned, you will need to display the field for entering the OTP in the payment form when calling the requestToken() method to request a token.

Step 3. Link the OTP div in the CardOptions instance

If checking the OTP status returns an onRequired callback, you will need to link the OTP <div> when creating a CardOptions instance. To do so, add the otp property to the fields object as shown below:

Next, request a token.

Step 4. Certification

Once you have made the changes in your application to migrate to Kushki.js 2.0, you must complete a certification to validate that everything works correctly.

3DS validation for one-time payment

Step 1. Token request

In Kushki.js 2.0, 3DS validation is performed automatically when calling the requestToken() method, which will display the 3DS modal and run the necessary validations, returning a successful response if a valid code is entered or an error message if there was a problem during validation. No additional action is required.

Note

In Kushki.js 2.0, additional 3DS information (secureId, secureService, security) is no longer returned when generating the token, as it was in Kushki.js 1.0.

Deferred options for one-time payment

Step 1. Token request

In Kushki.js 2.0, when you call the requestToken() method it will return, along with the token, the deferred payment options available to the merchant (if applicable), as shown below. No additional action is required.

Note

The requestDeferred() method available in Kushki.js 1.0 is no longer needed in version 2.0.

Services available for migration#

Migrating the one-time payment token#

Step 1. Update the library import source#

Step 2. Library initialization#

Kushki.js 1.0#

Kushki.js 2.0#

Step 3. Update the payment form#

Step 4. Token request#

Kushki.js 1.0#

Kushki.js 2.0#

Response#

Step 5. Certification#

OTP validation for one-time payment#

Step 1. Add the hosted field for OTP#

Step 2. Identify the OTP status#

Step 3. Link the OTP div in the CardOptions instance#

Step 4. Certification#

3DS validation for one-time payment#

Step 1. Token request#

Deferred options for one-time payment#

Step 1. Token request#

Services available for migration

Migrating the one-time payment token

Step 1. Update the library import source

Step 2. Library initialization

Kushki.js 1.0

Kushki.js 2.0

Step 3. Update the payment form

Step 4. Token request

Kushki.js 1.0

Kushki.js 2.0

Response

Step 5. Certification

OTP validation for one-time payment

Step 1. Add the hosted field for OTP

Step 2. Identify the OTP status

Step 3. Link the OTP div in the CardOptions instance

Step 4. Certification

3DS validation for one-time payment

Step 1. Token request

Deferred options for one-time payment

Step 1. Token request