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.

We make it easier!

Import Kushki.js

Usage

Import Kushki.js

Option 1 - CDN

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

Option 2 - NPM

Install the npm with the following code:

Then, import it to your development workspace with the following code:

Important to consider

Please add the following lines to your code only if you are using Angular 6 or a higher version along with Kushki's npm package. This will help with the issue when it is not possible to resolve 'net'/'global' or other node globals. Find more information in Angular GitHub repository.

Add the following code in your project:

Every time you run npm install, include the following code in your package.json as a part of the postinstall scripts:

Usage

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

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.

One-Time Payment Examples

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.

Card

Card Async

Apple Pay

Transfer In

Transfer In (Mexico)

Cash In

requestToken()

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

Request

Required

Property	Type	Description	Default	Possible Values
amount	String	The amount you are going to collect as a string
currency	String	Code of currency used	`USD`	`USD`, `COP`, `CLP`, `UF`, `PEN`, `MXN`
card	Object	The card data collected in an card object
callback	Function(response)	The created `callback` function()		* Success : `{ token: "90a9f2d93ba508c38971890454897fd4"}` * With OTP validation activated : `{ token: "90a9f2d93ba508c38971890454897fd4", secureId: "5e44449e-869b-4fed-bbca-e1bfa5af53c3", secureService: "KushkiOTP"}` * Error: `{ message:"error-message", code:"error-code", error: "error-message"}`

Optional

Property	Type	Description	Possible Values
months	Integer	Number of installments. Required only for deferred transactions in Chile	Minimum: 2, maximum: 48

Response

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

requestSecureServiceValidation() for OTP

To validate the OTP entered by the client:

Request

Required

Property	Type	Description	Possible Values
secureServiceId	String	The secureId you get from the token request
otpValue	String	Three-digit number that corresponds to the OTP	For the OTP sandbox, the value will change depending on the credit card currency: `155` for USD and PEN, `555` for COP and MXN, `150` for CLP
callback	Function(response)	The created `callback` function()	* Success : `{ isValid: true}` * Error: `{ message:"error-message", code:"error-code", error: "error-message"}`

Response

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

{
  "code": "OTP000", 
  "message": "ok"
}

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.

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.

To keep in mind

3DS authentication with kushki.js will only work in a web application. If the user attempts to pay from a mobile device, 3DS authentication will not be performed.

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.

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

Card Async

Apple Pay

requestSubscriptionToken()

To create a recurring charge token, you can use this function:

Request

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Òaa20412b0063aca652facd9g4transactionId=Qhcf3XOjdZmjve336Vee2gb5rof1",
        "authenticationTransactionId": "1d8cf7jg5Bfn8Nj73mn7",
        "paReq": "eNpVUtluwjAQfPdXoH5A7DghtGixxFUViRt6iDfXGGJCDpykQL++doDSvu3sjtYzs4ZlqKXsLaQotWQwknnOt7Km1q2HyeIx6EW7w2dn09NjFXnxxn1gMG3P5YHBl9S5ShPmOsShgG8QmRVahDwpGHBx6AzGzKdXoH5A7DghtGixxpVUtluwjAQfPdXoH5A7DghtGixs4ZlqKXsLaQot0u4KqLQKRlUugzC4gP+AYQlHrPwqLImhgfj0cnKvMwUhnfprkj0hiwnSPAxn1gMG3P5YHBl9S5ShPmOsShOqLqJ7x73Gx2vVbgC0DwZoXklFCKXFpo0bcpu83qWht0u4KqLQKRlUugzC4gP+AYQlHrpfUGenfxtGEOl1jIRN0c3hECesjSRhmNC+62Nh7vy7otNVxQmtdkm3Ew/Jrv1Kp0X4elF8Pb6p/n2KH/k0skaqcyeVHfdaulqgoP20X4elF8Pb6p/n2KH/k0sv8=",
        "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, you can use this function:

Request

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

Find the methods available in our Kushki.js library. You can perform the following operations:

One-Time Payment:

Create a card token

Request an OTP validation. If you want more information about this feature, please go to our One Time Password section

Get the JWT for 100% API integrations with 3DS

Validate 3DS challenge

Get deferred options by bin

Get Bin Info

Create a Card Async token

Get list of banks available for Transfer In

Create a Transfer In token

Create a Cash In token

Recurring Charges:

Create a Card recurring charge token

Get the JWT for 100% API integrations with 3DS

Get the token of a specific recurring charge

Get an Async Card recurring charge

Payouts:

Create a Cash Out token

Others:

Get the status of all the payment methods configured for a specific merchant

Get the information related to the commission charge configured for a specific merchant

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.

Kushki.js 🌐

Kushki.js#

Import Kushki.js#

Usage#

Examples#

One-Time Payment Examples#

requestToken()#

Request#

Response#

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

requestSecureServiceValidation() for OTP#

Request#

Response#

requestSecureInit()#

Request#

Response#

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

requestValidate3DS()#

Request#

Parameters#

Response#

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

requestDeferred()#

Request#

Response#

Ecuador#

Chile: Issuer & Merchant Installments available#

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

requestBinInfo()#

Request#

Response#

Recurring Charges Examples#

requestSubscriptionToken()#

Request#

Response#

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

requestSecureInit()#

Request#

Response#

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

requestValidate3DS()#

Request#

Response#

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

requestDeviceToken()#

Request#

Response#

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

Payouts Examples#

requestPayoutsCashToken()#

Request#

Response#

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

Other examples#

getStatusGateway()#

Request#

Response#

Reference#

One-Time Payment#

Recurring Charges#

Payouts#

Others#

Kushki.js

Import Kushki.js

Usage

Examples

One-Time Payment Examples

requestToken()

Request

Response

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

requestSecureServiceValidation() for OTP

Request

Response

requestSecureInit()

Request

Response

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

requestValidate3DS()

Request

Parameters

Response

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

requestDeferred()

Request

Response

Ecuador

Chile: Issuer & Merchant Installments available

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

requestBinInfo()

Request

Response

Recurring Charges Examples

requestSubscriptionToken()

Request

Response

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

requestSecureInit()

Request

Response

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

requestValidate3DS()

Request

Response

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

requestDeviceToken()

Request

Response

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

Payouts Examples

requestPayoutsCashToken()

Request

Response

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

Other examples

getStatusGateway()

Request

Response

Reference

One-Time Payment

Recurring Charges

Payouts

Others