kushki.js Hosted Fields

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

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 card 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 `cardNumber_id` and renders the card number field.
fields.cardholderName.selector	`string`	YES	Links with the container `cardholderName_id` and renders the cardholder name field.
fields.cvv.selector	`string`	YES	Links with the container `cvv_id` and renders the CVV field. You can skip CVV.
fields.cvv.isRequired	`boolean`	NO	Configures whether CVV entry is required or not. Applies only to subscriptions.
fields.deferred	`string`	NO	Links with the container `deferred_id` and renders the deferred payments field (if applicable).
fields.expirationDate	`string`	YES	Links with the container `expirationDate_id` and renders the expiration date field.
fields.otp.selector	`string`	NO	Links with the container `otp_id` and renders the OTP field (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 token.	`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	Styles for the card number field.
styles.cardholderName	CssProperties	NO	Styles for the cardholder name field.
styles.container	CssProperties	NO	Styles for the input container.
styles.cvv	CssProperties	NO	Styles for the CVV field.
styles.deferred	CssProperties	NO	Styles for the deferred payments field.
styles.expirationDate	CssProperties	NO	Styles for the expiration date field.
styles.focus	CssProperties	NO	Styles applied when the field has focus.
styles.input	CssProperties	NO	Styles for the input element.
styles.invalid	CssProperties	NO	Styles applied when a field is invalid.
styles.label	CssProperties	NO	Styles for the input label.
styles.otp	CssProperties	NO	Styles for the OTP field.
styles.valid	CssProperties	NO	Styles applied when a field is valid.
fullResponse	`boolean`	NO	Returns additional card information when generating a subscription token.

Step 3. Render hosted fields with the initCardToken() method

After creating a CardOptions instance, call the initCardToken() function to initialize an ICard instance. This function takes the Kushki instance from the Initializing Kushki.js Hosted Fields section and the CardOptions instance from Step 2 as parameters. It returns a promise of 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 (amount, currency, subscription status, autofill prevention, custom CSS styles, 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" }`	Returned if `options` or `kushkiInstance` are null or undefined.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	Returned if any field references a selector that does not exist in the DOM.

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 a One-click payment.

requestToken()

To obtain a payment token with a card, call the requestToken() method on the previously initialized card instance. This method also validates all fields; otherwise, it throws an exception.

This method returns a TokenResponse object that you should send to your backend to continue with the payment flow.

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.

Example token response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Deferred Payments

If your merchant has enabled the deferred payments option, the requestToken() method returns additional data based on your merchant's country:

México and Ecuador

In addition to the token, the method returns 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 non-interest-bearing months in Mexico, a minimum amount applies depending on the installment plan:

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 Mexico and Ecuador:

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

Chile, Colombia, and Peru

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

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

Chile: Merchant Installments (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:

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

Property	Type	Description
`token`	`String`	Token to make a charge.
`deferred`	`Object`	Optional. 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" }`	Error when requesting a token. Validate that the required information has been sent correctly.
E003	Merchant data request error	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	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" }`	3D Secure JWT request error. Please try again; if the error persists, contact Kushki support.
E005	Invalid 3D Secure fields	`{ code: "E005", message: "Campos 3DS inválidos" }`	3D Secure authentication error. Verify the data entered for 3D Secure validation.
E006	Token validation request error	`{ code: "E006", message: "Error en solicitud de validación de token" }`	3D Secure validation session error. Please try again; if the error persists, contact Kushki support.
E007	Form validation error	`{ code: "E007", message: "Error en la validación del formulario" }`	One or more hosted fields are invalid. Verify the data entered.
E008	OTP validation error	`{ code: "E008", message: "Error en la validación de OTP" }`	OTP validation failed. Please try again with the correct OTP.

Examples

One-time charge or subscription without deferred payments

TypeScript

JavaScript

One-time charge with deferred payments

Subscription with fullResponse set as true

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. This is triggered when a value is entered into the OTP field. This method returns three callbacks (onSuccess, onError, and onRequired) that allow you to identify the status of OTP validation.

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): Executed when the created token requires OTP validation.

onError ((error) => void): Executed when OTP validation returns an error.

onSuccess (() => void): Executed when OTP validation is successful.

Errors

Code	Message	Example	Description
E008	Error en la validación de OTP	`{ code: "E008", message: "Error en la validación de OTP" }`	OTP validation failed. Please try again with the correct OTP.

Example

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 required challenges. Authentication will be carried out according to the security rules established in your merchant configuration.

Optional: Manual 3D Secure authentication

Note

The manual 3DS authentication flow is optional and applies only to the following two specific scenarios:

When obtaining the token from your backend using the Create a card token method.

To perform 3DS validation for subscriptions at the moment of tokenizing the card for future charges.

For these specific cases, you can perform manual 3D Secure authentication using the requestSecureInit() method. This method allows you to obtain a JSON Web Token (JWT) which is required to obtain a card token. Subsequently, call the requestValidate3DS() method, which will display a modal 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	Object 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" }`	Error requesting the 3D Secure JWT. Please try again; if the error persists, contact Kushki support.
E018	Longitud de tarjeta inválida	`{ code: "E018", message: "Longitud de tarjeta inválida" }`	Please verify that the card length is correct.
E019	Comercio no tiene activo 3DS	`{ code: "E019", message: "Comercio no tiene activo 3DS" }`	Merchant does not have 3D Secure authentication enabled.

If the request was successful, you will receive the JWT:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Once the JWT is obtained, consume the endpoint to request a card token by sending the JWT in the request body:

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

Note

If the authRequired property within the security object (security.authRequired) returns true, you must consume the requestValidate3DS() method to display the authentication modal.

If the request was correct, you will receive the token along with 3D Secure validation properties:

{
  "token": "g9m2XG100000uut73n085881SMOP3bP1",
  "secureService": "3dsecure",
  "secureId": "61efd064-b9df-4c0c-81fb-5b39a5d0cf9f",
  "security": {
    "acsURL": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?...",
    "authenticationTransactionId": "uvvZn0ND0ukTOJIfhfi0",
    "authRequired": true,
    "paReq": "eNpVUstuwjAQ...",
    "specificationVersion": "2.2.0"
  }
}

More information in the requestSecureInit method definition.

requestValidate3DS()

Consume the requestValidate3DS() method when the transaction needs 3D Secure authentication. This method receives 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	`{ code: "E005", message: "Campos 3DS inválidos" }`	3D Secure authentication error. Verify the data entered.
E006	Error en solicitud de validación de token	`{ code: "E006", message: "Error en solicitud de validación de token" }`	3D Secure validation session error. Please try again; 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:

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

If authentication was successful, continue with the payment flow by consuming the endpoint to make a charge. Otherwise, restart the payment flow by calling requestSecureInit() again.

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 according to the security rules established in your merchant configuration.

You can also perform manual Sift authentication using the requestInitAntiFraud() method, which allows you to obtain a JSON Web Token (JWT) required to obtain a card token.

requestInitAntiFraud()

Call the requestInitAntiFraud() method by sending a Kushki instance with your merchant configuration and the 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	`{ code: "E003", message: "Error en solicitud de datos del comercio" }`	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 a one-click payment.

To generate a subscription token, 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 mark as optional the CVV field during the creation of a subscription token.

Important

Available only in Colombia for the aggregator model. Before skipping or making CVV entry optional, validate the functionality with your account manager.

To make CVV entry optional, send isRequired: false inside the CVV field configuration:

To skip the CVV field entirely, omit the cvv configuration from the fields object:

Then, follow the next steps to obtain a token.

Recurring charge

After requesting a subscription token, call the Create a recurring charge endpoint with 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, first create a subscription by submitting the periodicity property with the value of custom to get a subscriptionId.

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

requestDeviceToken()

A subscriptionId is required. It must have been previously created using the recurring charge API with a token obtained from requestToken where isSubscription was set to true.

Note

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

More information in the requestDeviceToken method definition.

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" }`	Error 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" }`	3D Secure JWT error. Please try again; if the error persists, contact Kushki support.
E005	Invalid 3DS fields	`{ code: "E005", message: "Campos 3DS inválidos" }`	3D Secure authentication error. Verify the data entered.
E006	Token validation request error	`{ code: "E006", message: "Error en solicitud de validación de token" }`	3D Secure validation session error. Please try again; 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" }`	Merchant has Sift Science configured and `subscriptionId` was not found or the request failed.
E020	Merchant data request error	`{ code: "E020", message: "Error, configuración de campos requeridos no encontrada" }`	`DeviceTokenRequest` body is not defined.

