Introduction

The new version of our Javascript library is much lighter, safer, customizable and easier to implement. With Kushki.js Hosted Fields, create a payment flow in a simple way by implementing the fields hosted on Kushki servers, which offers control by the merchant in the design of the payment form, greater security and ease of implementation with optimized methods inside the library.

Below you can see the differences between each version:

Characteristic	Kushki.js	Kushki.js Hosted Fields	Details
Size	~2.7 MB	~307* KB
Modularity	NO	YES
Import via CDN	YES	YES
Import via NPM	YES	YES
Import via YARN	NO	YES
Library Settings	`Kushki()` object instance	`KushkiOptions()` object instance
Token for one-time payment	`requestToken()`	`requestToken()`	In Kushki.js Hosted Fields, an object of type `CardOptions()` must be created, which will contain information about the amount, the type of currency, among other transaction data.
amount property in token for one-time payment	String. Amount without breakdown	Object. Allows you to break down the purchase amount by iva, ice, subtotaliva and subtotaliva0.	Transaction amount.
months property in token for one-time payment	Integer	Not available	In Kushki.js Hosted Fields, deferrals are now returned in the token (if available for the merchant).
Currency property in token for one-time payment	String	String	Currencies available by country.
Card object inside the token for one-time payment	Object. Card information such as cardholder name, card number, cvc, etc.)	Not available	In Kushki.js Hosted Fields, the merchant no longer requires handling of sensitive card data information.
Callback property in token for one-time payment	Function	Not available
Fields object within token for one-time payment	Not available	Through the `CardOptions` object instance	The fields object allows you to relate the html div tags with the corresponding ids of the hosted fields to be rendered.
isSubscription property in token for one-time payment	Not available	Boolean. Allows you to indicate whether the generated token is for a subscription or not	In Kushki.js Hosted Fields the `isSubscription` property replaces the implementation of the `requestSubscriptionToken()` method.
preventAutofill property in token for one-time payment	Not available	Boolean. Allows you to prevent hosted fields from being filled in automatically.
styles property in token for one-time payment	Not available	Object. Allows you to modify hosted field styles.	In Kushki.js Hosted Fields, the library allows greater control of styles in fields.
Validation via OTP for one-time payment	`requestSecureServiceValidation()` method	Automatic validation (if applicable) in the `requestToken()` method.
Getting JWT for 3D Secure validation for one-time payment	`requestSecureInit()` method	Automatic validation (if applicable) in the `requestToken()` method.
Validation through 3D Secure for single payment	`requestValidate3DS()` method	Automatic validation (if applicable) in the `requestToken()` method.
Deferred for one-time payment	`requestDeferred()` method	Returned automatically upon consuming the `requestToken()` method (if available for the merchant).
Information about the bin for one-time payment	`requestBinInfo()` method	Not available	In Kushki.js Hosted Fields, it is not required to obtain the bin since the validations are done automatically in the `requestToken()` method.
Subscription token	`requestSubscriptionToken()`	When calling the `requestToken()` method, the `isSubscription` property can be sent as true to indicate that the token will be from a subscription.
Currency property in token for subscription	String	String	Currencies available by country.
Token card object for subscription	Object. Card information such as cardholder name, card number, cvc, etc.)	Not available	In Kushki.js Hosted Fields, the merchant no longer requires handling of sensitive card data information.
Callback property in token for subscription	Function	Not available
Token fields object for subscription	Not available	Through the `CardOptions` object instance	The fields object allows you to relate the html div tags with the corresponding ids of the hosted fields to be rendered.
isSubscription property in token for subscription	Not available	Boolean. Allows you to indicate whether the generated token is for a subscription or not	In Kushki.js Hosted Fields the `isSubscription` property replaces the implementation of the `requestSubscriptionToken()` method.
preventAutofill property in token for subscription	Not available	Boolean. Allows you to prevent hosted fields from being filled in automatically.
styles property in token for subscription	Not available	Object. Allows you to modify hosted field styles	In Kushki.js Hosted Fields, the library allows greater control of the styles in the fields.
OTP validation for subscription	Not available	Automatic validation (if applicable) in the `requestToken()` method
Getting JWT for 3D Secure validation for subscription	`requestSecureInit()` method	Automatic validation (if applicable) in the `requestToken()` method
Validation using 3D Secure for subscription	`requestValidate3DS()` method	Automatic validation (if applicable) in the `requestToken()` method
Obtaining the device token for one-click payments	`requestDeviceToken()`	`requestDeviceToken()`
Card Async	YES	Not available
Transfer In	YES	Not available
Cash In	YES	Not available
Payouts	YES (transfer, cash)	Only for card payouts

* Estimated size of both card.min.js and kushki.min.js libraries.

Note

New services and functionalities will be added over time.

Kushki provides a web-based SDK to facilitate secure collection of card details without manipulation of sensitive data via hosted fields on Kushki servers. This SDK allows obtaining the token from the frontend in order to later send it to the backend to continue with the payment flow.

Importing Kushki.js Hosted Fields

Include the Kushki.js Hosted Fields script within your application directly from the following installation options; Do not pack or host it yourself.

