> ## 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 embebida de pagos

> Tu cliente escribe la referencia de su pago en tu web y Cobrix la valida con el banco

Con la validación embebida, tu cliente escribe la referencia de su pago móvil, transferencia o Zelle **en tu web**. Cobrix la valida con el banco y tu servidor recibe el resultado.

Tu llave nunca llega al navegador. Tu servidor pide un **token** para un pedido y tu página usa ese token. El token vive pocos minutos y sirve para un solo pedido.

## Cuándo usarla

| | Validación embebida | [Validación por API](https://docs.cobrix.co/api-guides/payment-verifications.md) |
| - | - | - |
| Quién escribe la referencia | Tu cliente, en tu web. | Tu sistema, con datos que ya tiene. |
| Desde dónde se llama | El navegador, con un token. | Tu servidor, con tu llave. |
| El formulario | Lo pone Cobrix. Pide los datos que exige el banco de la cuenta. | Lo haces tú. |
| El resultado | Tu servidor lo lee del token o lo recibe por webhook. | En la respuesta del `POST`. Zelle, por webhook. |

Usa la validación embebida cuando tu cliente está en tu web y no quieres construir el formulario. Usa la API cuando tu sistema ya tiene los datos del pago.

## Cómo funciona

**1. Tu servidor pide un token**

`POST /payment-verifications/tokens` con la cuenta receptora, el monto y tu referencia del pedido. Cobrix responde con el `token`.

**2. Tu página muestra el formulario**

`checkout.js` con el token. Tu cliente escribe la referencia y Cobrix la valida con el banco.

**3. Tu servidor confirma el resultado**

Consulta el token o espera el webhook. Entrega el pedido solo con lo que dice tu servidor.

> [!WARNING]
>
> **El evento del navegador es un aviso, no una prueba.** Entrega el pedido solo cuando tu servidor confirma el resultado: consultando el token o con el webhook firmado.

## Antes de empezar

* Crea una llave con `payment_verifications:write` y `payment_verifications:read`. Consulta [Autenticación](https://docs.cobrix.co/authentication.md).
* Registra tus webs en **Configuración › Integraciones › Checkout embebido**. El formulario solo funciona en esas webs, y sin ninguna emitir un token responde `422 embed_domain_required`. Las reglas de la dirección están en [Registra tu web](https://docs.cobrix.co/api-guides/embedded-checkout.md#3-registra-tu-web).
* Tu empresa necesita el checkout embebido activo. Lo está por defecto. Si está apagado, emitir un token responde `403 embed_disabled`: escribe a soporte de Cobrix.
* Suscribe tu webhook a `payment_verification.verified`, `payment_verification.rejected` y `payment_verification.failed`. Consulta [Webhooks](#webhooks).

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

Carga `checkout.js` del mismo ambiente donde emitiste el token. Un token de sandbox no funciona con el script de producción.

## 1. Pide un token desde tu servidor

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

* **Permiso de la llave:** `payment_verifications:write`.
* **Firma:** como toda la API de integraciones. Consulta [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md).
* **`Idempotency-Key`:** obligatorio. Consulta [Idempotencia](https://docs.cobrix.co/api-guides/idempotency.md).

Pide un token por pedido, justo antes de mostrar el formulario.

```json Solicitud theme={null}
{
  "receiverAccountKey": "bank:3d9a7c52-…",
  "amountMinor": 150000,
  "externalReference": "PED-1001",
  "methods": ["pago_movil", "bank_transfer"],
  "expiresInSeconds": 900,
  "maxAttempts": 5
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `receiverAccountKey` | Sí | Una cuenta de `GET /payment-verifications/receiver-accounts`. Consulta [Lista las cuentas receptoras](https://docs.cobrix.co/api-guides/payment-verifications.md#1-lista-las-cuentas-receptoras). |
| `amountMinor` | Sí | Número entero JSON en unidades menores, mínimo 1. `150000` es Bs 1.500,00. |
| `externalReference` | Sí | Tu referencia del pedido, de 1 a 128 caracteres. Vuelve en cada validación hecha con el token. |
| `currency` | No | La moneda de la cuenta receptora. Si no la envías, es esa. Otra responde `422 invalid_field`. |
| `methods` | No | Los métodos que tu cliente puede usar: `pago_movil`, `bank_transfer` o `zelle`. Solo métodos de la cuenta. Por defecto, todos los de la cuenta. |
| `metadata` | No | Objeto JSON que vuelve en la validación. Hasta 2048 bytes serializado. El navegador nunca lo ve. |
| `expiresInSeconds` | No | Cuánto vive el token: de 60 a 1800 segundos. Por defecto, 900 (15 minutos). |
| `maxAttempts` | No | Cuántos intentos tiene tu cliente: de 1 a 5. Por defecto, 5. |

Cada campo acepta solo el tipo JSON de la tabla: `"150000"` o `"5"` responden `400 invalid_request`. Un campo que no está en la tabla también.

**La moneda es la de la cuenta receptora**, con la misma regla que la API de servidor. Consulta [La moneda es la de la cuenta](https://docs.cobrix.co/api-guides/payment-verifications.md#la-moneda-es-la-de-la-cuenta). El pago móvil solo existe en `VES`: en una cuenta en `USD` o `EUR`, pedir `pago_movil` responde `422 method_not_available`, y sin `methods` el token sale solo para `bank_transfer`. Lo mismo en una cuenta bancaria (`bank:…`) cuyo teléfono receptor Cobrix no conoce. Consulta [El pago móvil necesita su teléfono](https://docs.cobrix.co/api-guides/payment-verifications.md#el-pago-móvil-necesita-su-teléfono).

```json Respuesta 201 theme={null}
{
  "id": "0f8fad5b-…",
  "token": "pvt_0f8f…_secret_…",
  "expiresAt": "2026-11-17T12:15:00.000Z",
  "maxAttempts": 5,
  "methods": ["pago_movil", "bank_transfer"],
  "amountMinor": 150000,
  "currency": "VES",
  "externalReference": "PED-1001"
}
```

* **`token` solo vuelve en esta respuesta.** Ninguna otra ruta lo devuelve. Entrégaselo a tu página y no lo guardes en logs.
* **Guarda `id`.** Con él consultas o revocas el token.
* **La misma `Idempotency-Key` con el mismo cuerpo devuelve el mismo token**, aunque ya haya caducado, se haya revocado o se haya usado. Para un token nuevo, usa otra clave. El estado actual lo da [`GET /payment-verifications/tokens/{tokenId}`](#3-confirma-el-resultado-en-tu-servidor).

Este ejemplo pide el token y lo devuelve a tu página:

```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 pedirToken(pedido) {
  const url = new URL(`${baseUrl}/integrations/v1/${companyId}/payment-verifications/tokens`)
  const body = JSON.stringify({
    receiverAccountKey: pedido.cuentaReceptora, // de GET /payment-verifications/receiver-accounts
    amountMinor: pedido.totalEnCentimos, // 150000 es Bs 1.500,00
    externalReference: pedido.id // tu referencia, por ejemplo 'PED-1001'
  })
  const timestamp = Math.floor(Date.now() / 1000).toString()
  // Se firma la ruta completa, con /api
  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': `token-${pedido.id}-${pedido.intento}`, // otra clave para un token nuevo
      'Cobrix-Timestamp': timestamp,
      'Cobrix-Signature': `v1=${signature}`
    },
    body
  })
  if (!response.ok) throw new Error(`Cobrix respondió ${response.status}`)

  const emitido = await response.json()
  // Guarda emitido.id con el pedido. emitido.token va solo a tu página.
  return { tokenId: emitido.id, token: emitido.token }
}
```

### Errores al pedir el token

| HTTP | Código | Cuándo |
| - | - | - |
| `403` | `embed_disabled` | El checkout embebido no está activo para tu empresa. |
| `422` | `embed_domain_required` | Tu empresa no tiene ninguna web registrada. |
| `422` | `invalid_receiver_account` | La cuenta no existe, está inactiva o no tiene una moneda reconocida. |
| `422` | `method_not_available` | Un método de `methods` no es de esa cuenta, también `pago_movil` en una cuenta que no está en `VES` o en una cuenta bancaria sin teléfono receptor conocido. `methods` dice cuáles. |
| `422` | `invalid_field` | `currency` no es la moneda de la cuenta, o `metadata` pasa de 2048 bytes. `field` dice cuál. |

Ninguno emite un token. Los errores comunes a toda la API (`400 invalid_request`, `403 company_mismatch`, `409 idempotency_conflict`, `429 rate_limited`) están en [Errores y rate limits](https://docs.cobrix.co/resources/errors.md).

## 2. Muestra el formulario en tu página

Tu página recibe el `token` de tu servidor, por ejemplo al cargar la página de pago, y se lo pasa a `checkout.js`.

```html theme={null}
<div id="verificacion"></div>
<script src="https://sandbox.cobrix.co/checkout.js"></script>
<script>
  const verification = Cobrix.paymentVerification({
    token: 'TOKEN_DEL_PEDIDO', // el token de POST /payment-verifications/tokens
    appearance: { primaryColor: '#7a4a1f', fontFamily: 'Lora' }, // opcional
  })

  verification.mount('#verificacion')

  verification.on('payment_verification.verified', (event) => {
    // Muestra «gracias». El pedido se entrega cuando tu servidor lo confirma.
  })
</script>
```

| Método | Qué hace |
| - | - |
| `Cobrix.paymentVerification({ token, appearance? })` | Crea el formulario. Si falta el token o no tiene el formato `pvt_…_secret_…`, lanza un error. |
| `mount(selector o elemento)` | Pone el formulario dentro de la página. |
| `on(evento, fn)` | Escucha un evento. `'*'` escucha todos. |
| `destroy()` | Quita el formulario y deja de escuchar eventos. |

* El formulario pide los datos que exige el banco de la cuenta receptora. El monto no se puede cambiar: lo fijó tu servidor.
* `appearance` acepta `primaryColor` y `fontFamily`, con las mismas reglas que el [checkout embebido](https://docs.cobrix.co/api-guides/embedded-checkout.md#apariencia).
* El token completo nunca va en una URL. `checkout.js` se lo entrega solo al formulario de Cobrix.

### Eventos en el navegador

| Evento | `data.status` | Cuándo ocurre |
| - | - | - |
| `payment_verification.verified` | `verified` | El banco confirmó el pago. |
| `payment_verification.pending_review` | `pending_review` | Tu cliente envió un Zelle. Lo revisa una persona de tu empresa. |
| `payment_verification.rejected` | `rejected` | Una persona de tu empresa rechazó ese Zelle. |
| `payment_verification.failed` | `exhausted` | El token se quedó sin intentos. |
| `element.ready` | — | El formulario está listo para que tu cliente escriba. |
| `element.unavailable` | — | El formulario no se puede usar. `data.reason` es `expired` si el token caducó, o `unavailable` en los demás casos, por ejemplo un token revocado o una página que no es de una web registrada. `data.message` trae un texto. |

Los eventos de resultado traen:

```json theme={null}
{
  "type": "payment_verification.verified",
  "data": {
    "status": "verified",
    "verificationId": "0b6e7c1a-…",
    "attemptsRemaining": 4
  }
}
```

* **Un intento que no verifica no emite nada** mientras le queden intentos al token. Tu cliente ve el aviso en el formulario y puede corregir los datos.
* **`payment_verification.pending_review` solo existe en el navegador.** No hay un webhook con ese nombre.
* **Un evento puede llegar más de una vez**, por ejemplo al volver a montar un token ya cerrado. Tu código debe tolerarlo.
* **Nunca traen el motivo, el monto ni datos del pagador.**
* `verificationId` es la validación del intento. Tu página se lo puede pasar a tu servidor.

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

## 3. Confirma el resultado en tu servidor

Elige una de estas formas, o las dos:

* **Consulta el token** con `GET /payment-verifications/tokens/{tokenId}`. Es la fuente de verdad.
* **Recibe los webhooks** `payment_verification.verified`, `payment_verification.rejected` y `payment_verification.failed`. Consulta [Webhooks](#webhooks).

Para el detalle de un intento, consulta la validación con `GET /payment-verifications/{verificationId}`. Es la misma validación de la API de servidor, con `tokenId`.

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

Requiere el permiso `payment_verifications:read`.

```json Respuesta 200 theme={null}
{
  "id": "0f8fad5b-…",
  "status": "verified",
  "attemptsUsed": 2,
  "maxAttempts": 5,
  "expiresAt": "2026-11-17T12:15:00.000Z",
  "externalReference": "PED-1001",
  "verificationId": "0b6e7c1a-…",
  "lastErrorCode": "not_found"
}
```

| `status` | Qué significa | Qué hacer |
| - | - | - |
| `active` | Se puede usar. También mientras corre su último intento. | Tu cliente todavía puede usarlo. Vuelve a consultar o espera el webhook. |
| `verified` | Se cerró con un pago verificado. | Entrega el pedido. |
| `pending_review` | Se cerró con un Zelle que espera revisión. | Espera el webhook o vuelve a consultar. |
| `rejected` | Se cerró con un Zelle que una persona de tu empresa rechazó. | No entregues el pedido. |
| `exhausted` | Gastó sus intentos sin un pago verificado, o llegó a su tope de envíos. | No entregues el pedido. Si tu cliente reintenta, emite un token nuevo. |
| `expired` | Caducó. | Igual que `exhausted`. |
| `revoked` | Lo revocaste, o la llave que lo emitió ya no sirve. | Igual que `exhausted`. |

* **Un token cerrado muestra el estado actual de su validación.** Un Zelle pasa de `pending_review` a `verified` o `rejected` cuando alguien lo revisa.
* **`verificationId`** es la validación que cerró el token.
* **`lastErrorCode`** es el resultado del último intento que no verificó, por ejemplo `not_found`, `mismatch`, `ambiguous`, `already_used` o `unverifiable`. Es `rate_limited` si lo frenó el límite de la llave. El detalle está en la validación.
* **`attemptsUsed`** cuenta los intentos gastados. Un intento que se devolvió no cuenta.
* Un token de otra empresa o que no existe responde `404 embed_token_not_found`. Un `tokenId` que no es un UUID responde `400 invalid_request`.

### Revoca un token

```http theme={null}
DELETE /integrations/v1/{companyId}/payment-verifications/tokens/{tokenId}
```

Requiere el permiso `payment_verifications:write`. Responde `200` con el token, igual que el `GET`.

* Revócalo si el pedido se cancela o se paga por otra vía. El navegador recibe `401 token_revoked` desde ese momento.
* **Revocar un token cerrado no lo cambia:** sigue mostrando su resultado.
* Repetir la llamada no cambia nada.
* Si revocas la llave que emitió el token, el token también deja de servir.

## Intentos

Cada token tiene pocos intentos: `maxAttempts`, 5 como máximo.

* **Un intento se gasta cuando Cobrix tiene una respuesta sobre el pago:** el banco lo confirma, no lo encuentra o un dato no coincide, o la referencia ya se usó. Un Zelle enviado también gasta su intento.
* **Si Cobrix no pudo consultar al banco, el intento se devuelve.** Por ejemplo, porque el banco no respondió. Tu cliente puede probar de nuevo más tarde.
* **Cada token tiene además un tope de envíos:** 3 veces `maxAttempts`, 15 en un token de 5 intentos. Cuenta también los intentos devueltos. Al llegar al tope, el token queda `exhausted` aunque le queden intentos.
* **`attemptsRemaining`**, en el navegador, ya tiene en cuenta los dos límites.
* **Un Zelle se envía una sola vez por token.** El token se cierra en `pending_review`.
* **Una referencia ya usada nunca verifica**, aunque la haya usado una validación anterior del mismo pedido. Una referencia paga un solo token. Si tu cliente reintenta con un token nuevo un pedido que ya quedó verificado, lo sabes por el token anterior.

Si el token gasta sus intentos sin un pago verificado, queda `exhausted` y Cobrix envía `payment_verification.failed`.

## Límites

| Qué | Límite |
| - | - |
| Emitir tokens | 60 por minuto por llave. |
| Consultar o revocar un token | 120 por minuto por llave. |
| Envíos desde el navegador | 60 por minuto por llave emisora, sumando todos sus tokens. |
| Sesión del navegador (`GET /session`) | 60 por minuto por IP. |
| Envío del navegador (`POST`) | 10 por minuto por IP. |

* Un envío que frena el límite de la llave no llega al banco ni le cuesta un intento a tu cliente. Responde `429 rate_limited`, y `lastErrorCode` del token queda en `rate_limited`.
* Las validaciones que el banco confirma cuentan para el número de validaciones de tu empresa, igual que las de la API de servidor.

## Rutas del navegador

`checkout.js` llama a estas rutas por ti. Te sirven para entender las respuestas y los errores, o para llamarlas desde tu página con el token.

* **Base:** `/api/embed/v1/payment-verifications`, sobre el dominio de la API del ambiente. En producción: `https://api.cobrix.co/api/embed/v1/payment-verifications`.
* **Autenticación:** `Authorization: Bearer <token>`. El token nunca va en la URL.
* **Origen:** solo responden a una página de una web registrada por tu empresa.

| Método y ruta | Qué hace |
| - | - |
| `GET /session` | Lo que el formulario necesita para mostrarse. |
| `POST /` | Envía lo que escribió tu cliente. Responde `200`. |

### `GET /session`

```json Respuesta 200 theme={null}
{
  "status": "active",
  "companyName": "Tienda Demo, C.A.",
  "amountMinor": 150000,
  "currency": "VES",
  "methods": ["pago_movil", "bank_transfer"],
  "receiver": { "bankName": "Mercantil", "maskedIdentifier": "••••4821" },
  "fields": {
    "pago_movil": [
      { "name": "reference", "required": true },
      { "name": "paymentDate", "required": true },
      { "name": "payerPhone", "required": true },
      { "name": "payerBankCode", "required": true },
      { "name": "payerDocument", "required": false }
    ],
    "bank_transfer": [
      { "name": "reference", "required": true },
      { "name": "paymentDate", "required": true }
    ]
  },
  "attemptsRemaining": 5,
  "expiresAt": "2026-11-17T12:15:00.000Z",
  "verificationId": null
}
```

* **`status`:** `active`, `verified`, `pending_review`, `not_verified` (un Zelle rechazado) o `exhausted`. Con `verified`, `pending_review` o `not_verified` el token ya está cerrado y `verificationId` trae su validación.
* **`fields`** dice, por método, qué datos pide el banco de la cuenta.
* **`methods`** son los del token que la cuenta sigue aceptando. Si la cuenta dejó de existir, `methods` es `[]` y `receiver` es `null`.
* No trae tu referencia del pedido, ni `metadata`, ni la clave de la cuenta.

### `POST /`

```json Solicitud theme={null}
{
  "method": "pago_movil",
  "reference": "000123456",
  "paymentDate": "2026-11-17",
  "payerPhone": "04120000000",
  "payerBankCode": "0134",
  "payerDocument": "V12345678"
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `method` | Sí | Uno de `methods` de la sesión. |
| `reference` | Sí | La referencia del comprobante, de 1 a 64 caracteres. En Zelle, la confirmación completa. |
| `paymentDate` | Sí | El día del pago, `YYYY-MM-DD`. |
| `payerBankCode` | Según `fields` | Banco desde el que pagó tu cliente, 4 dígitos. |
| `payerPhone` | Según `fields` | Teléfono del pagador, de 1 a 32 caracteres. |
| `payerDocument` | Según `fields` | Cédula o RIF del pagador, de 1 a 32 caracteres. |
| `payerName` | No | Nombre de quien envió el Zelle, de 1 a 200 caracteres. |

Cualquier otro campo responde `400 invalid_request`, también `amountMinor`, `currency` o `receiverAccountKey`: esos los fijó tu servidor.

```json Respuesta 200 theme={null}
{
  "status": "not_verified",
  "attemptsRemaining": 4,
  "verificationId": "0b6e7c1a-…"
}
```

| `status` | Qué significa | El intento | El token |
| - | - | - | - |
| `verified` | El banco confirmó el pago. | Se gasta. | Se cierra. |
| `pending_review` | Zelle enviado. Lo revisa una persona de tu empresa. | Se gasta. | Se cierra. |
| `not_verified` | El pago no se confirmó con esos datos. | Se gasta. | Sigue abierto. |
| `unavailable` | Cobrix no pudo consultar al banco, o tu empresa alcanzó su número de validaciones. No dice nada del pago. | Se devuelve. | Sigue abierto. |

* **El navegador nunca recibe el motivo.** Decir «el monto no coincide» o «ya está usada» confirmaría que esa referencia existe. El motivo es para tu servidor: `lastErrorCode` del token y `GET /payment-verifications/{verificationId}`.
* **`verificationId`** es la validación de este intento. Es `null` cuando no se llegó a crear ninguna.
* **Un `POST` sobre un token ya cerrado** responde `200` con su resultado, sin gastar nada.

## Errores en el navegador

Todos traen `{ "error": { "code", "message" } }`.

| HTTP | Código | Cuándo | Qué hacer en tu página |
| - | - | - | - |
| `400` | `invalid_request` | El cuerpo no cumple el formato o trae un campo que no existe. `field` y `details` dicen cuál. | Corrige el envío. |
| `401` | `invalid_token` | Falta el token, está mal formado o no existe. | Pide un token nuevo a tu servidor. |
| `401` | `token_expired` | El token caducó. | Pide un token nuevo a tu servidor. |
| `401` | `token_revoked` | Revocaste el token, o la llave que lo emitió ya no sirve. | Pide un token nuevo. Si se repite, revisa la llave. |
| `403` | `origin_not_allowed` | La página no es de una web registrada por tu empresa. | Registra la web en el panel. |
| `403` | `embed_disabled` | El checkout embebido no está activo para tu empresa. | Escribe a soporte de Cobrix. |
| `409` | `token_exhausted` | El token no tiene más intentos, o llegó a su tope de envíos. | No reintentes con este token. Consulta el token en tu servidor y, si el pedido sigue sin pagar, pide uno nuevo. |
| `409` | `request_in_progress` | Otro envío con este token está en curso. | Espera un momento y reintenta. |
| `422` | `method_not_allowed` | El método no es de los que fijó el token, o la cuenta ya no lo acepta: por ejemplo, `pago_movil` en un token emitido antes del 17/11/2026 sobre una cuenta bancaria sin teléfono receptor conocido. | Usa un método de `methods` de la sesión. |
| `422` | `missing_fields` | Falta un dato que exige el banco. `fields` los trae. | Pide esos datos a tu cliente. |
| `422` | `invalid_field` | Un dato está mal escrito, por ejemplo un día que no existe o una referencia demasiado corta. `field` dice cuál. | Pide a tu cliente que lo corrija. |
| `429` | `rate_limited` | Pasaste el límite por IP o el de la llave. | Espera y reintenta. |
| `500` | `internal_error` | Falló algo de Cobrix. El mensaje es genérico. | Reintenta en unos minutos. |

**Casi ningún error gasta un intento.** Los `400`, `401`, `403`, `409`, `422` y `429` no gastan nada. Un `500` casi nunca gasta uno.

## Webhooks

Configúralos en **Integraciones › Webhooks** y verifica su firma. Consulta [Firma de webhooks](https://docs.cobrix.co/guides/webhooks/signature).

| Evento | Cuándo | `data` |
| - | - | - |
| [`payment_verification.verified`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-verified) | El banco confirmó un pago móvil o una transferencia que tu cliente envió con el token, o una persona de tu empresa aprobó su Zelle. | La validación, con `tokenId`. |
| [`payment_verification.rejected`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-rejected) | Una persona de tu empresa rechazó el Zelle que tu cliente envió con el token. | La validación, con `tokenId`. |
| [`payment_verification.failed`](https://docs.cobrix.co/guides/webhooks/events/payment-verification-failed) | El token gastó sus intentos sin un pago verificado ni un Zelle en revisión. | El pedido del token, sin datos del pagador. |

* **Un intento que no verifica no envía nada.**
* **Un Zelle enviado no envía nada** hasta que alguien de tu empresa lo revisa.
* **`payment_verification.failed` llega como mucho una vez por token, y puede no llegar:** no se envía si el token caduca con intentos sin usar o si lo revocas. Si necesitas saber cómo terminó un pedido, consulta el token.

## Seguridad

* **Tu llave no sale de tu servidor.** El navegador solo recibe el token.
* **El token vive poco y sirve para un solo pedido.** Caduca en 15 minutos por defecto, 30 como máximo.
* **El navegador no puede cambiar el pedido.** Monto, moneda, cuenta receptora, métodos, tu referencia y `metadata` los fija tu servidor al emitir el token. Si el navegador los envía, la respuesta es `400`.
* **El formulario solo funciona en tus webs registradas.** Esa comprobación frena a otras páginas, no a un programa que no es un navegador. Lo que limita un token robado es que caduca, tiene pocos intentos, sirve para un solo pedido y puedes revocarlo.
* **El navegador no recibe datos de más:** ni el motivo de un rechazo, ni tu referencia del pedido, ni `metadata`, ni la clave de la cuenta.
* **Tu servidor decide.** Entrega el pedido con el token o con el webhook firmado, nunca con el evento del navegador.

## Lista para probar en sandbox

1. Crea una llave en sandbox con `payment_verifications:write` y `payment_verifications:read`.
2. Registra la dirección de tu web de pruebas en **Configuración › Integraciones › Checkout embebido**.
3. Pide un token con `POST /payment-verifications/tokens`. Guarda `id` y entrega `token` a tu página.
4. Muestra el formulario con `checkout.js` de sandbox.
5. Configura un webhook y confirma el resultado con `GET /payment-verifications/tokens/{tokenId}`.

> [card] [Validación por API](https://docs.cobrix.co/api-guides/payment-verifications.md)
>
> Cuentas receptoras, estados, motivos y la regla de la moneda.

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


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