After obtaining the token, call the make a One-click payment endpoint from your backend.

Secure DeviceToken

If you need to validate the CVV when performing a One-click payment, use the Secure DeviceToken method. This method 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.

Step 1 — Define the CVV container:

Step 2 — Create a SecureDeviceTokenOptions instance:

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

Step 3 — Call initSecureDeviceToken():

Call the initSecureDeviceToken() method, which renders the CVV hosted field and initializes 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 for initSecureDeviceToken()

Code	Message	Example	Description
E012	Error en inicialización de campos	`{ code: "E012", message: "Error en inicialización de campos" }`	`options` or `kushkiInstance` are null or undefined.
E013	El Id del contenedor de un input no fue encontrado	`{ code: "E013", message: "El Id del contenedor de un input no fue encontrado" }`	A field references a non-existing selector.

Step 4 — Call requestDeviceToken():

Response

Property	Type	Description
token	`String`	Token to make a charge.
cardInfo	`Object`	Optional. Returned if `fullResponse` is `true` when instantiating CardOptions.
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's last four digits.

Example response:

{
  "token": "a2b74b7e3cf24e368a20380f16844d16"
}

Example response with cardInfo:

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

Define the containers 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. Note that the isSubscription field is a checkbox, so specific styles must be applied to this input type. For more details, see the Card Payouts Styles interface.