CDN

NPM

YARN

Import the Kushki.js Hosted Fields library into your application using a <script> tag. Once imported, you will be able to access the resources described below to create a payment flow with Kushki.

It is necessary to import the libraries kushki.min.js (which brings the necessary code to store your merchant’s credentials) and card.min.js (the module that brings the necessary functionalities for the flow with card payments).

Initializing Kushki.js Hosted Fields

To use the Kushki.js library, it is first necessary to create an instance of type KushkiOptions, which allows you to declare the public key of your merchant, as well as being able to select the environment (test or production) through the init() method.

You obtain the public key when creating an account and it is required when calling this method since an instance is generated that allows your merchant to be identified to Kushki.

Note

When your merchant is ready to accept real payments, it is important that you replace the test key with the production key.

TypeScript

JavaScript

import { IKushki, init, KushkiError, KushkiOptions } from "@kushki/js-sdk";

const kushkiOptions : KushkiOptions = {
  publicCredentialId: '<public-credential-id>', // This corresponds to the public credential of the merchant
  inTest: true
};

const buildKushkiInstance = async () => {
  try {
    const kushkiInstance : Ikushki =  await init(kushkiOptions);
  } catch (e: KushkiError) {
    console.error(e.message);
  }
}

Configuration Parameters

Property	Type	Required	Description	Default	Allowed Values
publicCredentialId	`string`	YES	Public ID created for your merchant.
inTest	`boolean`	NO	Allows you to indicate the work environment between test or production.	`false`	`true`, `false`

Form initialization

The following steps describe how you can initialize a card token instance.

Step 1. Define the containers for hosted fields

Before calling the initCardToken() method, it is required to include the necessary <div> elements to render each hosted field.

Property	Required	Description
cardholderName_id	YES	hosted field for the cardholder's name.
cardNumber_id	YES	hosted field for the cardholder's number.
cvv_id	YES	hosted field for the cvv.
expirationDate_id	YES	hosted field for the expiration date.
deferred_id	NO	hosted field for deferred payments.
otp_id	NO	hosted field for OTP validation.

For a one-time payment token, the required fields are:

cardholderName

cardNumber

expirationDate

cvv

For a subscription token, the required fields are:

cardholderName

cardNumber

expirationDate

Step 2. Create a CardOptions Instance

Create an instance of CardOptions with transaction information such as the amount, currency, among other parameters.

TypeScript

JavaScript

CardOptions Parameters

Property	Type	Required	Description	Allowed Values
amount	`object`	YES (For one-time payments)	Object with detailed transaction amount information.
currency	`string`	YES	Available currencies by country: MX 🇲🇽: MXN CO 🇨🇴: COP CL 🇨🇱: CLP, UF PE 🇵🇪: PEN, USD EC 🇪🇨: USD
fields	`object`	YES	Object to link website containers with hosted fields.
fields.cardNumber.selector	`string`	YES	Links with the container with id `cardNumber_id` and renders the field to enter the card number.
fields.cardholderName.selector	`string`	YES	Links with the container with id `cardholderName_id` and renders the field to enter the cardholder's name fields.
fields.cvv.selector	`boolean`	YES	Links with the container with id `cvv_id` and renders the field to enter the card's cvv. You can skip cvv.
fields.cvv.isRequired	`string`	NO	Configures whether CVV value entry is required or not. Applies only to subscriptions.
fields.deferred	`string`	NO	Links with the container with id `deferred_id` and renders the field to select deferred payments (if applicable).
fields.expirationDate	`string`	YES	Links with the container with id `expirationDate_id` and renders the field to enter the card's expiration month and year.
fields.otp.selector	`string`	NO	Links with the container with id `otp_id` and renders the field to enter the OTP value (if applicable).
isSubscription	`boolean`	NO	Allows identifying whether it is a subscription or not. Set as `true` to generate a scheduled payment or a One-click payment.	`true`, `false`
preventAutofill	`boolean`	NO	Allows preventing autofill of hosted fields.	`true`, `false`
styles	`object`	NO	Object for declaring custom styles for hosted fields.
styles.cardNumber	`CssProperties`	NO	Allows modifying the styles of the field to enter the card number.
styles.cardholderName	`CssProperties`	NO	Allows modifying the styles of the field to enter the cardholder's name.
styles.container	`CssProperties`	NO	Allows modifying the styles of the input container.
styles.cvv	`CssProperties`	NO	Allows modifying the styles of the field to enter the card's cvv.
styles.deferred	`CssProperties`	NO	Allows modifying the styles of the field for deferred payments.
styles.expirationDate	`CssProperties`	NO	Allows modifying the styles of the field for the card's expiration month and year.
styles.focus	`CssProperties`	NO	Allows modifying the styles when the field has focus.
styles.input	`CssProperties`	NO	Allows modifying the input styles.
styles.invalid	`CssProperties`	NO	Allows modifying the styles when a field is invalid.
styles.label	`CssProperties`	NO	Allows modifying the styles of the input label.
styles.otp	`CssProperties`	NO	Allows modifying the styles of the OTP field.
styles.valid	`CssProperties`	NO	Allows modifying the styles when a field is valid.
fullResponse	`boolean`	NO	Allows you to obtain additional information when generating a token for subscriptions.

