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

# Validación de pagos por API

> Comprueba desde tu servidor un pago móvil, una transferencia o un Zelle que recibió tu empresa

Tu servidor envía los datos de un pago que recibió tu empresa y Cobrix responde si es bueno.

| Método | Cómo se valida | Cuándo tienes el resultado |
| - | - | - |
| Pago móvil (`pago_movil`) | Cobrix consulta al banco de la cuenta receptora. | En la misma llamada. |
| Transferencia (`bank_transfer`) | Cobrix consulta al banco de la cuenta receptora. | En la misma llamada. |
| Zelle (`zelle`) | Una persona de tu empresa lo aprueba o lo rechaza en el panel de Cobrix. | Por webhook o consultando la validación. |

Llama siempre desde tu servidor. La llave nunca va en el navegador. Si quieres que tu cliente escriba la referencia en tu web, usa la [validación embebida](https://docs.cobrix.co/api-guides/embedded-payment-verification.md).

> [!NOTE]
>
> **Desde el 17/11/2026, la moneda es la de la cuenta receptora.** Antes, un `POST` con una `currency` distinta de la de la cuenta se aceptaba. Ahora responde `422 invalid_field`. Si no envías `currency`, o envías la de la cuenta, no cambia nada. En una cuenta bancaria en `USD` o `EUR`, el valor por defecto ahora es la moneda de la cuenta (antes era `VES`), y esa cuenta ya no acepta `pago_movil`. Consulta [La moneda es la de la cuenta](#la-moneda-es-la-de-la-cuenta).
>
> **También desde el 17/11/2026, una cuenta bancaria ofrece `pago_movil` solo si Cobrix conoce el teléfono que lo recibe.** Consulta [El pago móvil necesita su teléfono](#el-pago-móvil-necesita-su-teléfono).

## Cómo funciona

**1. Lista las cuentas receptoras**

`GET /receiver-accounts` trae las cuentas de tu empresa contra las que puedes validar.

**2. Envía el pago**

`POST /` con la cuenta receptora, la referencia, el monto y el día del pago.

**3. Lee el resultado**

La respuesta `201` trae `status`. En pago móvil y transferencia ya es el resultado del banco.

**4. Si es Zelle, espera la revisión**

Queda en `pending_review`. Tu servidor recibe un webhook cuando alguien de tu empresa lo resuelve.

## Antes de empezar

* Crea una llave con `payment_verifications:write` y `payment_verifications:read` en **Configuración → Integraciones → Llaves API**. Consulta [Autenticación](https://docs.cobrix.co/authentication.md).
* Firma cada llamada. La ruta que firmas empieza en `/api`. Consulta [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md).
* El `POST` lleva `Idempotency-Key`, de hasta 255 caracteres. Consulta [Idempotencia](https://docs.cobrix.co/api-guides/idempotency.md).
* Para Zelle, suscribe tu webhook a `payment_verification.verified` y `payment_verification.rejected`.

Las rutas de esta guía van después de la URL base del [ambiente](https://docs.cobrix.co/environments.md), que ya termina en `/api`: `https://api.cobrix.co/api/integrations/v1/{companyId}/payment-verifications` en producción. Las rutas cortas (`POST /`, `GET /receiver-accounts`) van después de esa. `{companyId}` es la empresa de la llave: con otro responde `403 company_mismatch`. Hay un cliente firmado en [Ejemplos de código](https://docs.cobrix.co/resources/code-examples.md).

| Operación | Permiso | Método y ruta |
| - | - | - |
| [Listar cuentas receptoras](#1-lista-las-cuentas-receptoras) | `payment_verifications:read` | `GET /receiver-accounts` |
| [Validar un pago](#2-envía-el-pago) | `payment_verifications:write` | `POST /` |
| [Consultar una validación](#consultar-una-validación) | `payment_verifications:read` | `GET /{verificationId}` |

## Bancos con respuesta inmediata

Cobrix consulta al banco cuando la cuenta receptora es de **Banco de Venezuela (`0102`), Mercantil (`0105`) o Banesco (`0134`)**, en pago móvil y en transferencia.

La lista de tu empresa la da `GET /receiver-accounts`. Una cuenta de banco aparece solo si Cobrix puede consultarla: el banco admite la consulta y tu empresa tiene esa cuenta conectada en Cobrix. Contra una cuenta que no aparece no puedes validar con esta API.

## 1. Lista las cuentas receptoras

```http theme={null}
GET /integrations/v1/{companyId}/payment-verifications/receiver-accounts
```

```json Respuesta 200 theme={null}
{
  "data": [
    {
      "receiverAccountKey": "pago_movil:a41c7e90-2b5d-4f13-8a6e-9c0d1e2f3a45",
      "bankCode": "0102",
      "bankName": "Banco de Venezuela",
      "methods": ["pago_movil"],
      "lookupSupported": true,
      "maskedIdentifier": "••••0000",
      "currency": "VES"
    },
    {
      "receiverAccountKey": "bank:3d9a7c52-1e4b-4f6a-8c2d-7b5e9f1a0c34",
      "bankCode": "0105",
      "bankName": "Banco Mercantil",
      "methods": ["pago_movil", "bank_transfer"],
      "lookupSupported": true,
      "maskedIdentifier": "••••4821",
      "currency": "VES"
    },
    {
      "receiverAccountKey": "zelle:91d2b6e4-5a3c-4f7d-8e1b-2c6a9d0f4b75",
      "bankCode": null,
      "bankName": null,
      "methods": ["zelle"],
      "lookupSupported": false,
      "maskedIdentifier": "c•••@example.com",
      "currency": "USD"
    }
  ]
}
```

| Campo | Qué significa |
| - | - |
| `receiverAccountKey` | Identifica la cuenta. Es lo que envías al validar. |
| `bankCode`, `bankName` | El banco de la cuenta. `null` en Zelle. |
| `methods` | Los métodos que puedes validar contra esta cuenta. |
| `lookupSupported` | `true`: Cobrix consulta al banco y responde en el `POST`. `false` (Zelle): la validación queda en revisión. |
| `maskedIdentifier` | Los últimos 4 dígitos del teléfono o del número de cuenta, o el correo Zelle enmascarado. |
| `currency` | La moneda que recibe la cuenta: `VES`, `USD` o `EUR`. Es la única en la que puedes validar contra ella. |

### Cómo elegir la cuenta receptora

* Usa la cuenta de tu empresa a la que tu cliente dice que pagó.
* La cuenta debe traer el método del pago en `methods`.
* Si hay dos cuentas del mismo banco, distínguelas por `maskedIdentifier`.
* Envía `receiverAccountKey` tal como viene. No lo armes tú.
* Cobrix consulta solo al banco de esa cuenta.
* La cuenta fija la moneda. Consulta [La moneda es la de la cuenta](#la-moneda-es-la-de-la-cuenta).
* Una cuenta que no existe, está inactiva o no acepta el método responde `422 invalid_receiver_account`.
* En Zelle es opcional: si tu empresa tiene una sola cuenta Zelle, Cobrix usa esa. Con varias, envíala para que quien revisa sepa a cuál llegó el pago.

### La moneda es la de la cuenta

La moneda de una validación es la moneda de su cuenta receptora. `GET /receiver-accounts` la trae en `currency`.

| Cuenta | `currency` | Métodos |
| - | - | - |
| Pago móvil de tu empresa | `VES` | `pago_movil` |
| Cuenta bancaria en `VES` | `VES` | `pago_movil` y `bank_transfer`, según lo que permita consultar el banco. `pago_movil`, solo con [su teléfono](#el-pago-móvil-necesita-su-teléfono). |
| Cuenta bancaria en `USD` o `EUR` | La de la cuenta | Solo `bank_transfer` |
| Zelle | `USD` | `zelle` |

* **Si no envías `currency`, Cobrix usa la de la cuenta.**
* **Si envías otra, responde `422 invalid_field`** con `field: "currency"`. `detail` dice cuál es la moneda de la cuenta. No consulta al banco.
* **El pago móvil solo existe en bolívares.** `pago_movil` sobre una cuenta en `USD` o `EUR` responde `422 invalid_receiver_account`.
* **Una cuenta bancaria cuya moneda no sea `VES`, `USD` ni `EUR` no aparece en la lista.** Tampoco una cuenta en `USD` o `EUR` que su banco solo deja consultar por pago móvil. Si envías una de ellas, responde `422 invalid_receiver_account`.

### El pago móvil necesita su teléfono

Cobrix ofrece `pago_movil` solo donde conoce el teléfono al que tu cliente envía el dinero.

* **Si tu empresa tiene un pago móvil configurado en ese banco**, aparece como su propia cuenta, con `receiverAccountKey` `pago_movil:…` o `pago_movil_method:…`.
* **Si no, la cuenta bancaria (`bank:…`) ofrece `pago_movil` solo si su conexión con el banco tiene el teléfono receptor configurado.** Sin él, ofrece solo `bank_transfer`. Si su banco solo deja consultar pago móvil, no aparece.
* **`pago_movil` sobre una cuenta bancaria sin teléfono responde como un método que la cuenta no acepta.** No consulta al banco.

| Ruta | Respuesta |
| - | - |
| `POST /payment-verifications` | `422 invalid_receiver_account` |
| `POST /payment-verifications/tokens` | `422 method_not_available`. Sin `methods`, el token sale solo con `bank_transfer`. |
| El formulario de un token emitido antes del 17/11/2026 | `pago_movil` deja de aparecer. Un envío con `pago_movil` responde `422 method_not_allowed` y no gasta intento. |

Para validar pago móvil en ese banco, configura el pago móvil de tu empresa en **Configuración › Pago Móvil**, o escribe a soporte de Cobrix.

```json theme={null}
{
  "error": {
    "code": "invalid_field",
    "message": "A field is invalid.",
    "field": "currency",
    "detail": "Payments to this receiver account are in VES."
  }
}
```

**Por qué.** El banco compara solo la cifra, no la moneda. Sin esta regla, un pago de Bs 1.500,00 confirmaría una validación por USD 1.500,00 sobre una cuenta en bolívares.

## 2. Envía el pago

```http theme={null}
POST /integrations/v1/{companyId}/payment-verifications
```

```json Solicitud theme={null}
{
  "method": "pago_movil",
  "receiverAccountKey": "bank:3d9a7c52-1e4b-4f6a-8c2d-7b5e9f1a0c34",
  "reference": "000123456",
  "amountMinor": 150000,
  "paymentDate": "2026-11-12",
  "payerBankCode": "0134",
  "payerPhone": "04120000000",
  "payerDocument": "V12345678",
  "externalReference": "PED-1001"
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `method` | Sí | `pago_movil`, `bank_transfer` o `zelle`. |
| `receiverAccountKey` | Sí, salvo en Zelle | Una cuenta de `GET /receiver-accounts` que acepte ese método. |
| `reference` | Sí | La referencia del comprobante, completa, de 1 a 64 caracteres. En Zelle, la confirmación completa. |
| `amountMinor` | Sí | Número entero JSON en unidades menores, mínimo 1. `150000` es Bs 1.500,00. Nunca un texto ni un monto con decimales. |
| `currency` | No | La moneda de la cuenta receptora. Si no la envías, es esa. Otra responde `422 invalid_field`. Zelle es siempre `USD`. |
| `paymentDate` | Sí | El día del pago, `YYYY-MM-DD`. |
| `payerBankCode` | Según el banco | Banco desde el que pagó la persona, 4 dígitos. |
| `payerPhone` | Según el banco | Teléfono del pagador. |
| `payerDocument` | Según el banco | Cédula o RIF del pagador. |
| `payerName` | No | Nombre de quien envió el Zelle, hasta 200 caracteres. Lo ve quien revisa. Nunca vuelve en la respuesta. |
| `externalReference` | No | Tu referencia, hasta 128 caracteres. Vuelve tal cual. |
| `metadata` | No | Objeto JSON que vuelve tal cual. Hasta 2048 bytes serializado. |

No envíes otros campos: Cobrix responde `400 invalid_request`.

**Cada campo acepta solo el tipo JSON de la tabla.** Cobrix no convierte tipos. `amountMinor` es un número: `150000`, no `"150000"`, `"1500.00"` ni `true`. Los demás campos son textos entre comillas, también `payerBankCode` y `payerPhone`. Otro tipo responde `400 invalid_request` con su `field`. Consulta el [ejemplo](#errores).

Qué datos del pagador son obligatorios depende del banco de la cuenta receptora y del método. Si falta alguno, Cobrix responde `422 missing_fields` con todos en `fields`, sin consultar al banco:

```json theme={null}
{
  "error": {
    "code": "missing_fields",
    "message": "Required fields are missing for this receiver account.",
    "fields": ["payerPhone", "payerBankCode"]
  }
}
```

```json Respuesta 201 theme={null}
{
  "id": "0b6e2f4a-7c1d-4e8b-9a3f-5d2c1b0a9e87",
  "method": "pago_movil",
  "status": "verified",
  "reason": null,
  "warnings": [],
  "reference": "••••3456",
  "amountMinor": 150000,
  "currency": "VES",
  "paymentDate": "2026-11-12",
  "bank": { "amountMinor": 150000, "valueDate": "2026-11-12" },
  "receiverAccountKey": "bank:3d9a7c52-1e4b-4f6a-8c2d-7b5e9f1a0c34",
  "externalReference": "PED-1001",
  "metadata": null,
  "createdAt": "2026-11-13T12:00:00.000Z",
  "resolvedAt": "2026-11-13T12:00:01.000Z",
  "resolvedBy": "bank",
  "reviewNote": null,
  "tokenId": null
}
```

* **Guarda `id`.** Con él consultas la validación.
* **`tokenId`** es `null` en una validación que pide tu servidor. Trae el `id` del token cuando tu cliente envió el pago desde tu web con la [validación embebida](https://docs.cobrix.co/api-guides/embedded-payment-verification.md).
* **Un resultado negativo no es un error HTTP.** La respuesta es `201` con su `status`.
* **`reference` vuelve enmascarada:** solo sus últimos 4 caracteres, después de [limpiarla](#cómo-compara-cobrix-la-referencia). El teléfono, el documento y el nombre del pagador nunca vuelven.
* **`bank`** es lo que informó el banco. Solo viene en `verified` tras una respuesta del banco.

## 3. Lee el resultado

| `status` | Qué significa | Qué hacer |
| - | - | - |
| `verified` | El banco confirmó el pago, o una persona de tu empresa aprobó el Zelle. | Da el pago por bueno. Revisa `warnings`. |
| `not_found` | El banco no tiene un pago con esos datos. | No lo des por bueno. Revisa la referencia, el monto, el día y la cuenta receptora. |
| `mismatch` | El banco rechazó el pago porque un dato no coincide. | No lo des por bueno. `reason` dice qué dato. |
| `already_used` | La referencia ya se usó en otra validación de tu empresa. | No lo aceptes como un pago nuevo. |
| `ambiguous` | Más de un pago coincide y Cobrix no marcó ninguno. | No lo des por bueno. Valida con la referencia completa. |
| `unverifiable` | Cobrix no pudo consultar al banco. | No dice nada del pago. `reason` dice si sirve reintentar. |
| `pending_review` | Zelle en revisión. | Espera el webhook o consulta la validación. |
| `rejected` | Una persona de tu empresa rechazó el Zelle. | No lo des por bueno. Lee `reviewNote`. |

> [!WARNING]
>
> Solo `verified` confirma el pago. `unverifiable` y `pending_review` no son un rechazo ni una aprobación.

**Una validación `verified` marca la referencia como usada en tu empresa.** La siguiente validación de esa referencia responde `already_used`, venga de esta API, del panel de Cobrix o del checkout. Si la usó antes una validación de tu misma integración, la respuesta trae `originalVerificationId` con el `id` de esa validación.

### Cómo compara Cobrix la referencia

* **Antes de comparar, Cobrix limpia la referencia:** quita espacios, guiones, puntos y comas, y pasa las letras a mayúsculas. `0001-2345`, `0001 2345` y `00012345` son la misma referencia.
* **Lo que vuelve en `reference`** son los últimos 4 caracteres de la referencia ya limpia.
* **En pago móvil y transferencia, «ya usada» se decide con los últimos 6 caracteres**, por empresa y por banco de la cuenta receptora. Dos referencias distintas que terminan en los mismos 6 caracteres cuentan como la misma: la segunda responde `already_used`.
* **En Zelle cuenta la confirmación completa.**

### Motivos en `reason`

| `status` | `reason` | Qué hacer |
| - | - | - |
| `mismatch` | `amount_mismatch`, `date_mismatch`, `phone_mismatch`, `document_mismatch`, `bank_mismatch` | El monto, el día, el teléfono, el documento o el banco del pagador no coincide. Corrige el dato y valida otra vez. |
| `mismatch` | `duplicate_reference`, `already_reconciled`, `bank_rejected` | El banco rechazó la consulta. No des el pago por bueno. |
| `unverifiable` | `bank_unavailable` | El banco no respondió. Valida otra vez más tarde, con una `Idempotency-Key` nueva. |
| `unverifiable` | `payment_too_old` | El banco ya no deja consultar un pago de ese día. Reintentar no sirve. |
| `unverifiable` | `invalid_payer_data` | El banco no aceptó el formato de un dato del pagador. Corrígelo y valida otra vez. |
| `unverifiable` | `provider_misconfigured` | La conexión de tu empresa con el banco tiene un problema. Reintentar no sirve: escribe a soporte de Cobrix. |
| `already_used` | `reference_already_used` | La referencia ya se usó. |
| `ambiguous` | `multiple_matches` | Más de un pago coincide. |
| `rejected` | `rejected_by_reviewer` | Lo rechazó una persona de tu empresa. |

### Avisos en `warnings`

Solo vienen en `verified`. El pago está confirmado; el aviso agrega contexto.

| Aviso | Qué significa |
| - | - |
| `already_recorded_in_cobrix` | Cobrix ya tiene un pago de tu empresa con esa referencia, aplicado a un documento de cobro. |
| `pending_in_cobrix` | Cobrix tiene un pago de tu empresa con esa referencia, esperando aprobación. |
| `bank_amount_differs` | El banco informó un monto distinto de `amountMinor`. El del banco está en `bank.amountMinor`. |

## Zelle

Zelle no tiene consulta al banco. Cobrix guarda la validación y una persona de tu empresa la revisa.

**1. Envía el Zelle**

`POST /` con `method: "zelle"`, la confirmación completa en `reference`, el monto en USD y el día. Responde `201` con `status: pending_review`.

**2. Tu empresa lo revisa en el panel de Cobrix**

Una persona de tu empresa lo compara con el estado de cuenta de Zelle y lo aprueba o lo rechaza. Puede dejar una nota.

**3. Tu servidor recibe el resultado**

Llega `payment_verification.verified` o `payment_verification.rejected`. La nota viene en `reviewNote`.

```json Zelle en revisión theme={null}
{
  "id": "7e2a9c4d-6b1f-4a3e-9d8c-0f5b2e7a4c61",
  "method": "zelle",
  "status": "pending_review",
  "reason": null,
  "warnings": [],
  "reference": "••••7731",
  "amountMinor": 5000,
  "currency": "USD",
  "paymentDate": "2026-11-12",
  "bank": null,
  "receiverAccountKey": "zelle:91d2b6e4-5a3c-4f7d-8e1b-2c6a9d0f4b75",
  "externalReference": "PED-1002",
  "metadata": null,
  "createdAt": "2026-11-12T10:00:00.000Z",
  "resolvedAt": null,
  "resolvedBy": null,
  "reviewNote": null,
  "tokenId": null
}
```

> [!WARNING]
>
> **Un Zelle en revisión no vence.** Queda en `pending_review` hasta que alguien de tu empresa lo resuelve: Cobrix no lo aprueba ni lo rechaza solo, y no avisa mientras espera. Te enteras por el webhook o consultando `GET /{verificationId}`. Si tu flujo necesita un plazo, ponlo en tu sistema.

* Si tu empresa no tiene Zelle configurado, el `POST` responde `422 method_not_available`.
* Con otra moneda que no sea `USD`, responde `422 invalid_field`.
* La revisión se hace solo en el panel de Cobrix. No hay una ruta de esta API para aprobar o rechazar.

### La misma confirmación dos veces

Cobrix no compara confirmaciones al crear la validación. Un segundo `POST` con la misma confirmación y otra `Idempotency-Key` crea otra validación en `pending_review`, aunque la primera siga en revisión o ya esté aprobada.

* Solo una de las dos se puede aprobar.
* La otra no cambia sola: sigue en `pending_review` hasta que una persona de tu empresa la rechaza. Entonces llega `payment_verification.rejected`.
* No envíes dos veces la misma confirmación. Antes de enviarla, busca en tu sistema si ya la validaste.

## Consultar una validación

```http theme={null}
GET /integrations/v1/{companyId}/payment-verifications/{verificationId}
```

Devuelve la validación con su estado actual. Un `id` de otra empresa o que no existe responde `404 payment_verification_not_found`.

## Reintentos

**Toda respuesta `201` queda guardada con su `Idempotency-Key`**, también `unverifiable`, `not_found` y `pending_review`. La misma clave con el mismo cuerpo devuelve esa respuesta guardada: Cobrix no consulta al banco otra vez.

> [!WARNING]
>
> Un `unverifiable` porque el banco no respondió es una respuesta completa. Si reintentas con la misma `Idempotency-Key`, recibes el mismo `unverifiable`. Para consultar al banco otra vez, envía el `POST` con una **clave nueva**.

| Qué recibiste | Qué hacer |
| - | - |
| Timeout o `5xx` | Repite con la misma clave y el mismo cuerpo. |
| `409 request_in_progress` | Otra llamada con esa clave sigue en curso. Dura como mucho 30 segundos. Espera y repite con la misma clave. |
| `201` con `unverifiable` o `not_found` | Para consultar al banco otra vez, usa una clave nueva. |
| `201` con `pending_review` | No lo envíes de nuevo. La respuesta guardada sigue diciendo `pending_review` aunque ya esté resuelto: el estado actual lo da `GET /{verificationId}`. |
| `422` | Corrige el cuerpo y envía con una clave nueva. La misma clave con otro cuerpo responde `409 idempotency_conflict`. |
| `409 idempotency_result_ambiguous` | Esa clave ya no responde. Valida con una clave nueva. |

Si una respuesta `verified` se pierde y validas el mismo pago con otra clave, recibes `already_used` con `originalVerificationId`: es el `id` de la validación que ya lo confirmó.

## Errores

Los errores traen `{ "error": { "code", "message" } }`. Los comunes a toda la API están en [Errores y rate limits](https://docs.cobrix.co/resources/errors.md).

| HTTP | Código | Cuándo |
| - | - | - |
| `400` | `missing_idempotency_key` | Falta `Idempotency-Key` en el `POST`. |
| `400` | `invalid_request` | El cuerpo o el `verificationId` no cumple el formato o el tipo. Corrige el campo que dice `field`. |
| `403` | `company_mismatch` | El `companyId` de la ruta no es el de la empresa de la llave. |
| `403` | `verification_limit_reached` | Tu empresa alcanzó su número de validaciones configurado. |
| `404` | `payment_verification_not_found` | La validación no existe o es de otra empresa. |
| `409` | `idempotency_conflict` | Usaste la clave con otro cuerpo. |
| `409` | `request_in_progress` | Otra llamada con esa clave sigue en curso, también si dos reintentos de una llamada fallida llegan a la vez. |
| `409` | `idempotency_result_ambiguous` | Esa clave ya no responde. Usa una nueva. |
| `422` | `missing_fields` | Faltan datos del pagador. `fields` los trae todos. |
| `422` | `invalid_field` | Un dato no sirve. `field` dice cuál y `detail` por qué: una moneda que no es la de la cuenta, un teléfono mal escrito, una referencia más corta de lo que admite el banco o un día que no existe. |
| `422` | `invalid_receiver_account` | La cuenta no existe, está inactiva, no tiene una moneda reconocida o no acepta ese método, también `pago_movil` en una cuenta en `USD` o `EUR` o en una cuenta bancaria [sin teléfono](#el-pago-móvil-necesita-su-teléfono). |
| `422` | `method_not_available` | Tu empresa no tiene Zelle configurado. |
| `429` | `rate_limited` | Pasaste el [límite](#límites) de la llave. |
| `500` | `internal_error` | Falló algo de Cobrix. Repite con la misma clave en unos minutos. |

Ningún `4xx` consulta al banco ni crea la validación.

Un campo que falta, con otro tipo JSON, con formato incorrecto o que no está en esta página, y un `verificationId` que no es un UUID, responden `400 invalid_request`. `field` y `message` son los del primer problema y `details` trae todos. No gasta la `Idempotency-Key`: corrige el cuerpo y envía con la misma clave.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "amountMinor must be an integer number",
    "field": "amountMinor",
    "details": [
      {
        "field": "amountMinor",
        "message": "amountMinor must be an integer number"
      }
    ]
  }
}
```

Es la respuesta a `"amountMinor": "1500.00"`: el monto va como número entero en unidades menores.

Un cuerpo vacío o que no es JSON válido también responde `400`, pero con el formato del servidor web, sin `error.code`: comprueba que `error` sea un objeto antes de leer `error.code`.

`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`, vuelve como `requestId` en los errores `400`, `401`, `429` y `500`, y en `403 company_mismatch` y `403 insufficient_scope`: dáselo a soporte. No vuelve en `403 verification_limit_reached`, `404`, `409` ni `422`.

## Webhooks

Un pago móvil o una transferencia que envía tu servidor no manda webhooks: su resultado llega en la respuesta del `POST`. Los webhooks avisan de un Zelle revisado y de lo que tu cliente envía desde tu web con la [validación embebida](https://docs.cobrix.co/api-guides/embedded-payment-verification.md). Configúralos en **Integraciones › Webhooks** y verifica su firma. Consulta [Firma de webhooks](https://docs.cobrix.co/guides/webhooks/signature).

| Evento | Cuándo |
| - | - |
| [`payment_verification.verified`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-verified) | Una persona de tu empresa aprobó un Zelle, o el banco confirmó un pago que tu cliente envió con un token. |
| [`payment_verification.rejected`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-rejected) | Una persona de tu empresa rechazó un Zelle. |
| [`payment_verification.failed`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-failed) | Un token gastó sus intentos sin un pago verificado. Solo en la validación embebida. |

En `verified` y `rejected`, `data` es la misma validación que devuelve `GET /{verificationId}`.

## Límites

* **Validaciones por llave:** 60 `POST` por minuto. Las consultas, 120 por minuto por ruta.
* **Validaciones por empresa:** las que el banco confirma cuentan para el número configurado de tu empresa. Al alcanzarlo, el `POST` responde `403 verification_limit_reached`.
* **Datos mínimos:** las respuestas y los webhooks traen la referencia enmascarada y nunca el teléfono, el documento o el nombre del pagador.
* **Cada validación es de su empresa.** Un `id` ajeno responde `404`.

> [card] [Referencia de la API](https://docs.cobrix.co/api-reference/catalog.md)
>
> Campos, respuestas y códigos de cada ruta.

> [card] [Webhooks de validación](https://docs.cobrix.co/guides/webhooks/categories/payment-verifications.md)
>
> Payload de cada evento `payment_verification.*`.

> [card] [Validación embebida](https://docs.cobrix.co/api-guides/embedded-payment-verification.md)
>
> Tu cliente escribe la referencia en tu web, con un token corto.


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