Embedded Checkouts

Recurrente Checkout es una librería JavaScript que te permite insertar un checkout responsivo y seguro en tu propia página web. Funciona mostrando un iframe con tu sesión de pago y maneja callbacks para eventos clave como éxito, fallo o pagos en proceso.

Video tutorial

Para ver un video de cómo funciona: https://youtu.be/OUIYVcrnPr0

Requisitos previos

Para usar esta biblioteca, necesitas crear un checkout en Recurrente. Consulta la documentación de creación de checkouts para obtener tu URL de checkout.

Clave en checkouts embebidos

Dentro de un iframe, el navegador trata nuestras cookies como de terceros, así que Clave no siempre reconoce al cliente por su navegador. Por eso el checkout embebido abre con el botón Pagar con Clave, como el botón de Link junto a Apple Pay: al tocarlo se abre la ventana de Clave, una ventana en nuestro propio origen donde el navegador sí entrega la cookie; el cliente escoge su tarjeta y paga, la ventana se cierra sola y tu página recibe onSuccess igual que con un pago dentro del iframe. Quien prefiera seguir en el formulario tiene el camino de siempre: Clave lo reconoce por el correo o el teléfono que ya está escribiendo, le envía un código de un solo uso y, al confirmarlo, sus métodos guardados aparecen en el checkout.

No necesitas configurar nada para que esto funcione, y tu cliente nunca tiene que ajustar permisos del navegador. En los navegadores dentro de apps (Instagram, Facebook, WhatsApp), que no pueden sostener una ventana emergente, el botón no se muestra y queda el código. Consulta Acepta Clave.

Desarrollo local

Los campos de tarjeta del checkout los sirve nuestro procesador, que solo acepta que la página que contiene el iframe esté en un origen https:// o en http://localhost (con cualquier puerto). Si abres tu sitio desde http://127.0.0.1, una IP de tu red o un dominio como miapp.local, el checkout carga pero el formulario de tarjeta falla con un 422 en capture_context cuyo cuerpo indica el origen rechazado.

Para probar en local, abre tu sitio en http://localhost:PUERTO o expónlo por HTTPS con un túnel como ngrok.

Instalación

NPM (Recomendado)

npm install recurrente-checkout

CDN

<script src="https://cdn.jsdelivr.net/npm/recurrente-checkout@0.0.5/recurrente-checkout.js"></script>

Fija la versión en la URL del CDN, para que una versión nueva no cambie tu checkout sin que lo sepas.

Uso

<div id="recurrente-checkout-container"></div>

import RecurrenteCheckout from "recurrente-checkout";
RecurrenteCheckout.load({
  url: "https://app.recurrente.com/checkout-session/ch_abc123",
  onSuccess: (data) => {
    console.log("Pago exitoso", data.checkoutId);
  },
  onFailure: (data) => {
    console.log("Pago fallido", data.error);
  },
  onPaymentInProgress: (data) => {
    console.log("Pago en proceso", data.checkoutId);
  },
});

El checkout se monta en el elemento con id recurrente-checkout-container. Si no existe, la librería lo crea al final de la página.

Parámetros

Flujo completo

1. Crea un checkout vía la API de Recurrente (POST /api/checkouts)
2. Pasa su checkout_url a RecurrenteCheckout.load
3. Maneja los callbacks de éxito, fallo o pago pendiente
4. Confirma el pago en tu servidor con el webhook o GET /api/checkouts/{id} antes de entregar

// 1. Crea el checkout desde tu backend
const response = await fetch("/api/create-checkout", { method: "POST" });
const { checkout_url } = await response.json();
// 2-3. Monta e inicializa
RecurrenteCheckout.load({
  url: checkout_url,
  onSuccess: () => window.location.href = "/gracias",
  onFailure: () => alert("El pago falló. Intenta de nuevo."),
});

¿Ya tienes tu propio formulario de pago y solo quieres sumar Clave? Usa el botón de Clave.