Step 3. Render hosted Fields with the initCardToken() Method

After creating an instance of CardOptions, it is necessary to call the initCardToken() function to initialize an instance of ICard. This function takes the instance created in the Initializing Kushki.js Hosted Fields section and the instance with transaction options created in Step 2. Create a CardOptions Instance as parameters. It returns a promise of the ICard.

TypeScript

JavaScript

Parameters

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Instance with the merchant's public key and working environment.
options	`CardOptions`	YES	Must define the configuration of card fields (set transaction amount, currency, subscription status, autofill prevention, add custom CSS styles, add custom fields).

Errors

Here are the possible errors that the initCardToken() function may return:

Code	Message	Example	Description
E012	Error en inicialización de campos	`{ code: "E012", message: "Error en inicialización de campos" }`	If the parameters `options` or `kushkiInstance` are null or undefined, it will return an E012 error.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	If any field has a non-existing selector in the `options.fields` parameter, it will return an E013 error.

Tokenization

Request a payment token with a card that you can later use to charge a customer using the endpoint for a one-time payment, create a recurring charge or to make an One-click payment.

requestToken()

To obtain a payment token with a card, it is necessary to call the requestToken() method on the previously initialized card instance. This method also performs validation by confirming that all fields are correct; otherwise, it will throw an exception.

This method returns a TokenResponse object that you should send to your backend to continue with the payment flow. Next, you need to make a charge with the obtained token.

Note

Check the subscriptions section to request a subscription token.

If your merchant has OTP, 3D Secure, or Sift Science validation rules enabled, this method automatically performs validations for each rule and renders the corresponding modals for each case.

Example of returned token response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Deferred Payments

If your merchant has enabled the deferred payments option, when calling the requestToken() method, it will return the following information based on your merchant's country:

México y Ecuador

In addition to the token, the requestToken() method will return the following fields within the deferred object:

creditType: Transaction type.

graceMonths: Months of grace.

months: Months to defer the transaction.

Available creditType per country:

Ecuador 🇪🇨

Fixed installments with interest.

Months of grace with interest.

Monthly payment by month with interest.

Fixed installments without interest.

Months of grace without interest.

Monthly payment by month without interest.

Special without interest.

Supermaxi promo.

México 🇲🇽

"03" = Non-interest-bearing months.

For the non-interest-bearing months in Mexico, there is a minimum amount depending on the installment plan for deferring the transaction:

3 months: $300 MXN

6 months: $600 MXN

9 months: $900 MXN

12 months: $1,200 MXN

18 months: $1,800 MXN

Example response with the deferred object for merchants in Mexico and Ecuador:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "creditType": "03",
    "graceMonths": 2,
    "months": 12
  }
}

Chile, Colombia, and Peru

In addition to the token, the requestToken() method returns a deferred object. The structure of this object depends on the integration model configured for the merchant:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "months": 12
  }
}

Chile: Merchant Installments available (Cuotas Comercio)

🚀 Beta Feature

The Merchant Installments (Cuotas Comercio) feature is currently in Beta. This response structure applies only when the payer selects a Merchant Installment option available for your commerce configuration.

When a Merchant Installment is selected, the deferred object includes additional parameters required to process the payment correctly:

creditType: Returns "03" (Fixed value for Merchant Installments).

graceMonths: Returns 0 (Fixed value).

months: The number of months selected by the payer.

Example Response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "deferred": {
    "creditType": "03",
    "graceMonths": 0,
    "months": 6
  }
}

Response

Below are the properties that can be returned in the token request for one-time payments.

Property	Type	Description
`token`	`String`	Token to make a charge.
`deferred`	`Object`	Optional. Object returned if the bin and merchant have deferred enabled.
`deferred.creditType`	`String`	Optional. Type of credit requested. For Chile Cuotas comercio will be `03`.
`deferred.graceMonths`	`String`	Optional. Months of grace. • Ecuador: Standard behavior. • Chile Cuotas comercio: Returned only for the Kushki Acquiring model with a fixed value of `0`. More information in the Make a charge or deferred charge endpoint.
`deferred.months`	`Integer`	Optional. Number of installments.

Errors

Below is the list of errors that the requestToken() method can return as a KushkiError object:

Code	Message	Example	Description
E002	Token request error	`{ code: "E002", message: "Error en solicitud de token" }`	If there was an error when requesting a token, the error code E002 will be returned. Please validate that the required information has been sent correctly.
E003	Merchant data request error	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	If there was an error when requesting merchant information. Please try again; if the error persists, contact Kushki support.
E004	JWT request error	`{ code: "E004", message: "Error en solicitud de JWT" }`	If the merchant has a rule for 3D Secure enabled and there was an error requesting the JWT. Please try again; if the error persists, contact Kushki support.
E005	Invalid 3D Secure fields	`{ code: "E005", message: "Campos 3DS inválidos" }`	If the merchant has a rule for 3D Secure enabled and there was an error in the 3D Secure authentication. Please try again, making sure to enter the data correctly for 3D Secure validation.
E006	Token validation request error	`{ code: "E006", message: "Error en solicitud de validación de token" }`	If the merchant has a 3D Secure rule enabled and there was an error in the 3D Secure validation session. Please try again, making sure to enter the data correctly for 3D Secure validation; if the error persists, contact Kushki support.
E007	Form validation error	`{ code: "E007", message: "Error en la validación del formulario" }`	If any hosted field is invalid, the error code E007 will be returned. Please try again, making sure to enter the requested data correctly.
E008	OTP validation error	`{ code: "E008", message: "Error en la validación de OTP" }`	If OTP validation is not correct, the onError callback will return error code E008. Please try again by entering the correct data for OTP validation.

