> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout embebido

> Cobra con Cobrix dentro de tu propia web, sin enviar al cliente a otra página

Con el checkout embebido tu cliente paga **dentro de tu web**. Ve el mismo checkout de Cobrix (pago móvil, transferencia, Zelle y débito inmediato si tu empresa lo tiene activo), con el color y la letra de tu tienda.

> [!NOTE]
>
> **Disponible en sandbox.** Puedes integrarlo y probarlo completo hoy en sandbox. En producción todavía no está activo: te avisaremos cuando puedas cambiar las URLs.

Si prefieres que el pago sea un campo más de tu propio formulario, usa el [componente de débito inmediato](https://docs.cobrix.co/api-guides/embedded-direct-debit.md).

## Cómo funciona

Son tres pasos:

**1. Tu servidor crea el cobro**

Cuando el cliente va a pagar, tu servidor llama a `POST /checkouts` con el monto y tu referencia del pedido. Cobrix responde con un `embedToken`, que tu servidor le entrega a tu página. Hazlo siempre desde el servidor: la llave de API nunca va en el navegador. El detalle está en [1. Crea el cobro](#1-crea-el-cobro).

**2. Registras tu web en el panel**

Por seguridad, el checkout solo se muestra en las webs que tu empresa registra.

**3. Tu web muestra el checkout**

Con `checkout.js` y el `embedToken`, dentro de la página o en una ventana.

> [!WARNING]
>
> **Confirma el pago con el webhook, no con el evento del navegador.** Tu servidor da el pago por bueno solo cuando recibe el webhook firmado `payment.succeeded`. Los eventos de `checkout.on(...)` sirven para mostrarle el resultado al cliente, nada más.

## URLs por ambiente

| Qué | Sandbox | Producción |
| - | - | - |
| API | `https://sandbox-api.cobrix.co/api` | `https://api.cobrix.co/api` |
| `checkout.js` | `https://sandbox.cobrix.co/checkout.js` | `https://app.cobrix.co/checkout.js` |
| Panel | `https://sandbox.cobrix.co` | `https://app.cobrix.co` |

Carga siempre `checkout.js` del mismo ambiente donde creaste el cobro. Un `embedToken` de sandbox no funciona con el script de producción.

## 1. Crea el cobro

```http theme={null}
POST /integrations/v1/{companyId}/checkouts
```

* **Permiso de la llave:** `checkouts:write`.
* **Autenticación:** Bearer y firma, como en toda la API de integraciones. Consulta [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md).
* **`Idempotency-Key`:** obligatorio. La misma clave devuelve el mismo cobro. Consulta [Idempotencia](https://docs.cobrix.co/api-guides/idempotency.md).

Crea un cobro por cada pedido, justo antes de mostrar el pago. Este ejemplo lo crea y devuelve el `embedToken`:

```javascript Node.js (tu servidor) theme={null}
import crypto from 'node:crypto'

const baseUrl = 'https://sandbox-api.cobrix.co/api'
const companyId = process.env.COBRIX_COMPANY_ID
const secret = process.env.COBRIX_API_KEY

export async function crearCobro(pedido) {
  const url = new URL(`${baseUrl}/integrations/v1/${companyId}/checkouts`)
  const body = JSON.stringify({
    externalDocumentId: pedido.id, // tu referencia, por ejemplo 'PED-1001'
    customerExternalId: pedido.clienteId,
    customer: { type: 'individual', name: pedido.nombre, email: pedido.email },
    currency: 'USD',
    totalMinor: pedido.totalEnCentavos, // 2500 es USD 25,00
    description: pedido.descripcion
  })
  const timestamp = Math.floor(Date.now() / 1000).toString()
  // Se firma la ruta completa, con /api: /api/integrations/v1/.../checkouts
  const signed = `${timestamp}.POST.${url.pathname}.${body}`
  const signature = crypto.createHmac('sha256', secret).update(signed).digest('hex')

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${secret}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
      'Cobrix-Timestamp': timestamp,
      'Cobrix-Signature': `v1=${signature}`
    },
    body
  })
  if (!response.ok) throw new Error(`Cobrix respondió ${response.status}`)

  const cobro = await response.json()
  return cobro.embedToken // entrégaselo a tu página
}
```

Tu página recibe ese `embedToken` de tu servidor (por ejemplo, al cargar la página de pago) y se lo pasa a `checkout.js` en el [paso 4](#4-muestra-el-checkout).

El cuerpo de la solicitud:

```json Solicitud theme={null}
{
  "externalDocumentId": "PED-1001",
  "customerExternalId": "CLI-77",
  "customer": {
    "type": "individual",
    "name": "Ana Pérez",
    "email": "ana@correo.com"
  },
  "currency": "USD",
  "totalMinor": 2500,
  "description": "Plan mensual noviembre",
  "expiresInHours": 72
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `externalDocumentId` | Sí | Tu referencia del cobro, de 1 a 200 caracteres. Con ella lo consultas después. |
| `customerExternalId` | Sí | El identificador del cliente en tu sistema. |
| `customer` | Sí | Los datos del cliente, igual que en la creación de documentos de cobro. |
| `currency` | Sí | `USD`, `VES` o `EUR`. |
| `totalMinor` | Sí | Entero en unidades menores, mínimo 1. `2500` es USD 25,00. |
| `description` | No | Texto de la línea del cobro cuando no envías `lines`. |
| `lines` | No | Las líneas del documento. |
| `dueDate` | No | Por defecto, hoy. |
| `expiresInHours` | No | Máximo 720. Por defecto, 72. |
| `returnUrl` | No | Solo para el link (`checkoutUrl`): a dónde vuelve tu cliente al terminar. Consulta [Vuelve a tu web desde el link](#vuelve-a-tu-web-desde-el-link). |

```json Respuesta 201 theme={null}
{
  "externalDocumentId": "PED-1001",
  "status": "open",
  "totalMinor": 2500,
  "currency": "USD",
  "checkoutUrl": "https://sandbox.cobrix.co/checkout/collection-documents/cdoc_…",
  "embedToken": "cdoc_…",
  "expiresAt": "2026-11-11T14:00:00.000Z",
  "paymentMethods": ["pago_movil", "bank_transfer", "zelle", "debito_inmediato"]
}
```

* `embedToken` es lo que le pasas a `checkout.js`.
* `paymentMethods` trae los métodos que tu empresa tiene activos.
* Si enviaste `returnUrl`, la respuesta la trae.
* Si la referencia ya existe y sigue abierta, Cobrix actualiza el cobro y devuelve el checkout vigente.
* Si ya está pagada o anulada, responde `409 checkout_document_closed`.
* Si `returnUrl` no cumple las reglas, responde `422 invalid_return_url` y no crea nada.
* Todos los errores de `POST /checkouts` y `GET /checkouts/{externalDocumentId}` traen `{ "error": { "code", "message" } }`. Un cuerpo que no cumple el formato responde `400 invalid_request`, con el primer campo con problema en `field` y cada problema en `details`. Un fallo de Cobrix responde `500 internal_error`, con un mensaje genérico.

## 2. Consulta el cobro

```http theme={null}
GET /integrations/v1/{companyId}/checkouts/{externalDocumentId}
```

Requiere el permiso `checkouts:read`.

| Campo | Qué significa |
| - | - |
| `status` | `open`, `paid`, `expired` o `cancelled`. |
| `totalMinor`, `paidMinor`, `currency` | Los montos del cobro. |
| `expiresAt` | Cuándo vence el checkout. |
| `returnUrl` | La del último checkout, si la tiene. |
| `payments[]` | `method`, `status`, `amountMinor` y `paidAt` de cada pago. |

Una referencia que no existe responde `404`.

## 3. Registra tu web

En el panel, entra a **Integraciones › Checkout embebido** con un usuario owner o admin.

1. Escribe la dirección de tu web como se ve en el navegador, por ejemplo `mitienda.com`. El panel te muestra cómo se guardará: `https://mitienda.com`.
2. Copia el código que te da el panel y pásalo a quien maneja tu web.

Reglas de la dirección:

* Solo `https`. No se aceptan rutas, comodines (`*`) ni direcciones IP.
* Cada subdominio se registra aparte: `tienda.mitienda.com` no queda cubierto por `mitienda.com`.
* Máximo 10 webs por empresa.

En una web que no esté registrada, el navegador bloquea el checkout.

## 4. Muestra el checkout

```html theme={null}
<div id="pago"></div>
<script src="https://sandbox.cobrix.co/checkout.js"></script>
<script>
  const checkout = Cobrix.checkout({
    token: 'TOKEN_DEL_COBRO', // embedToken de POST /checkouts
    appearance: { primaryColor: '#7a4a1f', fontFamily: 'Lora' }, // opcional
  })

  checkout.mount('#pago') // dentro de la página
  // checkout.open()      // o en una ventana encima de la página

  checkout.on('payment.succeeded', (event) => {
    // Muestra «gracias». El pedido se entrega con el webhook.
  })
</script>
```

| Método | Qué hace |
| - | - |
| `Cobrix.checkout({ token, appearance? })` | Crea el checkout. |
| `mount(selector, { height? })` | Lo pone dentro de la página. Sin `height` crece con su contenido. |
| `open()` | Lo abre en una ventana. En teléfonos ocupa la pantalla completa. |
| `on(evento, fn)` | Escucha un evento. `'*'` escucha todos. |
| `close()` | Cierra la ventana o quita el checkout de la página. |
| `destroy()` | Cierra y deja de escuchar eventos. |

Mientras carga, `checkout.js` muestra una silueta gris. Si no carga en 20 segundos, muestra «No pudimos cargar el pago» con un botón para reintentar.

### Apariencia

| Opción | Valor | Regla |
| - | - | - |
| `primaryColor` | Color en hex | Se usa solo si el texto blanco encima se lee bien. Si no, queda el color de Cobrix. |
| `fontFamily` | Nombre de una fuente de Google Fonts | Por ejemplo `Lora`. |

Cualquier otro valor se ignora.

## 5. Eventos en el navegador

| Evento | Cuándo ocurre |
| - | - |
| `payment.reported` | El cliente envió un pago que queda en revisión. |
| `payment.succeeded` | El pago quedó confirmado. |
| `payment.failed` | El pago fue rechazado. |
| `checkout.collection_document_session.completed` | No queda saldo por pagar. |

Cada evento trae:

```json theme={null}
{
  "type": "payment.succeeded",
  "data": {
    "paymentId": "…",
    "sessionId": "…",
    "status": "succeeded",
    "amountMinor": 2500,
    "currency": "USD"
  }
}
```

> [!WARNING]
>
> No marques el pedido como pagado con estos eventos. Ocurren en el navegador del cliente: pueden no llegar si cierra la pestaña y cualquiera puede alterarlos desde su equipo. Úsalos solo para cambiar lo que ve el cliente.

### Confirma el pago con el webhook

Marca el pedido como pagado y entrégalo desde tu servidor, cuando llegue el webhook:

1. Configura tus webhooks en **Integraciones › Webhooks**.
2. Verifica la firma de cada webhook. Consulta [Firma de webhooks](https://docs.cobrix.co/guides/webhooks/signature).
3. Busca el pedido con el `externalDocumentId` que trae el webhook y márcalo como pagado.

El detalle de cada webhook está en [`payment.succeeded`](https://docs.cobrix.co/guides/webhooks/events/payment-succeeded) y [`checkout.collection_document_session.completed`](https://docs.cobrix.co/guides/webhooks/events/checkout-collection-document-session-completed).

## Qué ve tu cliente después de pagar

| Momento | Pantalla |
| - | - |
| Envía el pago y queda en revisión | «Tu pago está en revisión». |
| El pago se confirma | Cambia sola a «¡Gracias por tu pago!», sin recargar. |
| El pago se rechaza | «No pudimos confirmar tu pago». |
| Reabre el link con un pago en revisión o aprobado | Un recibo con monto, método y fecha. No ofrece pagar de nuevo. |

## Vuelve a tu web desde el link

Si en vez del checkout embebido mandas a tu cliente al link (`checkoutUrl`), envía `returnUrl` al crear el cobro. Así vuelve a tu web cuando termina.

```json Solicitud theme={null}
{
  "externalDocumentId": "PED-1001",
  "customerExternalId": "CLI-77",
  "customer": { "type": "individual", "name": "Ana Pérez" },
  "currency": "USD",
  "totalMinor": 2500,
  "returnUrl": "https://mitienda.com/pedido/listo"
}
```

Cuando el pago queda aprobado o en revisión, el checkout muestra «Volver a mitienda.com» y vuelve solo a los 5 segundos. Si el pago se rechaza, solo muestra el botón.

Cobrix agrega `checkout` con tu referencia y conserva la ruta, la query y el `#` de tu URL:

```text theme={null}
https://mitienda.com/pedido/listo?checkout=PED-1001
```

Reglas de `returnUrl`:

* Solo `https`, hasta 2048 caracteres, sin usuario ni contraseña.
* Va con el checkout que abre esa llamada. Si vuelves a crear el cobro sin `returnUrl`, el checkout nuevo no la tiene.

El checkout embebido no redirige. Tu página recibe el resultado con los [eventos del navegador](#5-eventos-en-el-navegador).

> [!WARNING]
>
> **La URL de regreso no confirma el pago.** Cualquiera puede escribirla a mano. Cuando tu cliente llegue, consulta el cobro con `GET /checkouts/{externalDocumentId}` desde tu servidor, o espera el webhook `payment.succeeded`. Nunca entregues el pedido por haber recibido la visita.

Este ejemplo atiende la vuelta y consulta el estado antes de decidir qué mostrar:

```javascript Node.js (tu servidor) theme={null}
import crypto from 'node:crypto'
import express from 'express'

const baseUrl = 'https://sandbox-api.cobrix.co/api'
const companyId = process.env.COBRIX_COMPANY_ID
const secret = process.env.COBRIX_API_KEY

async function consultarCobro(referencia) {
  const path = `/integrations/v1/${companyId}/checkouts/${encodeURIComponent(referencia)}`
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const signature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.GET.${path}.`) // en GET el cuerpo va vacío
    .digest('hex')

  const response = await fetch(`${baseUrl}${path}`, {
    headers: {
      Authorization: `Bearer ${secret}`,
      'Cobrix-Timestamp': timestamp,
      'Cobrix-Signature': `v1=${signature}`
    }
  })
  if (!response.ok) throw new Error(`Cobrix respondió ${response.status}`)
  return response.json()
}

const app = express()

app.get('/pedido/listo', async (req, res) => {
  const referencia = String(req.query.checkout ?? '')
  const cobro = await consultarCobro(referencia)

  if (cobro.status === 'paid') return res.send('¡Gracias! Tu pago está confirmado.')
  // En revisión u otro estado: el pedido se entrega cuando llegue el webhook.
  res.send('Recibimos tu pago. Te avisaremos cuando quede confirmado.')
})
```

## Seguridad

* **Solo en tus webs:** el checkout se muestra únicamente en las direcciones que registraste.
* **Sin datos de pago en tu página:** tu web nunca ve los datos bancarios del cliente, solo el resultado.
* **El webhook manda:** un evento del navegador puede no llegar si el cliente cierra la pestaña. El webhook firmado llega igual.
* **La URL de regreso tampoco confirma:** solo dice qué cobro consultar.

## Lista para probar en sandbox

1. Crea una llave en sandbox con `checkouts:write` y `checkouts:read`.
2. Registra la dirección de tu web de pruebas en **Integraciones › Checkout embebido**.
3. Crea un cobro con `POST /checkouts` y guarda el `embedToken`.
4. Muestra el checkout con `checkout.js` de sandbox.
5. Configura un webhook y confirma que recibes `payment.succeeded`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.