Events

Use the same methodology as in Events (optional). The difference is that these events apply specifically to the fields required for this tokenization method. For more details, see the initCardPayoutToken examples.

Get a Card Payout Token

Call the requestCardPayoutToken method on your previously initialized card payout instance. This method validates that all fields contain valid values; otherwise, it throws an exception.

This method returns a CardPayoutTokenResponse object:

If isSubscription is checked → returns a CardPayoutSubscriptionTokenResponse with a subscriptionId.

Otherwise → returns a CardPayoutUniqueTokenResponse with a one-time token.

Example

Apple Pay Integration

Watch Out!

The Apple Pay functionality is currently in a testing phase. It is only available for merchants in Chile 🇨🇱, Colombia 🇨🇴, Mexico 🇲🇽, 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 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 UAT or Production).

Host the File: Upload the file to your server at: 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: Add a container element 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 in their Apple Wallet.

One-time payment

First, add the HTML container where the Apple Pay button will appear:

This block initializes Kushki.js, configures the Apple Pay button, and defines the logic to request the Kushki card token upon click:

Subscription

The initialization flow is identical to a one-time payment. The only difference is the isSubscription: true flag passed to requestApplePayToken, which tells Kushki to generate a subscription token instead of a one-time payment token.

Note

The subscription token returned is used to create a recurring charge via Kushki's subscription API.

Important Notes

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

The token returned by requestApplePayToken is a Kushki card token, not an Apple token. It is pre-processed and ready to be used directly in Kushki's API.

When isSubscription: true, the resulting token must be used with Kushki's recurring charge API to create a subscription — it cannot be used for a one-time charge.

For a complete reference, see the initApplePayButton method definition.

Other methods

requestBankList()

Get the list of available banks and their IDs. 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	`{ code: "E014", message: "Error en solicitud de lista de bancos" }`	Error obtaining the bank list. Please try again; 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.

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 currency and amount to calculate 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	`{ code: "E015", message: "Error en solicitud de configuración de comisión" }`	Error getting commission settings. Please try again with the correct information.

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, and play it after a transaction is complete.

Define a container where the animation will appear:

Set one of the following valid IDs:

visa-sensory-branding — for Visa card transactions

mastercard-sensory-branding — for Mastercard card transactions

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

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.

Styles (optional)

If you wish to generate custom styles for hosted fields, the library offers two approaches through the Styles interface:

CSS Classes — The CssProperties interface allows you to provide a string to configure a CSS class from your site.

JSS Object — The CssProperties interface allows you to provide an object to configure custom CSS styles inline.

Note

You can combine both options; some style attributes can be CSS classes, and others can be objects.