Examples

One-time charge or subscription without deferred payments.

TypeScript

JavaScript

One-time charge with deferred payments
Example of how to handle the response when deferred payments are involved.

Security

OTP

A One-Time Password (OTP) is used when it is necessary to validate the cardholder's identity, confirming that the card owner is the one conducting the transaction. This helps reduce fraud and enhances security for online transactions in your merchant.

Consider using OTP when your merchant experiences a substantial amount of fraud or for transactions that are particularly sensitive or involve high amounts. Keep in mind that this may lead to a lower conversion rate as additional steps are added to the payment process.

You can configure for which types of transactions OTP validation will be required, such as when the transaction amount exceeds a certain threshold.

Note

This feature is available only for web integrations in one-time card payments.

Important

Keep in mind that, due to our risk policies, available payment methods and the type of integration may vary when formalizing affiliation. We will guide you on how to proceed if this process applies to your merchant.

For more information on OTP, visit our page accept one-time payments with OTP.

onOTPValidation()

If you need to validate the OTP flow, you can use the onOTPValidation() method on the previously created card instance for your Kushki.js hosted fields implementation. This is triggered when a value is entered into the OTP field to validate the code. This method returns three callbacks (onSuccess, onError and onRequired) that allow you to identify the status of OTP validation on the hosted fields.

Note

The user will have 3 attempts to enter a valid OTP.

This validation will only run if the merchant has configured the security rule associated with OTP.

OTP validation is activated when the third digit is entered in the hosted field. Each validation event will be activated, and you can capture these events using the onError or onSuccess callbacks.

Parameters

onRequired (() => void): This callback is executed when the created token requires OTP validation.

onError ((error) => void): This callback is executed when OTP validation returns an error.

onSuccess (() => void): This callback is executed when OTP validation is successful.

Errors

If the OTP validation is incorrect, the onError callback will return the following error messages:

Code	Message	Example	Description
E008	Error en la validación de OTP	`{ code: "E008", message: "Error en la validación de OTP" }`	If the OTP validation is incorrect, the `onError` callback will return the error code `E008`. Please try again by entering the correct data for OTP validation.

Examples

Handling onOTPValidation() events for the OTP hosted field.

3D Secure

By default, 3D Secure authentication will be performed automatically when generating a token and if necessary, a modal will be displayed for the cardholder to complete the challenges required to complete the transaction. Authentication will be carried out according to the security rules established in your merchant configuration.

You can also perform manual 3D Secure authentication on an integration through our API using the requestSecureInit() method. This method allows you to obtain a Json Web Token (JWT) which will be required to obtain a card token. Subsequently, call the requestValidate3DS() method, which will display a modal, if necessary, so that the cardholder can carry out the requested challenges.

Below are the steps to perform manual 3D Secure authentication.

requestSecureInit()

Consume the requestSecureInit() method by sending the card number to get a JWT.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.
secureInitRequest	`SecureInitRequest`	YES	You must define this object in order to request the initialization of 3D Secure.

Errors

Below is the list of errors that the requestSecureInit() method can return as a KushkiError object:

Code	Message	Example	Description
E004	JWT request error	`{ code: "E004", message: "Error en solicitud de JWT" }`	If the merchant has a rule for 3D Secure enabled and there was an error requesting the JWT. Please try again; if the error persists, contact Kushki support.
E018	Longitud de tarjeta inválida (Invalid card length)	`{ code: "E018", message: "Longitud de tarjeta inválida" }`	Please verify that the card length is correct.
E019	Comercio no tiene activo 3DS (Merchant does not have 3DS enabled)	`{ code: "E019", message: "Comercio no tiene activo 3DS" }`	Operation not permitted. Merchant does not have 3D Secure authentication enabled.

If the request was successful, you will receive the JWT as shown below:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ2NTg0ODgsImlhdCI6MTY1NDY1MTI4OCwiaXNzIjoiNWVhMzJmZDJmZjQ2NDU2OTY3YjUyNDliIiwianRpIjoiZjc4NzQzNTctMmY2Zi00OTExLTg3MDctZDBmN2RlYTZlNTk4IiwiT3JnVW5pdElkIjoiNWVhMzJmZDJhZDA3ZDIxYTM2OTc4OGFlIiwiUmVmZXJlbmNlSWQiOiIyZDdhOTA2OS04MjhjLTQxNDItYWYwNC1hMjZjNWI4YzQ3MjMifQ.5nmFrf3sOAxKNIcJTzc5i2GNY5ALABpu42YsrHIibio"
}

