Kushki.js 🌐

Kushki.js is our JavaScript library for building payment flows with your own style. You can collect all the card information from your client and generate a token that will safely save and send that data to your servers.

TIP

We make it easier!
This library handles the complexity of secure payments so you can focus on your web experience.

📦 Import Kushki.js

Choose the installation method that fits your project structure.

Option 1 - CDN

Option 2 - NPM

Use a script tag inside your page to add the features. When adding the following code to your page it will be imported.

Update package.json:
Add this to your postinstall scripts to run every time you execute npm install:

"scripts": {
    "postinstall": "node patch.js"
}

🛠️ Usage

Begin creating your Kushki instance. This will allow you to perform all the functions available in Kushki.js.

Configuration Parameters

Required

Property	Type	Description	Default	Possible Values
merchantId	String	Kushki ID created for your merchant
inTestEnvironment	boolean	Value to define if you are in production or test environment	`false`	`true` , `false`

Optional

Property	Type	Description	Default	Possible Values
regional	Boolean	Define if use a static IP to Kushki access	`false`	`true`,`false`

⚡ Examples

Find the methods available in our Kushki.js library along with examples.

Security Note

The token delivered by Kushki only encrypts and sends information. If you want to store the card information for future purchases, go to the Recurring Charges Examples section.

One-Time Payment Examples

💳 Card Token

🛡️ 3DS & OTP

⏳ Card Async 🇨🇱

🍏 Apple Pay

🏦 Transfer In

💵 Cash In

requestToken()

To create a card token, you can use this function.

Required Parameters

Property	Type	Description
`amount`	`String`	The amount to collect.
`currency`	`String`	`USD`, `COP`, `CLP`, `UF`, `PEN`, `MXN`.
`card`	`Object`	The card data collected.
`callback`	`Function`	Handles the response.

Optional Parameters

Property	Type	Description
`months`	`Integer`	Installments (Chile only). Min: 2, Max: 48.

Response Scenarios

Successful response will be in the function (callback):

{ 
    "token": "90a9f2d93ba508c38971890454897fd4"
}

The following is a response when the merchant has the OTP validation activated:

{ 
    "token": "90a9f2d93ba508c38971890454897fd4",
    "secureId": "5e44449e-869b-4fed-bbca-e1bfa5af53c3",
    "secureService": "KushkiOTP"
}

The following is a response when the merchant has the 3DS validation activated:

{ 
    "token": "90a9f2d93ba508c38971890454897fd4",
    "secureId": "1c3a9ada-1287-4f8b-b1a9-dadf44a39dd3",
    "secureService": "3dsecure",
    "security": {
        "acsURL": "",
        "authenticationTransactionId": "OWgXwASsYPW4hr1ATcf0",
        "authRequired": true,
        "paReq": "sandbox",
        "specificationVersion": "1.0.2"
    }
}

Error response will be in the function (callback):

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

requestDeferred()

To get deferred options according to merchant deferred configurations specified in Backoffice.

Request

Required

Property	Type	Description
bin	String	The bin that is going to be validated for deferred options
callback	Function(response)	The created `callback` function()

Response

Successful response will be in the function (callback):

Ecuador

[
  {
    "name": "Diferido Cuota Fija sin intereses",
    "type": "04",
    "months": ["3", "6", "12"],
    "monthsOfGrace": ["1", "2"]
  },
  {
    "name": "Diferido Cuota Fija con intereses",
    "type": "01",
    "months": ["3", "6", "9"],
    "monthsOfGrace": []
  }
]

Chile: Issuer & Merchant Installments available

[
  {
    "type": "ALL",
    "months": ["2", "3", "4", "...", "48"],
    "monthsOfGrace": []
  },
  {
    "type": "03",
    "months": ["2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"],
    "monthsOfGrace": []
  }
]

The Merchant Installments (Cuotas Comercio) feature—identified by specific type "03" is currently in Beta.

Parameter	Type	Description	Countries/Notes
`name`	`string`	The name of the deferred payment option (e.g., "Diferido con intereses," "Meses sin intereses," "Regular").	Note: This field may not always be returned in the response.
`type`	`string`	A code that identifies the deferred option type.	The value can be a specific code (e.g., `"001"`, `"002"`) or the keyword `"ALL"` for countries like Perú or Colombia, where it applies to all deferred options.
`months`	`string[]`	An array of available payment terms (number of months).	Required for deferred payments.
`monthsOfGrace`	`string[]`	An array of available grace periods in months.	This field is optional and is only present if the bank/card allows a grace period for the specific deferred type.

