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

# Débito inmediato

> Cobra con débito inmediato desde tu propio formulario, sin pantallas de Cobrix

**Tu formulario de pago, el débito de Cobrix.**
Tu servidor pide el código al banco del pagador, el pagador lo escribe en tu web y tu servidor lo envía. Cobrix calcula los bolívares, aplica el pago al documento de cobro y te avisa por webhook.

direct\_debits:read
direct\_debits:write

## Operaciones

Todas las rutas empiezan en `/api/integrations/v1/{companyId}/direct-debits`.

| Operación | Scope | Método y ruta |
| - | - | - |
| [Listar bancos](#listar-bancos) | `direct_debits:read` | `GET /banks` |
| [Pedir el código](#pedir-el-código) | `direct_debits:write` | `POST /` |
| [Ejecutar con el código](#ejecutar-con-el-código) | `direct_debits:write` | `POST /{id}/execute` |
| [Consultar un débito](#consultar-un-débito) | `direct_debits:read` | `GET /{id}` |
| [Listar para conciliar](#listar-para-conciliar) | `direct_debits:read` | `GET /` |
| [Pedir otro código](#pedir-otro-código) | `direct_debits:write` | `POST /{id}/otp` |
| [Cancelar](#cancelar) | `direct_debits:write` | `POST /{id}/cancel` |

¿Prefieres que Cobrix muestre los campos del pago? Usa el [componente de débito inmediato](https://docs.cobrix.co/api-guides/embedded-direct-debit.md). Con esta API, tu web pide los datos y el código.

## Antes de empezar

* La empresa necesita el **débito inmediato activo**. Si no lo tiene, `POST /` responde `422 direct_debit_unavailable`.
* Crea una llave con `direct_debits:write` y `direct_debits:read` en **Configuración → Integraciones → Llaves API**.
* Firma cada llamada como en toda la API de integraciones. La ruta que firmas empieza en `/api` e incluye el query string, tal como la envías (`url.pathname + url.search`). Consulta [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md).
* Todo `POST` lleva `Idempotency-Key`. Consulta [Idempotencia](https://docs.cobrix.co/api-guides/idempotency.md).
* Llama siempre desde tu servidor. La llave nunca va en el navegador.

## El flujo

```mermaid theme={null}
sequenceDiagram
    participant P as Pagador en tu web
    participant S as Tu servidor
    participant C as Cobrix
    participant B as Banco del pagador
    P->>S: Banco, cédula y teléfono
    S->>C: POST /direct-debits
    C->>B: Pide el código
    B-->>P: SMS con el código
    C-->>S: id y status otp_sent
    P->>S: El código que recibió
    S->>C: POST /direct-debits/{id}/execute
    C->>B: Ejecuta el débito
    C-->>S: succeeded, processing o failed
    C-->>S: Webhook payment.succeeded
    S-->>P: Pedido confirmado
```

**1. Muestra los bancos**

Llama a `GET /banks` y arma la lista de bancos de tu formulario.

**2. Pide el código**

Con el cobro y los datos del pagador, llama a `POST /`. El banco envía un SMS al pagador. Guarda el `id` que responde Cobrix.

**3. Ejecuta con el código**

El pagador escribe el código en tu web y tu servidor lo envía con `POST /{id}/execute`. Responde `succeeded`, `processing`, `failed` o `expired`.

**4. Espera el resultado**

Si queda `processing`, el banco todavía no confirma. Espera el webhook o consulta `GET /{id}`.

**5. Entrega el pedido**

Cuando tu servidor recibe el webhook `payment.succeeded`, el dinero está cobrado y el pago aplicado al documento.

**6. Concilia**

Lista tus débitos con `GET /` y compáralos con tus pedidos.

> [!WARNING]
>
> **Confirma el pago con el webhook, no con lo que reporta tu página.** Lo que pasa en el navegador del pagador sirve para mostrarle «gracias» o el error. Puede no llegar si cierra la pestaña, y cualquiera puede alterarlo desde su equipo. Marca el pedido como pagado cuando tu servidor reciba el webhook firmado `payment.succeeded`. Si un webhook se demora, consulta `GET /{id}` desde tu servidor.

## Ejemplos con curl

Los ejemplos usan esta función de shell. Firma cada llamada y la envía. Tus datos van en variables de entorno, nunca en el código.

```bash theme={null}
export COBRIX_API_URL="https://sandbox-api.cobrix.co"
export COBRIX_COMPANY_ID="ID_DE_TU_EMPRESA"
export COBRIX_API_KEY="cbx_live_REEMPLAZAR"

# cobrix MÉTODO RUTA [CUERPO] [IDEMPOTENCY_KEY]
cobrix() {
  local method="$1" route="/api/integrations/v1/$COBRIX_COMPANY_ID/direct-debits$2"
  local body="$3" key="$4" ts sig
  ts=$(date +%s)
  sig=$(printf '%s' "$ts.$method.$route.$body" \
    | openssl dgst -sha256 -hmac "$COBRIX_API_KEY" | awk '{print $NF}')
  set -- -sS -X "$method" "$COBRIX_API_URL$route" \
    -H "Authorization: Bearer $COBRIX_API_KEY" \
    -H "Cobrix-Timestamp: $ts" \
    -H "Cobrix-Signature: v1=$sig"
  if [ -n "$key" ]; then set -- "$@" -H "Idempotency-Key: $key"; fi
  if [ -n "$body" ]; then set -- "$@" -H "Content-Type: application/json" --data-raw "$body"; fi
  curl "$@"
}
```

* `RUTA` es lo que va después de `/direct-debits`: `/banks`, `/{id}/execute` o `?status=succeeded`. Vacía para `POST /` y `GET /`.
* `CUERPO` es el JSON exacto que envías. La firma usa ese mismo texto.
* `IDEMPOTENCY_KEY` es obligatoria en los `POST`. Si repites una llamada por un timeout, usa la misma clave y el mismo cuerpo.

## Listar bancos

`GET /banks` · Scope `direct_debits:read`

Los bancos desde los que el pagador puede pagar. Usa `code` como `payer.bankCode` al pedir el código.

```bash theme={null}
cobrix GET /banks
```

```json Respuesta 200 theme={null}
{
  "banks": [
    { "code": "0102", "name": "Banco de Venezuela" },
    { "code": "0105", "name": "Banco Mercantil" },
    { "code": "0138", "name": "Banco Plaza" }
  ],
  "total": 3
}
```

Si la lista viene vacía, la empresa no puede cobrar con débito inmediato ahora. Ofrece otro método de pago.

Errores: solo los [comunes a todas las rutas](#errores-comunes-a-todas-las-rutas).

## Pedir el código

`POST /` · Scope `direct_debits:write`

Crea el cobro y pide al banco del pagador que le envíe el código por SMS. El cobro es el mismo de `POST /checkouts`: cliente, documento de cobro y sesión. Cobrix calcula el monto en bolívares. Nunca lo envíes tú.

```json Solicitud theme={null}
{
  "externalDocumentId": "PED-1001",
  "customerExternalId": "CLI-77",
  "customer": { "type": "individual", "name": "Ana Pérez" },
  "currency": "USD",
  "totalMinor": 1500,
  "description": "Botín de cuero",
  "payer": {
    "bankCode": "0102",
    "documentType": "V",
    "documentNumber": "12345678",
    "phone": "04120000000",
    "holderName": "Ana Pérez"
  }
}
```

```bash curl theme={null}
BODY='{
  "externalDocumentId": "PED-1001",
  "customerExternalId": "CLI-77",
  "customer": { "type": "individual", "name": "Ana Pérez" },
  "currency": "USD",
  "totalMinor": 1500,
  "description": "Botín de cuero",
  "payer": {
    "bankCode": "0102",
    "documentType": "V",
    "documentNumber": "12345678",
    "phone": "04120000000",
    "holderName": "Ana Pérez"
  }
}'
cobrix POST "" "$BODY" "PED-1001-codigo-1"
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `externalDocumentId` | Sí | Tu referencia del cobro, de 1 a 200 caracteres. |
| `customerExternalId` | Sí | El cliente en tu sistema. |
| `customer` | Sí | `type` (`individual` o `business`) y `name`. Opcionales: `email`, `phone`, `taxId`. |
| `currency` | Sí | `USD`, `VES` o `EUR`. El banco siempre debita bolívares. |
| `totalMinor` | Sí | Entero en unidades menores. `1500` es USD 15,00. |
| `description` | No | Texto del cobro. También es el concepto del débito. |
| `payer.bankCode` | Sí | 4 dígitos, de `GET /banks`. |
| `payer.documentType` | Sí | `V`, `E`, `J`, `P` o `G`. |
| `payer.documentNumber` | Sí | De 5 a 10 dígitos, sin letra ni puntos. |
| `payer.phone` | Sí | El celular asociado a la cuenta: 11 dígitos con el 0. |
| `payer.holderName` | Sí | Titular de la cuenta, de 2 a 120 caracteres. |
| `splits` | No | Reparte la venta entre varias cuentas. Ver [Repartir la venta](#repartir-la-venta). |

También acepta `lines`, `dueDate` y `expiresInHours`, igual que [crear el cobro del checkout embebido](https://docs.cobrix.co/api-guides/embedded-checkout.md#1-crea-el-cobro). No envíes otros campos: Cobrix responde `400 invalid_request`.

```json Respuesta 201 theme={null}
{
  "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
  "externalDocumentId": "PED-1001",
  "status": "otp_sent",
  "amount": { "minor": "1313475", "currency": "VES" },
  "reference": { "minor": 1500, "currency": "USD" },
  "otp": {
    "sentTo": "0412***00",
    "expiresAt": "2026-11-10T15:02:00.000Z",
    "validitySeconds": 120
  },
  "createdAt": "2026-11-10T15:00:00.000Z",
  "updatedAt": "2026-11-10T15:00:00.000Z"
}
```

* **Guarda `id`.** Lo usas para ejecutar, consultar, pedir otro código o cancelar.
* **`amount`** es lo que el banco va a debitar, siempre en bolívares. `minor` viene como texto: `"1313475"` es Bs 13.134,75.
* **`reference`** es el total del cobro en su moneda.
* **`otp`** dice a qué teléfono llegó el código (enmascarado) y cuándo vence. La vigencia la pone el banco.
* **Una referencia abierta se reutiliza.** Si `externalDocumentId` ya existe y sigue abierta, Cobrix la actualiza y abre un cobro nuevo.

| HTTP | Código | Cuándo |
| - | - | - |
| `409` | `checkout_document_closed` | La referencia ya está pagada o anulada. Usa otra. |
| `409` | `payer_debit_in_progress` | Otro débito de este cliente está en `processing`. |
| `422` | `direct_debit_unavailable` | La empresa no puede cobrar con débito inmediato. |
| `422` | `payer_bank_not_supported` | Ese banco no se puede debitar. Revisa `GET /banks`. |
| `422` | `payer_bank_rejected` | El banco del pagador no quiso enviar el código. Trae `bankCode`. |
| `422` | `payer_data_invalid` | Los datos del pagador no sirven para un débito, por ejemplo un teléfono que no es celular. |
| `422` | `invoice_total_mismatch` | Las `lines` no suman `totalMinor`. |
| `422` | `rate_unavailable` | Todavía no hay tasa del día. Reintenta más tarde. |
| `429` | `rate_limited` | Demasiados códigos para este pagador. Ver [Límites](#límites). |
| `503` | `bank_unavailable` | El banco no responde. Reintenta en unos minutos. |

También pueden salir los [errores comunes](#errores-comunes-a-todas-las-rutas), como `400 invalid_request` o `500 internal_error`.

### Repartir la venta

Con `splits` indicas a qué cuentas va el dinero de esta venta y en qué porcentaje. Tiene el mismo formato, las mismas reglas y los mismos errores que en [Links de cobro](https://docs.cobrix.co/api-reference/categories/checkout-links.md), sección «Repartir la venta entre varias cuentas».

* La llave necesita además `payout_splits:write`. Sin ese permiso responde `403 insufficient_scope`.
* La respuesta trae `splits` con cada cuenta enmascarada, en el mismo orden.
* Si `splits` tiene un error, Cobrix responde antes de crear el cobro o las cuentas.

## Ejecutar con el código

`POST /{id}/execute` · Scope `direct_debits:write`

Envía al banco el código que escribió el pagador.

```json Solicitud theme={null}
{ "otp": "12345678" }
```

```bash curl theme={null}
# ID: el id del débito. CODIGO: lo que escribió el pagador.
cobrix POST "/$ID/execute" "{\"otp\":\"$CODIGO\"}" "PED-1001-ejecutar-1"
```

`otp` son los dígitos que el banco envió por SMS. Tu servidor lo reenvía y no lo guarda. Cobrix tampoco lo guarda ni lo devuelve.

```json Cobrado theme={null}
{
  "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
  "externalDocumentId": "PED-1001",
  "status": "succeeded",
  "amount": { "minor": "1313475", "currency": "VES" },
  "paymentId": "b2c4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "createdAt": "2026-11-10T15:00:00.000Z",
  "updatedAt": "2026-11-10T15:01:10.000Z"
}
```

```json Rechazado theme={null}
{
  "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
  "externalDocumentId": "PED-1001",
  "status": "failed",
  "amount": { "minor": "1313475", "currency": "VES" },
  "error": {
    "code": "payer_bank_rejected",
    "message": "Tu cuenta no tiene saldo suficiente para este pago. Recarga o paga desde otra cuenta.",
    "bankCode": "AM04"
  },
  "createdAt": "2026-11-10T15:00:00.000Z",
  "updatedAt": "2026-11-10T15:01:10.000Z"
}
```

Responde `201` con el débito en uno de estos estados:

| Estado | Qué hacer |
| - | - |
| `succeeded` | Cobrado. Trae `paymentId`. Entrega el pedido cuando llegue `payment.succeeded`. |
| `processing` | El banco todavía no confirma. Espera el webhook o consulta `GET /{id}`. No cobres de nuevo. |
| `failed` | No se cobró. Muestra `error.message` al pagador. |
| `expired` | El código venció, aunque Cobrix ya haya cerrado el débito. Pide otro con `POST /{id}/otp`. |

* **Un rechazo del banco no es un error HTTP.** La respuesta es `201` con `status: failed` y el motivo en `error`.
* **Para reintentar después de `failed`**, llama otra vez a `POST /` con el mismo `externalDocumentId` y una `Idempotency-Key` nueva. El débito rechazado no se reutiliza.
* **Si la llamada se corta**, repítela con la misma `Idempotency-Key` y el mismo cuerpo. Recibes la misma respuesta y el débito no se envía dos veces. Con otra clave responde `409 direct_debit_not_executable`: consulta `GET /{id}`.

| HTTP | Código | Cuándo |
| - | - | - |
| `400` | `invalid_request` | `otp` no son solo dígitos (de 4 a 12). |
| `404` | `direct_debit_not_found` | El débito no existe para tu integración. |
| `409` | `direct_debit_not_executable` | Ya se envió al banco o ya terminó. Consulta `GET /{id}`. |
| `409` | `payer_debit_in_progress` | Otro débito de este cliente está en `processing`. Este débito queda `failed`. |
| `422` | `invalid_otp_format` | El código no tiene la forma que usa ese banco. El débito sigue esperando su código: pide al pagador que lo escriba de nuevo. |
| `503` | `bank_unavailable` | Cobrix no puede seguir el débito ahora. Reintenta en unos minutos. |
| `500` | `internal_error` | Falló algo de Cobrix. Consulta `GET /{id}` antes de reintentar. |

## Consultar un débito

`GET /{id}` · Scope `direct_debits:read`

El estado actual de un débito.

```bash theme={null}
cobrix GET "/$ID"
```

```json Respuesta 200 theme={null}
{
  "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
  "externalDocumentId": "PED-1001",
  "status": "otp_sent",
  "amount": { "minor": "1313475", "currency": "VES" },
  "otp": {
    "expiresAt": "2026-11-10T15:02:00.000Z",
    "validitySeconds": 74
  },
  "createdAt": "2026-11-10T15:00:00.000Z",
  "updatedAt": "2026-11-10T15:00:00.000Z"
}
```

* Mientras espera su código, `otp.validitySeconds` dice cuántos segundos le quedan.
* Cuando el código vence, el débito pasa a `expired` con `error.code: otp_expired`. Pide otro con `POST /{id}/otp`.
* `succeeded` trae `paymentId`. `failed`, `expired` y `cancelled` traen `error`.

| HTTP | Código | Cuándo |
| - | - | - |
| `404` | `direct_debit_not_found` | El `id` es de otra empresa, de otra integración o no existe. |

## Listar para conciliar

`GET /` · Scope `direct_debits:read`

Los débitos de los cobros que creó tu integración, del más nuevo al más viejo. Todos los filtros son opcionales.

| Parámetro | Qué filtra |
| - | - |
| `status` | Uno de los [seis estados](#estados). Un código vencido ya cuenta como `expired`. |
| `from`, `to` | Fecha de creación en ISO 8601, por ejemplo `2026-11-01T00:00:00Z`. Incluye `from`, no incluye `to`. |
| `externalDocumentId` | Los débitos de un cobro. |
| `limit` | De 1 a 100. Por defecto, 50. |
| `cursor` | El `nextCursor` de la página anterior. |

```bash theme={null}
cobrix GET "?status=succeeded&from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z"
```

```json Respuesta 200 theme={null}
{
  "items": [
    {
      "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
      "externalDocumentId": "PED-1001",
      "status": "succeeded",
      "amount": { "minor": "1313475", "currency": "VES" },
      "paymentId": "b2c4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "createdAt": "2026-11-01T15:00:00.000Z",
      "updatedAt": "2026-11-01T15:01:10.000Z"
    }
  ],
  "pagination": { "limit": 50, "hasMore": false, "nextCursor": null }
}
```

* Mientras `hasMore` sea `true`, pide la siguiente página con `cursor` igual a `nextCursor`.
* El cursor no repite ni salta débitos aunque entren nuevos mientras lees.
* Para conciliar, cruza cada débito `succeeded` con tu pedido por `externalDocumentId` y guarda su `paymentId`.

| HTTP | Código | Cuándo |
| - | - | - |
| `400` | `invalid_status` | `status` no es uno de los seis estados. |
| `400` | `invalid_date` | `from` o `to` no es una fecha ISO 8601. |
| `400` | `invalid_cursor` | El cursor está alterado o no es de esta lista. |

## Pedir otro código

`POST /{id}/otp` · Scope `direct_debits:write`

Para cuando el código venció o no llegó. Sirve para un débito en `otp_sent` o `expired`. Usa el mismo cobro y el mismo pagador.

Va sin cuerpo, con o sin `Content-Type: application/json`. Firma con el cuerpo vacío.

```bash theme={null}
cobrix POST "/$ID/otp" "" "PED-1001-otro-codigo-1"
```

```json Respuesta 201 theme={null}
{
  "id": "0d2f4b6a-8c1e-4a3b-9d5f-7e6a5b4c3d21",
  "externalDocumentId": "PED-1001",
  "status": "otp_sent",
  "amount": { "minor": "1313475", "currency": "VES" },
  "otp": {
    "sentTo": "0412***00",
    "expiresAt": "2026-11-10T15:06:00.000Z",
    "validitySeconds": 120
  },
  "createdAt": "2026-11-10T15:04:00.000Z",
  "updatedAt": "2026-11-10T15:04:00.000Z"
}
```

* **Si el código sigue vigente** (`otp_sent`), responde ese mismo débito con `otp.sentTo`, `otp.expiresAt` y los segundos que le quedan. El banco no envía otro SMS.
* **Si el código venció** (`expired`), responde un **débito nuevo, con su propio `id`**. El anterior queda `expired`. El código nuevo cuenta para el [límite](#límites) de 3 por hora.
* Ejecuta siempre con el `id` de esta respuesta.

| HTTP | Código | Cuándo |
| - | - | - |
| `404` | `direct_debit_not_found` | El débito no existe para tu integración. |
| `409` | `direct_debit_not_resendable` | El débito no está en `otp_sent` ni en `expired`. |
| `409` | `payer_debit_in_progress` | Otro débito de este cliente está en `processing`. |
| `422` | `payer_bank_rejected` | El banco del pagador no quiso enviar el código. Trae `bankCode`. |
| `422` | `payer_data_invalid` | Los datos del pagador no sirven para un débito. |
| `429` | `rate_limited` | Demasiados códigos para este pagador. Ver [Límites](#límites). |
| `503` | `bank_unavailable` | El banco no responde. Reintenta en unos minutos. |

## Cancelar

`POST /{id}/cancel` · Scope `direct_debits:write`

Cancela un débito que espera su código (`otp_sent`). Úsalo si el pagador elige otro método o abandona la compra. Va sin cuerpo, con o sin `Content-Type: application/json`.

```bash theme={null}
cobrix POST "/$ID/cancel" "" "PED-1001-cancelar-1"
```

```json Respuesta 201 theme={null}
{
  "id": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
  "externalDocumentId": "PED-1001",
  "status": "cancelled",
  "amount": { "minor": "1313475", "currency": "VES" },
  "error": {
    "code": "cancelled",
    "message": "El cobro se canceló antes de enviarse al banco."
  },
  "createdAt": "2026-11-10T15:00:00.000Z",
  "updatedAt": "2026-11-10T15:00:30.000Z"
}
```

| HTTP | Código | Cuándo |
| - | - | - |
| `404` | `direct_debit_not_found` | El débito no existe para tu integración. |
| `409` | `direct_debit_not_cancellable` | Ya se envió al banco, ya terminó o su código venció. Un débito enviado espera su resultado. |

## Estados

Los mismos seis estados para cualquier banco.

| Estado | Qué significa | ¿Se cobró? |
| - | - | - |
| `otp_sent` | El banco envió el código. Falta ejecutar. | No |
| `processing` | Enviado al banco. Falta su respuesta. | Todavía no se sabe |
| `succeeded` | Cobrado y aplicado al documento de cobro. | Sí |
| `failed` | El banco lo rechazó o falló el cobro. | No |
| `expired` | El código venció antes de ejecutarse. | No |
| `cancelled` | Lo cancelaste antes de ejecutar. | No |

`processing` se resuelve solo: Cobrix sigue consultando al banco hasta tener su respuesta. Mientras tanto, no pidas código ni ejecutes otro débito del mismo cliente: Cobrix responde `409 payer_debit_in_progress`.

`expired` también llega solo. Desde que vence el código, el débito se lee `expired` en `GET /{id}`, en `GET /` y en sus filtros. Un minuto después, Cobrix lo cierra aunque nadie lo consulte. Un débito vencido no se cobra, no bloquea otro débito del cliente y no envía webhook.

## Por qué no se cobró

Un débito `failed`, `expired` o `cancelled` trae `error`:

```json theme={null}
{
  "code": "payer_bank_rejected",
  "message": "Tu cuenta no tiene saldo suficiente para este pago. Recarga o paga desde otra cuenta.",
  "bankCode": "AM04"
}
```

* `code` es estable para cualquier banco. Úsalo en tu código.
* `message` está en español, listo para mostrar al pagador.
* `bankCode` es el código propio del banco, solo para soporte. Puede cambiar con el banco. Solo viene cuando el código es del banco.

| `error.code` | Cuándo |
| - | - |
| `payer_bank_rejected` | El banco del pagador rechazó el débito, por ejemplo por saldo insuficiente. |
| `payer_data_invalid` | Los datos del pagador no coinciden con su cuenta. |
| `bank_timeout` | El banco no respondió a tiempo. |
| `duplicate_debit` | El banco dice que ya tiene ese débito. |
| `bank_error` | Cualquier otro fallo: un código del banco sin clasificar o un fallo de Cobrix. Un fallo de Cobrix trae un mensaje genérico y no trae `bankCode`. |
| `otp_expired` | El código venció (`status: expired`). |
| `cancelled` | Lo cancelaste (`status: cancelled`), o el banco anuló el débito (`status: failed`). |

## Errores comunes a todas las rutas

Todos los errores HTTP de estas rutas traen `{ "error": { "code", "message" } }`. Consulta también [Errores y rate limits](https://docs.cobrix.co/resources/errors.md).

| HTTP | Código | Qué hacer |
| - | - | - |
| `400` | `invalid_request` | El cuerpo no cumple el formato. Corrige el campo que dice `field`. |
| `400` | `missing_idempotency_key` | Agrega `Idempotency-Key` al `POST`. |
| `401` | `invalid_api_key`, `revoked_api_key`, `expired_api_key` | Revisa o rota la llave. |
| `401` | `missing_signature`, `missing_timestamp`, `invalid_signature`, `timestamp_out_of_tolerance` | Firma con la ruta completa desde `/api` y el cuerpo exacto. |
| `403` | `company_mismatch`, `insufficient_scope` | Revisa el `companyId` y los scopes de la llave. |
| `409` | `idempotency_conflict` | Usaste la clave con otro cuerpo. Usa una clave nueva. |
| `409` | `request_in_progress` | La misma llamada sigue en curso. Espera y repítela. |
| `409` | `idempotency_result_ambiguous` | Consulta el débito antes de reintentar con otra clave. |
| `429` | `rate_limited` | Más de 120 llamadas por minuto a la misma ruta. Espera y reintenta. |
| `500` | `internal_error` | Falló algo de Cobrix. Reintenta en unos minutos. |

Un campo con formato incorrecto, o que no está en esta página, responde `400 invalid_request`. `field` es el primer campo con problema y `details` trae todos:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "payer.phone must be 11 digits starting with 0.",
    "field": "payer.phone",
    "details": [
      {
        "field": "payer.phone",
        "message": "payer.phone must be 11 digits starting with 0."
      }
    ]
  }
}
```

`500 internal_error` es un fallo de Cobrix, no del banco ni de tus datos. El mensaje es genérico y no trae detalles internos. Si envías `X-Request-Id`, la respuesta lo devuelve como `requestId`: dáselo a soporte.

## Webhooks

Configura tus webhooks en **Integraciones › Webhooks** y verifica la firma de cada uno. Consulta [Firma de webhooks](https://docs.cobrix.co/guides/webhooks/signature).

| Evento | Cuándo |
| - | - |
| [`payment.succeeded`](https://docs.cobrix.co/guides/webhooks/events/payment-succeeded) | El débito se cobró. |
| [`collection_document.paid`](https://docs.cobrix.co/guides/webhooks/events/collection-document-paid) | El documento de cobro quedó pagado. |
| [`payment.failed`](https://docs.cobrix.co/guides/webhooks/events/payment-failed) | El débito quedó `failed`. |

* **`payment.succeeded`:** `data.paymentId` es el `paymentId` del débito. Tu `externalDocumentId` llega en `data.documents[].externalInvoiceId`.
* **`payment.failed`:** sale una sola vez por débito. No sale cuando el código vence ni cuando cancelas: nada llegó al banco.

Un débito creado con esta API llega en `payment.failed` así:

```json theme={null}
{
  "id": "evt_5b8e1f3a-2c4d-4e6f-9a7b-0c1d2e3f4a5b",
  "event": "payment.failed",
  "created_at": "2026-11-10T15:01:10.000Z",
  "api_version": "2025-01-21",
  "data": {
    "paymentId": null,
    "directDebitId": "6f0c9d1e-3a52-4c0e-9a41-2f5b7c8d9e10",
    "externalDocumentId": "PED-1001",
    "companyId": "4a9c2e71-5d3b-4f8a-b1c6-2e7d9f0a3b58",
    "checkoutSessionId": "9e1d3c5b-7a2f-4b8e-a6d4-3c2b1a0f9e87",
    "companyCustomerId": "2c7a9e1b-4d6f-4a3c-8b5e-1f0d9c8b7a65",
    "amount": 13134.75,
    "amountMinor": 1313475,
    "currency": "VES",
    "method": "debito_inmediato",
    "status": "failed",
    "reason": "Tu cuenta no tiene saldo suficiente para este pago. Recarga o paga desde otra cuenta.",
    "error": {
      "code": "payer_bank_rejected",
      "message": "Tu cuenta no tiene saldo suficiente para este pago. Recarga o paga desde otra cuenta.",
      "bankCode": "AM04"
    },
    "failedAt": "2026-11-10T15:01:10.000Z"
  }
}
```

* `paymentId` va en `null`: un débito rechazado no crea pago. Identifícalo con `directDebitId`, que es el `id` del débito.
* `error` es el mismo objeto de `GET /{id}`. Si falló por algo de Cobrix, trae `bank_error` sin `bankCode`.

## Límites

* **Códigos por pagador:** 3 por hora por documento del pagador, aunque pague para distintos clientes tuyos. También 3 por hora por cliente. Después, `429 rate_limited`.
* **Un código a la vez:** si llegan dos pedidos de código para el mismo pagador al mismo tiempo, uno pasa y el otro recibe `429 rate_limited`.
* **Un débito en curso por cliente:** mientras un débito de un cliente (`customerExternalId`) está en `processing`, pedir un código o ejecutar otro débito de ese cliente responde `409 payer_debit_in_progress`. Un débito `otp_sent`, `expired` o `cancelled` no bloquea.
* **Llamadas por llave:** 120 por minuto por ruta.
* **Datos mínimos:** las respuestas y los webhooks nunca traen el código, ni el documento, el teléfono o la cuenta completos.
* **Cada débito es de su empresa y su integración.** Un `id` ajeno responde `404`, nunca `403`.

## Probar en sandbox

1. Pide a Cobrix que active el débito inmediato en tu empresa de sandbox.
2. Crea una llave de sandbox con `direct_debits:read` y `direct_debits:write`.
3. Configura tus webhooks y verifica la firma.
4. Llama a `GET /banks` y confirma que trae bancos.
5. Pide un código con `POST /` y ejecútalo con `POST /{id}/execute`.
6. Confirma que tu servidor recibe `payment.succeeded`.
7. Prueba también un código vencido, un cobro cancelado y un rechazo.

> [!WARNING]
>
> En sandbox el banco es real: el pagador recibe un SMS y el débito mueve dinero. Prueba con una cuenta tuya y un monto pequeño.

> [card] [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md)
>
> Cómo calcular `Cobrix-Signature` en tu lenguaje.

> [card] [Webhooks de pagos](https://docs.cobrix.co/guides/webhooks/categories/payments.md)
>
> Firma y contenido de `payment.succeeded` y `payment.failed`.


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