Once the JWT is obtained, it is necessary to consume the endpoint to request a card token by sending the JWT in the body of the request.

{
  "card": {
    "name": "John Doe",
    "number": "4000000000000002",
    "expiryMonth": "01",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 59,
  "currency": "USD",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ2NTg0ODgsImlhdCI6MTY1NDY1MTI4OCwiaXNzIjoiNWVhMzJmZDJmZjQ2NDU2OTY3YjUyNDliIiwianRpIjoiZjc4NzQzNTctMmY2Zi00OTExLTg3MDctZDBmN2RlYTZlNTk4IiwiT3JnVW5pdElkIjoiNWVhMzJmZDJhZDA3ZDIxYTM2OTc4OGFlIiwiUmVmZXJlbmNlSWQiOiIyZDdhOTA2OS04MjhjLTQxNDItYWYwNC1hMjZjNWI4YzQ3MjMifQ.5nmFrf3sOAxKNIcJTzc5i2GNY5ALABpu42YsrHIibio"
}

If the request was correct, you will receive the token along with other properties related to 3D Secure validation.

Note

If the authRequired property within the security object (security.authRequired) returns true, it will be necessary to consume the requestValidate3DS() method to display the modal so that the cardholder can do the corresponding authentication.

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1",
  "secureService": "3dsecure",
  "secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
  "security": {
    "acsURL": "[https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA](https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)",
    "authenticationTransactionId": "uvvZn0ND0ukTOJIfhfi0",
    "authRequired": true,
    "paReq": "eNpVUstuwjAQvPsrItRTD7HjhAjQYokWqQVUSksqKm5RYkiU5oFjE/j72iFAK/mws7Nr78wagkRwPl3zSAnO4I3XdbjnVhqPe+p43BZkOSUqC97ns12yS0mPwWryyQ8MjlzUaVkwxyY2BXyFSF8hoiQsJIMwOjzNlszzh9TxAXcQQc7FbMr6nksdAviCEBRhztlivXh8ScpaWitRxiqSpRXwWqYF4JZHEJWqkOLMfOIBvgIESvywRMpqhHHTNHam6iRLq3Bf1nZU5oANjwDfh1spE9Va8ymNWfy9pZvca4Lso4k38isg1XybJ3kYTMaATQWCOJScUUIp8cnAIu5IH1cP0eYRhLkZhj30hzbRsjqIoDIPTS6oPzTU34wWpITgRXRmA09zN4SAn6qy4LpG23uLtYb75M+vxuRIGjd9z3UpNS63uG1PtTXUJ07bn7Y+YdODux3ibt06+vcNfgHbNq5L",
    "specificationVersion": "2.2.0"
  }
}

More information in the requestSecureInit method definition.

requestValidate3DS()

Consumes the requestValidate3DS() method in case the transaction needs to be authenticated using 3D Secure. The requestValidate3DS() method receives as a parameter the object obtained when requesting a card token.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.
cardTokenResponse	`CardTokenResponse`	YES	The response object from the card tokenization process using the API.

Errors

Below is the list of errors that the requestValidate3DS() method can return as a KushkiError object:

Code	Message	Example	Description
E005	Campos 3DS inválidos (Invalid 3DS fields)	`{ code: "E005", message: "Campos 3DS inválidos" }`	If the merchant has a 3D Secure rule enabled and there was an error in the 3D Secure authentication. Please try again making sure to enter the data correctly for the 3D Secure validation.
E006	Error en solicitud de validación de token (Token validation request error)	`{ code: "E006", message: "Error en solicitud de validación de token" }`	If the merchant has a 3D Secure rule enabled and there was an error in the 3D Secure validation session. Please try again making sure to enter correctly the data for the 3D Secure validation, if the error persists contact Kushki support.

If the authentication was correct, the previously generated token will be returned.

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1"
}

If there was a problem during authentication, a TokenResponse object will be returned with the error information.

{
  "code": "E012",
  "message": "Error en inicialización de campos"
}

If the authentication has been successfully completed, you can continue with the payment flow by consuming the endpoint to make a charge, otherwise it will be necessary to start the payment flow again by initializing the 3D Secure authentication by consuming the requestSecureInit() method and following the steps described above.

More information in the requestValidate3DS method definition.

Sift

Protect the integrity of your online transactions and safeguard your customers' trust through the artificial intelligence fraud detection tool, Sift. With Sift, you will be able to detect and prevent fraudulent activities in real time, reducing financial losses and protecting your reputation, ensuring a secure and frictionless shopping experience for your customers.

By default, Sift authentication will be performed automatically when generating a token and if necessary, a modal will be displayed for the cardholder to complete the challenges required to complete the transaction. Authentication will be carried out according to the security rules established in your merchant configuration.

You can also perform manual Sift authentication on an integration through our API using the requestInitAntiFraud() method. This method allows you to obtain a Json Web Token (JWT) which will be required to obtain a card token.

Below are the steps to perform manual Sift authentication.

requestInitAntiFraud

