Javascript

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.

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.

Styles (optional)

If you wish to generate custom styles for hosted fields, the Kushki.js Hosted Fields library offers the following two ways through the Styles interface:

CSS Classes: The CssProperties interface allows you to provide a string so that you can configure a CSS class for your site.

JSS Object: The CssProperties interface allows you to provide an object; meaning, you can configure custom CSS styles.

Note: You can combine both options; some style attributes can be CSS classes, and others can be an object.

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

Kushki JS - Definition of scopes for attributes of Styles

Kushki JS - Example.- Custom styles from class css

Kushki JS - Example.- Custom styles with JSS

Kushki JS - 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 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 the field validation changes. For more information, refer to the getFormValidity form 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 the necessary methods described above are integrated to obtain a token from the frontend on your merchant site, it is necessary to consume one of the following endpoints from your backend to continue with the payment flow:

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

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

Make an 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, it is necessary to perform a certification to obtain your credentials from the production environment. Refer to the certification section to review the requirements for your implementation of Kushki.js Hosted Fields.

Prerequisites#

Quick Example#

Important Notes#

Other methods#

requestBankList#

Errors#

requestBrandsByMerchant#

Errors#

requestCommissionConfiguration#

Errors#

requestInitCardBrandingAnimation#

Errors#

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#

Prerequisites

Quick Example

Important Notes

Other methods

requestBankList

Errors

requestBrandsByMerchant

Errors

requestCommissionConfiguration

Errors

requestInitCardBrandingAnimation

Errors

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