A simple code fragment that will help you tu unleash all the potential of Hola Cash in your e-commerce. Integrate it in minutes in the easiest way.

Checkout Widget integration demo

Open window

Do not forget that to use the cash.portal, make transactions and obtain the API Keys, you must create a developers account in Hola Cash.

1. Create an account to access the Sandbox.

Create an account in our Sandbox environment, you just need an email and password to create your account. If you prefer you can use our test API Key:

Copy and paste the Test API Key and use it directly in the API Reference.


2. Widget customization and payment methods.

You must add the domain of the webpage in which the Widget will be displayed, you can also select the payment methods you want to include. Configure them in the Configuration > Widget customization. section.

* It's important that you only add the domain name, without the https protocol or www nor subdomains, for example, if your Widget wil be displayed inhttps://holacash.mx/widget , you just have to add holacash.mx.

3. Include Connect.js

Include this code snippet into the <head/> section of your website, replace the {PUBLIC_KEY} with your API Public Key.

The CDN_URL must be replaced depending on the environment you are using:

Production environment
Sandbox environment

4. Include the "PAY" button element

You must include the PAY button which will show the Checkout Widget. Include this snippet where you want the button to load, replacing {PUBLIC_KEY} with your Public API Key. and {ButtonUrlBase} with the following URLs depending on environment you are using:

Production environment
Sandbox environment
<div id="instant-holacash-checkout-button">
  <object id="checkout-button"
  data-disabled={false} />

Ensure that the container div has the id instant-holacash-checkout-button and the object tag has id checkout-button

The data-disabled the attribute allows you to disable the button while the order id is fetched from the order API

We strongly suggest using the checkout button provided by the Checkout Widget. We've taken care of some basic functionality like disabling the button while you generate an order_id.

However if you want to use a custom button or to show the modal/window after an event like completing an API call, you can use the HolaCashCheckout.initiateCheckout() function. Please make sure to call this after passing an order_id inside the configure method (as described in Step 6).

5. Create an order

To be able to create a payment and initialize the Checkout Widget, first you need to create an order containing all the details from the products added to your shopping cart. Remember that the Order must be created before calling HolaCashCheckout.configure.

💡 IMPORTANT: In order for your transactions to be approved when triggering 3DS 2.0, we strongly recommend you include the Billing and Shipping information when creating the order. Please look at the API Reference documentation to create an order

For more on how to send this information, see section How to implement 3DS 2.0. on our 3DS tutorial

6. Load the Widget

When the user clicks on the button, PAY, you must initialize the Checkout Widget,passing the Order as a parameter .

        order_id: order_id,
        language: 'en', // 'es'
        // hints are optional
        hints: {
            first_name: 'John',
            last_name: 'Doe',
            second_last_name: 'Doe',
            email: 'john.doe@gmail.com',
            phone: '13212312412'
        // payments config is completely optional, but it will override the config from your Merchant portal since this settings are preferred if added in code
        payments: {
            credit_debit_card: {
                months_without_interest: {
                    hide: true, // optional: hides msi installments if needed
                    allowed_installments: [3, 6, 9, 12, 24], // customizes displayed installments default options are (3,6,9,12)
                    pre_selected_installment_option: 9, // if available this option will be selected by default
            bnpl: {
                hide: true, //optional: hides BNPL payment method if needed,
                providers: ['aplazo'] // optional: customizes displayed BNPL providers

Callbacks list:

  1. onComplete -- > we call this callback when the charge is successfull. The Widget remains open for users. It returns the response of the charge API

  2. onSuccess -- > we call this callback when the charge is successfull and the users click on "Finalizar" to close the Widget. Returns the response of the charge API

  3. onAbort -- > when the user closes the Widget (modal/popup)

  4. onError -- > when the charge fails. The parameter is the error object

  5. onEmailEntered -- > when the user completes entering an email

  6. onCheckoutStart -- > when the checkout page is presented

  7. check -- > We will use the check callback to determine if Cash Pay should proceed loading the checkout page. This must return a boolean

const callbacks = {
  onSuccess: (res) => {
    console.log("onSuccess", JSON.parse(res));
  onComplete: (res) => {
    // charge was completed correctly, but Widget remains open
    // res -> contains the result from the charge API call
    console.log("onComplete", JSON.parse(res));
    // remove comment to close Widget automatically after a charge is completed correctly
    // HolaCashCheckout.closeCheckout()
  onAbort: () => console.log("onAbort callback"),
  onError: (err) => {
    // remove comment to close Widget automatically after a charge attempt fails
    // HolaCashCheckout.closeCheckout()
  onEmailEntered: (email) => console.log(email),
  onCheckoutStart: () => console.log("checkout started"),
  // this function should always return a boolean
  check: () => {
    return true;

Pass the object callbacks as second parameter in the HolaCashCheckout.configure()


In order to automatically close the Widget:

  1. Wait to receive an onComplete or onError event.
  2. Call HolaCashCheckout.closeCheckout()

* Important: to avoid closing the Widget in the middle of a transaction, closeCheckout() cannot be called until one of the above mentioned events is fired.

7. Widget look and feel

This is how the Checkout Widget will look ready to process your Order and its Payment.

8. Webhook

When the payment is processed, a webhook will be sent with the information about the event. To configure the Webhook address, go to the Hola Merchant portalin the Developers section.

9. Widget Demo

In this repo you will be able to download a demo for the Widget:

Widget demo

Button icon