Call the requestInitAntiFraud method by sending a Kushki instance with your merchant configuration and customer id.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.
userId	`String`	YES	Client ID. It can be email, phone number, address or empty.

Errors

Below is the list of errors that the requestInitAntiFraud() method can return as a KushkiError object:

Code	Message	Example	Description
E003	Error en solicitud de datos del comercio (Error in requesting merchant data)	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	If there was an error requesting merchant information. Please try again if the error persists contact Kushki support.
E023	Error al configurar sesión de Sift	`{ code: "E023", message: "Error al configurar sesión de Sift" }`	Sift configuration error. Please check your Sift settings and try again.

More information in the requestInitAntiFraud method definition.

Subscriptions

You can generate a subscription token to execute a recurring charge or an one-click payment.

To generate a token for a subscription, you must set the isSubscription property to true when creating a CardOptions instance.

TypeScript

JavaScript

Next, request a card token.

Skip CVV

You can skip, mark as required or optional the CVV field during the creation of a token for subscriptions.

Important

Available only in Colombia for aggregator model. Before you can skip or mark the CVV entry as optional, you must validate the functionality with your account manager.

To make the CVV entry optional, you must send the isRequired flag as false inside the object with the settings for the CVV field.

If you want to skip the CVV field, do not send the configuration for the CVV field inside the CardOptions object.

Then, follow the next steps to obtain a token.

Recurring charge

After requesting a token for subscription, you must call the Create a recurring charge endpoint by submitting the required information.

Note

Remember to set the frequency for the automatic charge to be executed.

If the information sent is valid, the subscription will be created and executed according to the established periodicity.

One-click payments

Kushki allows you to make one-click payments by storing card information securely and then charging on demand.

To make a one-click payment, you must first create a subscription by submitting the periodicity property with the value of custom to get a subscriptionId.

Then, you must call one of the following methods depending on whether you need to validate the CVV when executing an on-demand charge.

requestDeviceToken()

To use this method, a subscriptionId is required. It must have been previously created using the recurring charge API with a token obtained from requestToken, where the isSubscription flag was set to true.

Note

This method is used directly without validating the cvv in a hosted field.

Click here for more information.

Example

Errors

Below is the list of errors that the requestDeviceToken() method can return as a KushkiError object:

Code	Message	Example	Description
E003	Merchant data request error	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	If there was an error when requesting merchant information. Please try again; if the error persists, contact Kushki support.
E004	JWT request error	`{ code: "E004", message: "Error en solicitud de JWT" }`	If the merchant has a rule for 3D Secure enabled and there was an error requesting the JWT. Please try again; if the error persists, contact Kushki support.
E005	Invalid 3DS fields	`{ code: "E005", message: "Campos 3DS inválidos" }`	If the merchant has a rule for 3D Secure enabled and there was an error in the 3D Secure authentication. Please try again, making sure to enter the data correctly for 3D Secure validation.
E006	Token validation request error	`{ code: "E006", message: "Error en solicitud de validación de token" }`	If the merchant has a 3D Secure rule enabled and there was an error in the 3D Secure validation session. Please try again, making sure to enter the data correctly for 3D Secure validation; if the error persists, contact Kushki support.
E016	Error in UserId request for subscription	`{ code: "E016", message: "Error en solicitud de UserId para subscripción" }`	If the merchant has Sift Science configurations and `options.subscriptionId` into body is not found or the request fails then throw E016 error. Please try again, making sure to enter the requested data correctly.
E020	Merchant data request error	`{ code: "E020", message: "Error, configuración de campos requeridos no encontrada" }`	If `DeviceTokenRequest` body is not defined, then it throws this error.

After obtaining the token using the requestDeviceToken() method, you need to call the make an One-click payment endpoint from your backend to perform a One-click payment.

Secure DeviceToken

If you need to validate the CVV when performing an One-click payment, call the Secure DeviceToken method. This is the second method to obtain a deviceToken, but it uses a hosted field to validate the card's CVV.

Note

You can skip entering the CVV when obtaining a token and request it when charging on demand. More information in the CardOptions reference.

If your merchant has 3D Secure or Sift Science validation rules enabled, this method automatically performs validations for each rule and renders the corresponding modals for each case.

To validate the CVV, follow the steps below:

Form initialization

You first need to define the container where the field to enter the CVV will be displayed.

SecureDeviceTokenOptions instance

Create an instance of SecureDeviceTokenOptions.

Property	Type	Required	Description	Allowed Values
fields.cvv.selector	`string`	YES	Links with the container with id `cvv_id` and renders the field to enter the card's cvv.
preventAutofill	`boolean`	NO	Allows preventing autofill of hosted fields.	`true`, `false`
styles	`Styles`	NO	Object for declaring custom styles for hosted fields.

Step 1: Call the initSecureDeviceToken() method

Call the initSecureDeviceToken() method which renders cvv hosted field and init an instance of ICardSubscriptions.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.
options	`SecureDeviceTokenOptions`	YES	Object to get device token for one-click payment.

Errors

Below is the list of errors that the initSecureDeviceToken() method can return as a KushkiError object:

