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

# Componente de débito inmediato

> El débito inmediato como un campo más de tu formulario de compra

Con el componente, tu cliente paga con débito inmediato **dentro de tu propio formulario**. Escribe su banco, cédula y teléfono, recibe un código por SMS y lo confirma ahí mismo. El botón «Pagar» es el tuyo.

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

Usa el mismo cobro, las mismas webs registradas y el mismo `checkout.js` que el [checkout embebido](https://docs.cobrix.co/api-guides/embedded-checkout.md).

## Cómo funciona

**1. Tu servidor crea el cobro**

Llama a `POST /checkouts` y recibe un `embedToken`. Sin ese token el componente no se puede mostrar.

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

El componente solo se muestra en las webs que tu empresa registra.

**3. Tu formulario monta el componente**

Con `checkout.js` y el `embedToken`. Tu botón «Pagar» llama a `confirm()`.

## Antes de empezar

* Tu empresa necesita el **débito inmediato activo**. Si `paymentMethods` de `POST /checkouts` no trae `debito_inmediato`, el componente avisa que no está disponible.
* El débito inmediato cobra en bolívares. Cobrix calcula el monto en Bs a partir del cobro.
* Necesitas una llave de API con el permiso `checkouts:write`. Consulta [Autenticación](https://docs.cobrix.co/authentication.md).

## 1. Crea el cobro

Cuando el cliente va a pagar, tu servidor crea el cobro y obtiene el `embedToken`. Hazlo siempre desde el servidor: la llave de API nunca va en el navegador.

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

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

```json Respuesta 201 theme={null}
{
  "externalDocumentId": "PED-1001",
  "status": "open",
  "totalMinor": 2500,
  "currency": "USD",
  "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`. Tu página lo recibe de tu servidor.
* Confirma que `paymentMethods` trae `debito_inmediato`.
* Todos los campos, la firma y los errores están en [Checkout embebido › 1. Crea el cobro](https://docs.cobrix.co/api-guides/embedded-checkout.md#1-crea-el-cobro).

## 2. Registra tu web

En el panel, entra a **Integraciones › Checkout embebido** y agrega la dirección de tu web, por ejemplo `mitienda.com`. Solo `https`, y cada subdominio se registra aparte. En una web que no esté registrada, el navegador bloquea el componente.

## 3. Monta el componente

```html theme={null}
<form id="compra">
  <!-- los campos de tu tienda -->
  <div id="pago"></div>
  <button id="pagar" disabled>Pagar</button>
</form>

<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' }, // opcional
  })

  checkout.mountElement('#pago', { method: 'debito-inmediato' })

  // Activa tu botón cuando los datos estén completos.
  checkout.on('element.change', (event) => {
    pagar.disabled = !event.data.complete || event.data.step !== 'form'
  })

  // No se puede cobrar: ofrece otro método.
  checkout.on('element.unavailable', (event) => {
    console.log(event.data.reason, event.data.message)
  })

  compra.addEventListener('submit', async (event) => {
    event.preventDefault()
    const result = await checkout.confirm()
    if (result.status === 'succeeded') {
      // Muestra «gracias». El pedido se entrega con el webhook.
    } else {
      // result.error.code y result.error.message
    }
  })
</script>
```

> [!WARNING]
>
> **Confirma el pago con el webhook, no con `confirm()`.** El resultado de `confirm()` llega al navegador del cliente y sirve para mostrarle «gracias» o el error. Tu servidor marca el pedido como pagado solo cuando recibe el webhook firmado `payment.succeeded`. Consulta [Confirmar el pago en tu servidor](#confirmar-el-pago-en-tu-servidor).

## Qué pasa al pagar

**1. El cliente llena sus datos**

Banco, cédula y teléfono. Cuando están completos llega `element.change` con `complete: true`.

**2. Tu botón llama a confirm()**

Cobrix le pide al banco del cliente que envíe el código por SMS.

**3. El cliente escribe el código**

Lo escribe dentro del componente. Tu página nunca ve el código ni los datos bancarios.

**4. confirm() se resuelve**

Con `succeeded` o `failed`. En paralelo recibes el webhook `payment.succeeded`.

## Métodos y eventos

| Llamada o evento | Qué hace |
| - | - |
| `mountElement(selector, { method })` | Pone el componente. `method` es `'debito-inmediato'`. |
| `confirm()` | Inicia el cobro. Se resuelve cuando el pago termina. |
| `element.ready` | El componente cargó y ya se puede cobrar. |
| `element.change` | Trae `{ complete, step }`. |
| `element.unavailable` | No se puede cobrar. Trae `{ reason, message }`. |

Valores de `step` en `element.change`: `form`, `otp`, `processing`, `success` y `error`.

### Resultado de confirm()

```json Pago aprobado theme={null}
{ "status": "succeeded", "transactionId": "…" }
```

```json Pago no completado theme={null}
{ "status": "failed", "error": { "code": "AM04", "message": "Fondos insuficientes." } }
```

| `error.code` | Qué significa | Qué hacer |
| - | - | - |
| `incomplete` | Falta un dato del cliente. | Espera `element.change` con `complete: true`. |
| `not_ready` | Todavía no llegó `element.ready`. | Espera ese evento antes de cobrar. |
| `in_progress` | Ya hay un cobro en curso. | Espera a que termine. |
| `not_mounted`, `closed` | El componente no está en la página. | Vuelve a llamar a `mountElement`. |

Cuando el banco rechaza, `error.code` trae el código del banco (por ejemplo `AM04`, fondos insuficientes) y `error.message` un texto listo para mostrar. El componente ofrece «Intentar de nuevo» y tu página vuelve a llamar a `confirm()`.

### Motivos de element.unavailable

| `reason` | Qué significa |
| - | - |
| `expired` | El cobro venció. Crea uno nuevo. |
| `already_paid` | El cobro ya tiene un pago aprobado o en revisión. |
| `method_disabled` | Tu empresa no tiene el débito inmediato activo. |
| `rate_unavailable` | No hay tasa de cambio para calcular el monto en Bs. |

## Apariencia

El componente no tiene fondo ni margen propios: sus bordes coinciden con los de tus campos. Además de `primaryColor` y `fontFamily`, `appearance` acepta:

| Opción | Valores | Qué cambia |
| - | - | - |
| `borderRadius` | 0 a 24 (px) | Las esquinas de los campos. |
| `colorBorder` | Color en hex | El borde de los campos. |
| `colorText` | Color en hex | Títulos y texto. |
| `labelFontSize` | 12 a 20 (px) | El tamaño de los títulos. |
| `labelFontWeight` | 400 a 700 | El peso de los títulos. |
| `spacing` | 8 a 32 (px) | La separación entre campos. |
| `inputHeight` | 40 a 56 (px) | El alto de los campos. |

Un valor fuera de rango se ignora. El componente usa siempre el tema claro.

```javascript theme={null}
const checkout = Cobrix.checkout({
  token: 'TOKEN_DEL_COBRO',
  appearance: {
    primaryColor: '#7a4a1f',
    borderRadius: 8,
    colorBorder: '#d6d3d1',
    inputHeight: 48,
  },
})
```

## Confirmar el pago en tu servidor

> [!WARNING]
>
> No entregues el pedido con el resultado de `confirm()` ni con los eventos del componente. Ocurren en el navegador del cliente: pueden no llegar si cierra la pestaña y cualquiera puede alterarlos desde su equipo. Entrégalo cuando tu servidor reciba el webhook firmado.

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.

Al aprobarse el débito llegan los mismos webhooks que con el checkout completo: [`payment.succeeded`](https://docs.cobrix.co/guides/webhooks/events/payment-succeeded) y, si no queda saldo, [`checkout.collection_document_session.completed`](https://docs.cobrix.co/guides/webhooks/events/checkout-collection-document-session-completed). Los dos traen tu `externalDocumentId`.

También puedes consultar el cobro con `GET /integrations/v1/{companyId}/checkouts/{externalDocumentId}`.

## Lista para probar en sandbox

1. Pide a Cobrix que active el débito inmediato en tu empresa de sandbox.
2. Crea un cobro con `POST /checkouts` y confirma que `paymentMethods` trae `debito_inmediato`.
3. Registra tu web de pruebas en **Integraciones › Checkout embebido**.
4. Monta el componente y espera `element.ready`.
5. Llama a `confirm()` desde tu botón y maneja `succeeded` y `failed`.
6. Confirma que tu servidor recibe `payment.succeeded`.


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