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
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_sandbox_MjFiENYD.U38HsIFTKLpdiCQwOZYitzBWXgyulH6u
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 Merchant 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:
<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:
<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
HolaCashCheckout.configure(
{
order_id: order_id,
language: 'es', // 'en'
// 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
);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
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:
- Espera a recibir onComplete o onError
- 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 Merchant portal.
9. Demo de Widget
En este repositorio podrás descargar un demo del Widget:
Demo de Widget