Code	Message	Example	Description
E012	Error en inicialización de campos	`{ code: "E012", message: "Error en inicialización de campos" }`	If the parameters `options` or `kushkiInstance` are null or undefined, it will return an E012 error.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	If any field has a non-existing selector in the `options.fields` parameter, it will return an E013 error.

Step 2: Call the requestDeviceToken() method

To get a secure device token, you should call the requestDeviceToken method on your card subscription instance that was previously initialized, this method also validates if the cvv field is valid, otherwise it will throw an exception.

Example

Response

This method returns a TokenResponse object that you will send to you backend and proceed with the charge of one-click payment or subscription on demand.

Below are the properties that can be returned in the token request for subscriptions.

Property	Type	Description
token	`String`	Token to make a charge.
cardInfo	`Object`	Optional. If the `fullResponse` property is set to `true` when instantiating CardOptions to create the subscription, this object will be returned with additional information.
cardInfo.bin	`String`	Optional. The card bin (8 digits).
cardInfo.brand	`String`	Optional. The card brand.
cardInfo.expirationDate	`String`	Optional. The card expiration date.
cardInfo.lastFourDigits	`String`	Optional. The card last four digits.

Example of returned token response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Example of returned token response with cardInfo object:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16",
  "cardInfo": {
    "bin": "42424242",
    "brand": "visa",
    "expirationDate": "11/27",
    "lastFourDigits": "4242"
  }
}

Card Payouts

The Card Payouts process enables you to securely capture cardholder and card details to generate a unique payment token. This token can be used for:

One-time payouts: Send money to a card once using a single-use payment token.

Recurring payouts: Obtain a subscription token to send money multiple times to the same tokenized card.

Form initialization

The first step is to define the container for the required hosted fields.

Next, define a CardPayoutOptions object and call the initCardPayoutToken method. This will render the hosted fields on your side, allowing the user to enter their card details and complete the tokenization process. More examples here.

Styling

Use the same methodology as in Card Token Styles. The difference is that these styles apply specifically to the fields required for this tokenization method. Additionally, note that the isSubscription field is a checkbox, so specific styles must be applied to this input type. For more details, click here.

Events

Use the same methodology as in Card Token Events. The difference is that these events apply specifically to the fields required for this tokenization method. For more details, click here.

Get a Card Payout Token

To obtain a card payout token, call the requestCardPayoutToken method on your previously initialized card payout instance. This method also validates whether the fields contain valid values; otherwise, it will throw an exception.

This method returns a CardPayoutTokenResponse object, which you must send to your backend to proceed with the payment or subscription charge. The response type depends on the isSubscription field:

If isSubscription is checked, the response will be a CardPayoutSubscriptionTokenResponse, which includes a subscriptionId.

Otherwise, it will return a CardPayoutUniqueTokenResponse, which provides a one-time token.

Basic Example

Apple Pay Integration

WARNING

Watch Out!
The Apple Pay functionality is currently in a testing phase. It is only available for merchants in Chile 🇨🇱 and Peru 🇵🇪, and supports Visa and Mastercard cards.

Please note that this functionality is subject to change without prior notice.

Get Card Token from Apple Pay

The initApplePayButton method enables you to easily render the Apple Pay button and initialize a payment session via the Kushki API.

Prerequisites

Secure Domain (HTTPS): Your website must be served over a secure HTTPS connection.

Domain Verification: You must verify your domain ownership with Kushki before integrating.

Get the File: Request the apple-developer-merchantid-domain-association file from Kushki Support (specify if it is for UAT or Production).

Host the File: Upload the file to your server at the following specific path:
https://{your-domain}/.well-known/apple-developer-merchantid-domain-association

Register Domain: Log in to the Kushki Console, go to Configuration > Integrations > Apple Pay, and register your domain URL.

HTML Container: Include a container element in your HTML where the Apple Pay button will be rendered:

Device Availability: The user must be using a compatible device (iOS or macOS) with Safari, and have a valid card added to their Apple Wallet.

Quick Example

First, add this HTML container where you want the Apple Pay button to be rendered on your page:

Once the HTML container is set, this JavaScript block initializes Kushki.js, configures the Apple Pay button, and defines the logic to request the Kushki card token upon click.

Important Notes