Error response will be in the function (`callback`):

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

requestBinInfo()

Returns an object with the information related to the credit-card bin (first eight digits). For Chilean merchants, the response is helpful to decide whether to continue with the request of a card token (when cardType is CREDIT), or with the request of a card async token (when cardType is DEBIT):

Request

Required

Property	Type	Description
bin	String	The first eight digits of the credit card
callback	Function(response)	The created `callback` function()

Response

Successful response will be in the function (callback):

{
    "bank": "BANCO DE LA PRODUCCION S.A. (PRODUBANCO)",
    "brand": "visa",
    "cardType": "debit",
    "country": "Ecuador"
}

Error response will be in the function (callback):

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

Recurring Charges Examples

💳 Card Subscription

⏳ Card Async 🇨🇱

requestSubscriptionToken()

To create a recurring charge token.

Required

Property	Type	Description	Default	Possible Values
card	Object	The card data collected in an card object
currency	String	Code of currency used	`USD`	`USD`, `COP`, `CLP`, `UF`, `PEN`, `MXN`
callback	Function(response)	The created `callback` function()		* Success : `{ token: "90a9f2d93ba508c38971890454897fd4"}` * Error: `{ message:"error-message", code:"error-code", error: "error-message"}`

Response

Successful response will be in the function (callback):

{ 
  "token": "90a9f2d93ba508c38971890454897fd4"
}

Error response will be in the function (callback):

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

The following is a response when the merchant has the 3DS validation activated:

{
    "token": "oaACBE1012310zYTjE239227yqFRA8r7",
    "secureService": "3dsecure",
    "secureId": "e356d68d-3f31-4134-a9a7-8cba46b3cdac",
    "security": {
        "acsURL": "https://authentication.cardinalcommerce.com/ThreeDSecure/V1_0_2/PayerAuthentication?issuerId\u00d2aa20412b0063aca652facd9g\u0034transactionId\u003dQhcf3XOjdZmjve336Vee2gb5rof1",
        "authenticationTransactionId": "1d8cf7jg5Bfn8Nj73mn7",
        "paReq": "eNpVUtluwjAQfPdXoH5A7DghtGixxFUViRt6iDfXGGJCDpykQL++doDSvu3sjtYzs4ZlqKXsLaQotWQwknnOt7Km1q2HyeIx6EW7w2dn09NjFXnxxn1gMG3P5YHBl9S5ShPmOsShgG8QmRVahDwpGHBx6AzGzKdXoH5A7DghtGixxpVUtluwjAQfPdXoH5A7DghtGixs4ZlqKXsLaQot0u4KqLQKRlUugzC4gP+AYQlHrPwqLImhgfj0cnKvMwUhnfprkj0hiwnSPAxn1gMG3P5YHBl9S5ShPmOsShOqLqJ7x73Gx2vVbgC0DwZoXklFCKXFpo0bcpu83qWht0u4KqLQKRlUugzC4gP+AYQlHrpfUGenfxtGEOl1jIRN0c3hECesjSRhmNC+62Nh7vy7otNVxQmtdkm3Ew/Jrv1Kp0X4elF8Pb6p/n2KH/k0skaqcyeVHfdaulqgoP20X4elF8Pb6p/n2KH/k0sv8\u003d",
        "specificationVersion": "1.0.2",
        "authRequired": true
    }

}

Below is the description of these variables:

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

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

requestSecureInit()

OPTIONAL. This method allows you to obtain the Json Web token (JWT) for 100% API integrations with 3DS.

Request

Required

PROPERTY	TYPE	DESCRIPTION	POSSIBLE VALUES
card	Object	Bin number (8 digits) collected in an object

Response

Successful response will be in the function (callback):

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTQ2NTY4ODYsImlhdCI6MTY1NDY0OTY4NiwiaXNzIjoiNWVhMzJmZDJmZjQ2NDU2OTY3YjUyNDliIiwianRpIjoiMDFhZTQyYWUtYzMyZS00YWRjLWFmOWQtZWVhMmFlNjRkMDkxIiwiT3JnVW5pdElkIjoiNWVhMzJmZDJhZDA3ZDIxYTM2OTc4OGFlIiwiUmVmZXJlbmNlSWQiOiI3ZjY1NzM5NS0yMDIwLTQ1ZjEtOTY4Mi05MzJiNTU5YWYzMWIifQ.JUkk70Kg4KlUYW7eIvsW8LoDhxJeG8P00VrJH9oQipc"
}

Error response will be in the function (callback):

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

requestValidate3DS()

OPTIONAL. This method allows to perform the 3DS authentication by the cardholder in case it is required.

