Checkout.js · @cauril/checkout-js

El drop-in del browser. Toma un client_secret, monta el campo de pago seguro del PSP, tokeniza del lado del cliente, maneja 3DS/vouchers y reroutea si un PSP no inicializa. Framework-agnóstico y sin dependencias.

Esta página es la referencia del paquete. Para el flujo completo de extremo a extremo (crear la sesión en tu server, confirmar por webhook) leé Checkout embebido.

Los datos de tarjeta van directo al PSP, nunca pasan por tu server ni por Cauril (PCI SAQ-A). Y el resultado del browser es para la UX: confirmá siempre el cobro en tu backend vía el webhook payment.succeeded antes de entregar.

Instalación

Con un bundler, instalá el paquete:

BASH

npm install @cauril/checkout-js

O cargá el drop-in con un <script> desde el CDN; expone un global window.Cauril:

HTML

<script src="https://js.cauril.com/v1/checkout.js"></script>

La API es idéntica por las dos vías: import { Cauril } from "@cauril/checkout-js" o el global Cauril del <script>.

Uso

Pasá al browser el client_secret que devolvió POST /v1/checkout/sessions (nunca tu sk_), creá el checkout y montalo en un contenedor:

import { Cauril } from "@cauril/checkout-js";

const checkout = Cauril.checkout({
  clientSecret: "cs_01J..._secret_aGVsbG8", // del POST /v1/checkout/sessions
});

checkout.on("completed", ({ payment_status }) => {
  // UX: mandá al comprador a la página de éxito.
  // El cobro REAL se confirma por webhook.
  window.location.assign("/gracias");
});
checkout.on("failed", ({ code, message }) => console.error(code, message));

await checkout.mount("#cauril-checkout");

Opciones de `Cauril.checkout(options)`

Campo	Default	Qué hace
`clientSecret`	—	Requerido. El `client_secret` de la sesión (lleva el id adentro).
`baseUrl`	`https://api.cauril.com`	Origen de la API.
`locale`	de la sesión / browser	Fuerza el idioma: `"es"`, `"pt"` o `"en"`.
`appearance`	—	Tema y estilo controlado (ver abajo).
`onComplete`	`"manual"`	`"redirect"` navega a `success_url` al completar; `"manual"` solo emite `completed`.

Métodos del controlador

Método	Qué hace
`mount(target)`	Monta el drop-in en un selector o `HTMLElement`. Devuelve una `Promise`. Idempotente.
`on(event, handler)`	Se suscribe a un evento. Devuelve una función para desuscribirse.

Eventos

Los códigos vienen siempre normalizados, nunca strings crudos del PSP.

Evento	Cuándo	Payload
`ready`	El drop-in cargó y mostró el campo de pago.	`{ session }`
`method_selected`	El comprador eligió un método.	`{ method }`
`processing`	El cobro está en curso.	—
`requires_action`	Hace falta una acción (ej. 3DS, voucher).	`{ next_action }`
`completed`	La sesión se completó (confirmada por webhook).	`{ payment_status }`
`failed`	El pago fue rechazado.	`{ code, message }`
`expired`	La sesión expiró sin pagar.	—
`error`	Error al montar o de red.	`{ code, message }`

Apariencia

Subconjunto controlado (sin CSS arbitrario, por seguridad): theme (light/dark), accent (color del botón, sanitizado), radius (0–24 px) y font (system/serif/mono).

Cauril.checkout({
  clientSecret,
  appearance: { theme: "light", accent: "#0a7cff", radius: 8, font: "system" },
}).mount("#cauril-checkout");

Errores

El paquete exporta CheckoutError (con code y, cuando aplica, status). Los fallos de pago llegan además por el evento failed con su código normalizado, así que normalmente alcanza con escuchar los eventos.

Reintento entre PSPs

Si el PSP ruteado no inicializa (SDK caído, conexión mal configurada), el drop-in le pide a la API rerutear a otro PSP elegible y se vuelve a montar, antes de que el comprador escriba nada. Es automático; no tenés que manejarlo.