Inicio rápido

Un simple fragmento de código que te ayudará a tener todo el potencial de Hola Cash en tu tienda en línea. Intégralo en unos minutos de forma fácil.

Demo de integración del Checkout Widget

Open window

No olvides que para poder usar el cash.portal, hacer transacciones y obtener las API Keys, debes crear una cuenta de desarrollador en Hola Cash.

1. Crea una cuenta y accede al Sandbox

Crea una cuenta en nuestro ambiente de pruebas, solo necesitas un email y contraseña la información que requerimos para crear tu cuenta. Si lo prefieres, usa nuestra API Key de prueba:

Copia el API key de pruebas y utilizalo directamente en la pagina de referencia del API

pub_play_lpHjv1RO.B3qZ8dfFTM2TwDCSLmTzo4qsK3jNFPH6

2. Personalización de Widget y métodos de pago

Deberás agregar el dominio de la página en la que se mostrará el Widget, además puedes elegir cuáles serán los métodos de pago que deseas incluir. Puedes configurarlos en el Cash Portal, entrando a la sección de Configuración > Personalización de Widget.

* Es importante que solo agregues el nombre del dominio, sin subdominios ni https www, por ejemplo, si tu Widget va a existir en https://holacash.mx/widget, deberás agregar solamente holacash.mx.

3. Incluye Connect.js

Incluye este fragmento de código en el <head/> de tu página, remplazando {PUBLIC_KEY} por tu llave pública del API.

El url de CDN_URL debe de ser remplazado según el ambiente en el que te encuentres:

Producción
https://widget.connect.holacash.mx
Sandbox
https://widget.connect.sandbox.holacash.mx
Copy
Copied
<script
  async
  id="holacash-connect"
  type="text/javascript"
  src="{CDN_URL}/connect.min.js"
  data-public-key="{PUBLIC_KEY}"
></script>

4. Incluye el botón "Pagar"

Deberás incluir un botón de pagar el cual mostrará el Checkout Widget. Incluye este fragmento de código en donde desees que se cargue el botón, remplazando {PUBLIC_KEY} por tu llave pública del API. y {ButtonUrlBase} por los siguientes URLs dependiendo el ambiente en que te encuentres:

Producción
https://live.api.holacash.mx/v2
Sandbox
https://sandbox.api.holacash.mx/v2
Copy
Copied
<div id="instant-holacash-checkout-button">
  <object id="checkout-button"
  data={`${ButtonUrlBase}/checkout/button?public_key=${PUBLIC_KEY}`}
  data-disabled={false} />
</div>

Asegúrate que el contenedor div tenga id instant-holacash-checkout-button y el tag de objeto tenga id checkout-button

El atributo data-disabled permite desactivar el botón mientras el id de la orden está siendo recuperado del order API

Te recomendamos utilizar el botón de pago proporcionado por el Widget de pago. Nos hemos ocupado de algunas funciones básicas, como deshabilitar el botón mientras genera un order_id.

Sin embargo, si deseas usar un botón personalizado o mostrar el modal/ventana después de un evento como completar una llamada a la API, puedes usar la función HolaCashCheckout.initiateCheckout(). Por favor asegúrate de llamar a la función después de pasar un order_id dentro del método de configuración (como se describe en el Paso 6).

5. Crea una orden

Para poder crear un pago e iniciar el Checkout Widget primero necesitas crear una orden con los detalles de los productos agregados a tu carrito. La orden debe estar creada antes de llamar HolaCashCheckout.configure.

💡 IMPORTANTE: Es necesario que incluyas la información de envío y facturación en tu orden para permitir que las transacciones puedan ser aprobadas por la validación 3DS 2.0. Revisa la Referencia del API para más detalles sobre cómo crear una orden.

Para más información sobre cómo mandar esta información, revisa el tutorial de 3DS en la sección de Cómo implementar 3DS 2.0.

6. Carga el Widget

Llama HolaCashCheckout.configure cuando el usuario haga clic en el botón Pagar, para lanzar / inicializar nuestro Checkout Widget pasando la orden como parámetro

Copy
Copied
HolaCashCheckout.configure(
   {
        order_id: order_id,
        // 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 Cash 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)
                },
            },
            bnpl: {
                hide: true, //optional: hides BNPL payment method if needed,
                providers: ['aplazo'] // optional: customizes displayed BNPL providers
            },
        },
    },
    callbacks
);

Lista de callbacks:

  • onComplete -- > Se llama este callback cuando el cargo ha sido exitoso, el Widget continúa abierto.Regresa los detalles del cargo

  • onSuccess -- > Se llama este callback cuando el cargo ha sido exitoso, los usuarios dieron click a "Finalizar" y cerraron el Widget. Regresa los detalles del cargo

  • onAbort -- > cuando el usuario cierra el Widget. (modal/popup)

  • onError -- > cuando el cargo ha sido fallido. El parametro es el objeto de error.

  • onEmailEntered -- > cuando el usuario completa el ingreso de su email

  • onCheckoutStart -- > cuando el checkout Widget es presentado

  • check -- > Usaremos la devolución de llamada de verificación para determinar si Cash Pay debe continuar cargando la página de pago. Esto debe devolver un booleano

Copy
Copied
const callbacks = {
  onSuccess: (res) => {
    setSuccessResponse(JSON.parse(res));
    setReceiptVisible(true);
    console.log("onSuccess", JSON.parse(res));
  },
  onComplete: (res) => {
    // cargo completado exitosamente, pero Widget se mantiene abierto
    // res -> contiene los detalles y respuesta del API de crear cargo
    setReceiptDetails(JSON.parse(res));
    console.log("onComplete", JSON.parse(res));
    // remover comentario para cerrar Widget automaticamente cuando hay un cargo exitoso
    // HolaCashCheckout.closeCheckout()
  },
  onAbort: () => console.log("onAbort callback"),
  onError: (err) => {
    console.log(JSON.stringify(err));
    // remover comentario para cerrar Widget automaticamente cuando hay un cargo fallido
    // HolaCashCheckout.closeCheckout()
  },
  onEmailEntered: (email) => console.log(email),
  onCheckoutStart: () => console.log("checkout started"),
  // esta función deberá retornar siempre un booleano
  check: () => {
    return true;
  },
};

Pasa el objeto callbacks como segundo parámetro en HolaCashCheckout.configure()


HolaCashCheckout.closeCheckout()

Si deseas cerrar el Widget automáticamente:

  1. Espera a recibir onComplete o onError
  2. Llama HolaCashCheckout.closeCheckout()

* Importante: para evitar cerrar el Widget a la mitad de una transacción, no se podrá llamar closeCheckout() hasta que se haya disparado uno de los eventos mencionados arriba

7. Aspecto del Widget

Así es como se verá el Widget listo para poder procesar tu Orden y su pago.

8. Webhook

Al terminar de procesar el pago, se mandará un webhook con información del evento. Para configurar la dirección del webhook entra al Cash Portal.

9. Demo de Widget

En este repositorio podrás descargar un demo del Widget:

Demo de Widget

Button icon