Request

Use the following cards in test mode to make sure your integration is ready. 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

Parameters

PROPERTY	TYPE	DESCRIPTION
secureId	String	The secureId you get from the token or recurring charge token response
security	Object	The security object received from the token response
acsURL	String	URL of the challenge page of the issuer
authenticationTransactionId	String	ID of the transaction verified by the brands.
specificationVersion	String	3D Secure version
paReq	String	This parameter contains zipped Based64-encoded data on the transaction. This parameter is received from the brands.
authRequired	Boolean	Identifies whether the 3DS challenge is required or not.
callback	Function(response)	The created callback function()

Response

The following response will be in the function (callback):

{isValid:true}

Error response will be in the function (callback):

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

If the transaction is declined for the authentication, its result will be included as part of the response of the charge with 322 and any of the subcodes specified in the error code list.

If the value of the authRequired variable is equal to true the modal for OTP validation will be displayed and your client will then receive the value to enter by email or text message.

If the value of the authRequired variable is equal to false, the OTP validation modal will not be displayed.

The response to this call will be received in the callback function. If it is positive, it sends the token to the back-end to continue with the transaction.

requestDeviceToken()

This method is required for executing one-click payments. Find more information in our guide to generate One-Click payments.

Request

Required

Property	Type	Description	Possible Values
subscriptionId	String	SubscriptionId that was previously created
callback	Function(response)	The created `callback` function()	* Success : `{ token: "90a9f2d93ba508c38971890454897fd4"}` * Error: `{ message:"error-message", code:"error-code", error: "error-message"}`
amount (only required for 3DS authentication)	Object	The value of the purchase
currency (only required for 3DS authentication)	String	Code of currency used	`USD`, `PEN`

Response

Successful response will be in the function (callback):

{ 
  "token": "90a9f2d93ba508c38971890454897fd4"
}

Error response will be in the function (callback):

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

Payouts Examples

💸 Cash Out

requestPayoutsCashToken()

To create a Cash Out token.

Required

Property	Type	Description	Possible Values
name	String	Name of the client
lastName	String	Last name of the client
documentType	String	Type of document that the client is using to pay.	`CC`, `NIT`, `CE`, `TI`, `PP`
documentNumber	String	Document number that the client is using to pay
totalAmount	Number	The amount you are going to collect as a number
currency	String	Code of currency used	`COP`
callback	Function(response)	The created `callback` function()	* Success : `{ token: "90a9f2d93ba508c38971890454897fd4"}` * Error: `{ message:"error-message", code:"error-code", error: "error-message"}`

Optional

Property	Type	Description
email	String	Email address of the client
paymentDescription	String	A description of the payment

Response

Successful response will be in the function (callback):

{ 
    "token": "90a9f2d93ba508c38971890454897fd4"
}

Error response will be in the function (callback):

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

Other Examples

Gateway Status

Commissions

🎨 Card Branding Animation

getStatusGateway()

To get the status of all the payment methods configured for a specific merchant.

Request

Required

Property	Type	Description
callback	Function(response)	The created `callback` function()

Response

The response will be in the function (callback):

[
    {
      "card": true,
      "transfer": true,
      "cash": true
    }
]

📖 Reference Summary

One-Time Payment

Name	Description
`requestToken()`	Returns a card token (supports 3DS/OTP).
`requestSecureServiceValidation()`	Validates OTP.
`requestSecureInit()`	Gets JWT for 3DS API integration.
`requestValidate3DS()`	Performs 3DS authentication flow.
`requestDeferred()`	Gets deferred payment options.
`requestBinInfo()`	Gets BIN information.
`requestCardAsyncToken()`	Returns a card async token.
`requestBankList()`	Returns list of banks (Transfer In).
`requestTransferToken()`	Returns a transfer in token.
`requestCashToken()`	Returns a cash in token.

Recurring Charges

Name	Description
`requestSubscriptionToken()`	Returns a recurring charge token.
`requestDeviceToken()`	Returns token for one-click payments.
`requestSubscriptionCardAsyncToken()`	Returns async card recurring token.

Others

Name	Description
`requestPayoutsCashToken()`	Returns a cash out token.
`getStatusGateway()`	Returns payment methods status.
`getCommissionConfiguration()`	Returns commission configuration.
`initCardBrandingAnimation()`	Renders sensory branding.

One-Time Payment

