> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Embedded Checkouts

> Inserta un checkout de Recurrente directamente en tu sitio web

**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.

> **Note**
>
> Para ver la versión más actualizada de esta guía y código de ejemplo, visita el repo: [github.com/recurrente/recurrente-checkout](https://github.com/recurrente/recurrente-checkout)

## Video tutorial

Para ver un video de cómo funciona: [https://youtu.be/OUIYVcrnPr0](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](/referencia-api/api-reference/checkouts/create-checkout) 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](/guias-espanol/guias/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)

```bash
npm install recurrente-checkout
```

### CDN

```html
<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

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

```javascript
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

| Parámetro             | Tipo     | Descripción                                                              |
| --------------------- | -------- | ------------------------------------------------------------------------ |
| `url`                 | string   | El `checkout_url` que devuelve la API al crear un checkout               |
| `onSuccess`           | function | Cuando el pago se completa. Recibe `checkoutId`                          |
| `onFailure`           | function | Cuando un intento falla. Recibe `error` (y `notice`, con el mismo texto) |
| `onPaymentInProgress` | function | Cuando el pago queda en proceso, como una transferencia bancaria         |
| `development`         | boolean  | Acepta eventos de cualquier origen. Solo para pruebas locales            |

## 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

```javascript
// 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](/guias-espanol/guias/clave).