The Apple Pay button is automatically rendered inside the container specified by its ID (i.e., #kushki-apple-pay-button).

The token returned by the requestApplePayToken method is a Kushki card token, not an Apple token. This token is pre-processed and ready to be used directly in Kushki’s API to perform a charge card transaction.

For a complete reference on this and related methods, see the Detailed documentation.

Other methods

requestBankList

Get the list of available banks and their ids through the requestBankList() method. You must send the ID of the selected bank when requesting a transfer token.

Send a valid IKushki object when calling the requestBankList() method to get the complete list of available banks.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.

Errors

Below is the list of errors that the requestBankList() method can return as a KushkiError object:

Code	Message	Example	Description
E014	Error en solicitud de lista de bancos (Error in bank list request)	`{ code: "E014", message: "Error en solicitud de lista de bancos" }`	If there was an error in obtaining the bank list, the error code E014 will be returned. Please try again making sure to enter the card data correctly, if the error persists contact Kushki support.

More information in the requestBankList method definition.

requestBrandsByMerchant

Get the list of card networks available in your merchant by calling the requestBrandsByMerchant() method. This information can be useful to display the payment options available in your store.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.

Errors

Below is the list of errors that the requestBrandsByMerchant() method can return as a KushkiError object:

Code	Message	Example	Description
E021	Error en solicitud de marcas de tarjetas del comercio	`{ code: "E021", message: "Error en solicitud de marcas de tarjetas del comercio" }`	Please check the information sent and try again.

More information in the requestBrandsByMerchant method definition.

requestCommissionConfiguration

This method only works when the Split Payment mode is enabled. The Split Payment collection mode allows dividing the payment of one transaction into two recipient merchants: the main merchant and the Commission Recipient Merchant.

Use this method to calculate the amount that would be paid on a given transaction to the Commission Recipient Merchant.

INFO

Note
The Split Payment mode is only available on demand in Ecuador.

Property	Type	Required	Description
kushkiInstance	`IKushki`	YES	Object with public merchant id and work environment.
body	`CommissionConfigurationRequest`	YES	Object with information on the currency and the amount to calculate the commissions.

Errors

Below is the list of errors that the requestCommissionConfiguration() method can return as a KushkiError object:

Code	Message	Example	Description
E015	Error en solicitud de configuración de comisión (Error in commission configuration request)	`{ code: "E015", message: "Error en solicitud de configuración de comisión" }`	If there was an error getting the commission settings for the merchant, error code E015 will be returned. Please try again making sure you submit the required information correctly.

More information in the requestCommissionConfiguration method definition.

requestInitCardBrandingAnimation

The Card Branding Animation gives users meaningful confirmation of their payment.

Apply this animation only when the user has selected a Mastercard or Visa card to make payment, and play it after a transaction is complete.

You need to define a container where the animation will appear.

Set one of the following valid ids to the container:

visa-sensory-branding: for Visa card transactions

mastercard-sensory-branding: for Mastercard card transactions

Next, call the requestInitCardBrandingAnimation method to render the animation after an approved transaction.

Property	Type	Required	Description
opts	`CardBrandingRequest` (Visa, Mastercard)	YES	Object with animation settings.

Errors

Below is the list of errors that the requestInitCardBrandingAnimation() method can return as a KushkiError object:

Code	Message	Example	Description
E022	Error al generar animación	`{ code: "E022", message: "Error al generar animación" }`	Please verify that the animation configuration parameters are correct.

More information in the requestInitCardBrandingAnimation method definition.

kushki.js Hosted Fields

Introduction#

Importing Kushki.js Hosted Fields#

Initializing Kushki.js Hosted Fields#

Configuration Parameters#

Form initialization#

Step 1. Define the containers for hosted fields#

Step 2. Create a CardOptions Instance#

CardOptions Parameters#

Step 3. Render hosted Fields with the initCardToken() Method#

Errors#

Tokenization#

requestToken()#

Deferred Payments#

México y Ecuador#

Chile, Colombia, and Peru#

Chile: Merchant Installments available (Cuotas Comercio)#

Errors#

Examples#

Security#

OTP#

onOTPValidation()#

3D Secure#

requestSecureInit()#

requestValidate3DS()#

Sift#

requestInitAntiFraud#

Subscriptions#

Skip CVV#

Recurring charge#

One-click payments#

requestDeviceToken()#

Secure DeviceToken#

Form initialization#

SecureDeviceTokenOptions instance#

Step 1: Call the initSecureDeviceToken() method#

Step 2: Call the requestDeviceToken() method#

Card Payouts#

Form initialization#

Styling#

Events#

Get a Card Payout Token#

Apple Pay Integration#

Get Card Token from Apple Pay#

Prerequisites#

Quick Example#

Other methods#

requestBankList#

Errors#

requestBrandsByMerchant#

Errors#

requestCommissionConfiguration#

requestInitCardBrandingAnimation#

Introduction

Importing Kushki.js Hosted Fields

Initializing Kushki.js Hosted Fields

Configuration Parameters

Form initialization

Step 1. Define the containers for hosted fields

Step 2. Create a CardOptions Instance

CardOptions Parameters

Step 3. Render hosted Fields with the initCardToken() Method

Errors

Tokenization

requestToken()

Deferred Payments

México y Ecuador

Chile, Colombia, and Peru

Chile: Merchant Installments available (Cuotas Comercio)

Errors

Examples

Security

OTP

onOTPValidation()

3D Secure

requestSecureInit()

requestValidate3DS()

Sift

requestInitAntiFraud

Subscriptions

Skip CVV

Recurring charge

One-click payments

requestDeviceToken()

Secure DeviceToken

Form initialization

SecureDeviceTokenOptions instance

Step 1: Call the initSecureDeviceToken() method

Step 2: Call the requestDeviceToken() method

Card Payouts

Form initialization

Styling

Events

Get a Card Payout Token

Apple Pay Integration

Get Card Token from Apple Pay

Prerequisites

Quick Example

Other methods

requestBankList

Errors

requestBrandsByMerchant

Errors

requestCommissionConfiguration

requestInitCardBrandingAnimation