Name	Parameters	Returns	Description
requestToken()	`card`, `amount`, `currency`, `months`, `callback`	Object	Returns a token of a credit card. Make sure they are outside of your main form (PCI COMPLIANCE). If the merchant has the OTP validation activated, this method will also return a `secureId` and a `secureService` that can later be used to validate the OTP.
requestSecureServiceValidation()	`secureServiceId`, `otpValue`, `callback`	Object	Returns whether the OTP is valid or not.
requestSecureInit()	`card`, `callback`	Object	This method allows you to obtain the Json Web token (JWT) for 100% API integrations with 3DS.
requestValidate3DS()	`secureId`, `security`, `acsURL`, `authenticationTransactionId`, `specificationVersion`, `paReq`, `authRequired`, `callback`	Object	This method allows to perform the 3DS authentication by the cardholder in case it is required.
requestDeferred()	`binBody`, `callback`	Object	Returns an object with deferred options that are allowed for Ecuadorian, Mexican, and Peruvian merchants.
requestBinInfo()	`binBody`, `callback`	Object	Returns an object with the information related to the credit card bin.
requestCardAsyncToken()	`totalAmount`, `currency`, `returnUrl`, `email`, `description`, `callback`	Object	Returns a card async token.
requestBankList()	`callback`	Object	Returns a list of banks available for Transfer In.
requestTransferToken()	`bankId`, `amount`, `email`, `callbackUrl`, `documentType`, `documentNumber`, `currency`, `paymentDesc`, `userType`, `callback`	Object	Returns a transfer in token.
requestTransferSubscriptionToken()	`email`, `callback`	Object	Returns a transfer in token (Mexico only).
requestCashToken()	`name`, `lastName`,`documentType`, `identification`, `email`, `totalAmount`, `currency`,`description`, `callback`	Object	Returns a cash in token.

Recurring Charges

Name	Parameters	Returns	Description
requestSubscriptionToken()	`card`, `currency`, `callback`	Object	Returns a token of a recurring charge. Make sure they are outside of your main form (PCI COMPLIANCE).
requestSecureInit()	`card`, `callback`	Object	This method allows you to obtain the Json Web token (JWT) for 100% API integrations with 3DS.
requestValidate3DS()	`secureId`, `security`, `acsURL`, `authenticationTransactionId`, `specificationVersion`, `paReq`, `authRequired`, `callback`	Object	This method allows to perform the 3DS authentication by the cardholder in case it is required.
requestDeviceToken()	`subscriptionId`, `callback`	Object	Returns the token of a specific recurring charge.
requestSubscriptionCardAsyncToken()	`currency`, `email`, `cardNumber`, `callbackUrl`, `callback`	Object	Returns an async card recurring charge token.

Payouts

Name	Parameters	Returns	Description
requestPayoutsCashToken()	`name`, `lastName`,`documentType`, `identification`, `email`, `totalAmount`, `currency`,`paymentDescription`, `callback`	Object	Returns a cash out token.

Others

Name	Parameters	Returns	Description
getStatusGateway()	`callback`	Object	Returns the status of all the payment methods configured for a specific merchant.
getCommissionConfiguration()	`totalAmount`, `currency`, `callback`	Object	Returns the information related to the commission charge configured for a specific merchant.
initCardBrandingAnimation()	`callback`, `constrained`, `color`, `sound`, `checkmark`	Object	The Card Branding Animation gives users meaningful confirmation of their payment.

Got a suggestion on this documentation? Contact Us.

📦 Import Kushki.js#

🛠️ Usage#

Configuration Parameters#

One-Time Payment Examples#

requestToken()#

requestDeferred()#

Ecuador#

Chile: Issuer & Merchant Installments available#

Error response will be in the function (callback):#

requestBinInfo()#

Response#

Recurring Charges Examples#

requestSubscriptionToken()#

requestSecureInit()#

requestValidate3DS()#

requestDeviceToken()#

Payouts Examples#

requestPayoutsCashToken()#

Other Examples#

getStatusGateway()#

📖 Reference Summary#

One-Time Payment#

Recurring Charges#

Others#

One-Time Payment#

Recurring Charges#

Payouts#

Others#

📦 Import Kushki.js

🛠️ Usage

Configuration Parameters

One-Time Payment Examples

requestToken()

requestDeferred()

Ecuador

Chile: Issuer & Merchant Installments available

Error response will be in the function (`callback`):

requestBinInfo()

Response

Recurring Charges Examples

requestSubscriptionToken()

requestSecureInit()

requestValidate3DS()

requestDeviceToken()

Payouts Examples

requestPayoutsCashToken()

Other Examples

getStatusGateway()

📖 Reference Summary

One-Time Payment

Recurring Charges

Others

One-Time Payment

Recurring Charges

Payouts

Others