CSS Classes

You can use the CSS class from:

Local CSS File

CSS Framework

The following example shows the declaration of CSS styles from a local file:

Style objects

Definition of scopes for attributes of Styles

Example: Custom styles from CSS class

Example: Custom styles with JSS

Example: Pseudo-elements with JSS

JSS Documentation

CSS Pseudo-elements

Events (optional)

Management of the focus event on the field

This event is triggered when the field gains focus. For more information, refer to the onFieldFocus method within the ICard interface.

Management of the blur event on the field

This event is executed when the field loses focus. For more information, refer to the onFieldBlur method within the ICard interface.

Management of the submit event on the field

This event is executed when the field has been submitted. For more information, refer to the onFieldSubmit method within the ICard interface.

Management of the validation in the field

This event is executed when the field validation changes. For more information, refer to the onFieldValidity method within the ICard interface.

Management of the form validation for all hosted fields

This event is executed when any field validation changes. For more information, refer to the getFormValidity method within the ICard interface.

Setting focus for a hosted field

This method asynchronously focuses on a form field of the specified type; otherwise, an exception will be generated. For more information, refer to the focus method within the ICard interface.

Resetting a hosted field

This method asynchronously resets a form field of the specified type to the default state; otherwise, an exception will be generated. For more information, refer to the reset method within the ICard interface.

Next steps

Once you have integrated the methods described above to obtain a token from the frontend, consume one of the following endpoints from your backend to continue with the payment flow:

Make a one-time charge if initCardToken() was not initialized as a subscription.

Make a subscription if initCardToken() was initialized as a subscription.

Make a One-click payment if initCardToken() was initialized as a subscription and a token was generated with the requestDeviceToken() method.

When you have completed the development process, perform a certification to obtain your credentials for the production environment. Refer to the certification section to review the requirements for your implementation of Kushki.js Hosted Fields.

Got a suggestion on this documentation? Contact us.

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 and Ecuador#

Chile, Colombia, and Peru#

Chile: Merchant Installments (Cuotas Comercio)#

Response#

Errors#

Examples#

Security#

OTP#

onOTPValidation()#

3D Secure#

Optional: Manual 3D Secure authentication#

requestSecureInit()#

requestValidate3DS()#

Sift#

requestInitAntiFraud()#

Subscriptions#

Skip CVV#

Recurring charge#

One-click payments#

requestDeviceToken()#

Secure DeviceToken#

Card Payouts#

Form initialization#

Styling#

Events#

Get a Card Payout Token#

Apple Pay Integration#

Get Card Token from Apple Pay#

Prerequisites#

One-time payment#

Subscription#

Important Notes#

Other methods#

requestBankList()#

requestBrandsByMerchant()#

requestCommissionConfiguration()#

requestInitCardBrandingAnimation()#

Styles (optional)#

CSS Classes#

Style objects#

Other related articles#

Events (optional)#

Management of the focus event on the field#

Management of the blur event on the field#

Management of the submit event on the field#

Management of the validation in the field#

Management of the form validation for all hosted fields#

Setting focus for a hosted field#

Resetting a hosted field#

Next steps#

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 and Ecuador

Chile, Colombia, and Peru

Chile: Merchant Installments (Cuotas Comercio)

Response

Errors

Examples

Security

OTP

onOTPValidation()

3D Secure

Optional: Manual 3D Secure authentication

requestSecureInit()

requestValidate3DS()

Sift

requestInitAntiFraud()

Subscriptions

Skip CVV

Recurring charge

One-click payments

requestDeviceToken()

Secure DeviceToken

Card Payouts

Form initialization

Styling

Events

Get a Card Payout Token

Apple Pay Integration

Get Card Token from Apple Pay

Prerequisites

One-time payment

Subscription

Important Notes

Other methods

requestBankList()

requestBrandsByMerchant()

requestCommissionConfiguration()

requestInitCardBrandingAnimation()

Styles (optional)

CSS Classes

Style objects

Other related articles

Events (optional)

Management of the focus event on the field

Management of the blur event on the field

Management of the submit event on the field

Management of the validation in the field

Management of the form validation for all hosted fields

Setting focus for a hosted field

Resetting a hosted field

Next steps