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

# Vuelto embebido

> La persona escribe en tu web dónde recibir su vuelto y Cobrix se lo envía por pago móvil

Con el vuelto embebido, la persona que recibe el vuelto escribe su banco, su teléfono y, si no la sabes, su cédula **en tu web**. Cobrix le envía un pago móvil desde la cuenta de tu empresa y tu servidor recibe el resultado.

Tu llave nunca llega al navegador. Tu servidor pide un **token** para un vuelto y tu página usa ese token. El token vive 5 minutos y crea como mucho un vuelto.

> [!WARNING]
>
> Un vuelto mueve dinero de la cuenta de tu empresa. Antes de empezar, lee [Vueltos por API](https://docs.cobrix.co/api-guides/customer-payouts.md): los estados, los topes y los webhooks son los mismos.

## Cuándo usarlo

| | Vuelto embebido | [Vueltos por API](https://docs.cobrix.co/api-guides/customer-payouts.md) |
| - | - | - |
| Quién escribe los datos de quien recibe | La persona, 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. | Lo haces tú. |
| Moneda | Solo `VES`. | `VES`, `USD` o `EUR`. |
| El resultado | Tu servidor lo lee del token o del vuelto, o lo recibe por webhook. | En la respuesta del `POST`, en una consulta o por webhook. |

Usa el vuelto embebido cuando no tienes los datos de pago móvil de la persona y no quieres construir el formulario. Usa la API cuando tu sistema ya los tiene.

## Cómo funciona

**1. Tu servidor pide un token**

`POST /customer-payouts/tokens` con el cliente, el monto, el concepto, el motivo y tu referencia. Cobrix responde con el `token`.

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

`checkout.js` con el token. La persona escribe dónde recibir el vuelto y Cobrix lo envía al banco.

**3. Tu servidor confirma el resultado**

Consulta el token o el vuelto, o espera el webhook. Da el vuelto por pagado solo con lo que dice tu servidor.

> [!WARNING]
>
> **El evento del navegador es un aviso, no una prueba.** Da el vuelto por pagado solo cuando tu servidor lo confirma: con `customer_payout.sent` o con `status: sent` en una consulta.

## Antes de empezar

* **Cobrix activa el vuelto embebido para tu empresa.** Viene apagado: pídeselo a soporte de Cobrix. También necesita el checkout embebido activo, que lo está por defecto. Si uno de los dos está apagado, emitir un token responde `403 embed_disabled`.
* **Todo lo de [Vueltos por API](https://docs.cobrix.co/api-guides/customer-payouts.md#antes-de-empezar) aplica igual:** la cuenta de origen habilitada y los dos [topes](#topes) de tu empresa.
* Crea una llave con `customer_payouts:write` y `customer_payouts:read`. Solo el dueño de la empresa puede dar `customer_payouts:write`. Consulta [Autenticación](https://docs.cobrix.co/authentication.md#scopes).
* 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).
* Suscribe tu webhook a `customer_payout.sent`, `customer_payout.failed`, `customer_payout.unknown` y `customer_payout_token.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}/customer-payouts/tokens
```

* **Permiso de la llave:** `customer_payouts: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 vuelto, justo antes de mostrar el formulario.

```json Solicitud theme={null}
{
  "customerId": "2c7a9e1b-…",
  "amountMinor": 150000,
  "concept": "Vuelto de compra",
  "reason": "Vuelto del pedido PED-1001",
  "externalReference": "PED-1001"
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `customerId` | Sí | El `companyCustomerId` del cliente, el que devuelven `POST /customers/upsert` y `GET /customers`. |
| `amountMinor` | Sí | Número entero JSON en céntimos de bolívar, mínimo 1. `150000` es Bs 1.500,00. |
| `concept` | Sí | Concepto del pago móvil: solo letras y espacios, hasta 60. Además, lo que acepte el banco de la cuenta de origen. |
| `reason` | Sí | Por qué se devuelve el dinero, de 10 a 300 caracteres. Queda en la auditoría de tu empresa. |
| `externalReference` | Sí | Tu referencia, de 1 a 100 caracteres. Viaja en el vuelto y en los webhooks. |
| `currency` | No | Solo `VES`. El vuelto embebido nunca se convierte. |
| `accountId` | Según la empresa | Cuenta de origen. Sin él, Cobrix usa la única cuenta habilitada. Con varias cuentas habilitadas es obligatorio. |
| `document` | No | La cédula de quien recibe, si ya la sabes: `V`, `E` o `J` y 9 dígitos. Con ella, el formulario no la pide. |

Cada campo acepta solo el tipo JSON de la tabla: `"150000"` responde `400 invalid_request`. Un campo que no está en la tabla también, por ejemplo `bankCode`, `phone`, `expiresInSeconds` o `maxAttempts`: el banco y el teléfono los escribe la persona, y la vida y los intentos del token son fijos.

```json Respuesta 201 theme={null}
{
  "id": "0f8fad5b-…",
  "token": "cpt_0f8f…_secret_…",
  "expiresAt": "2026-11-17T12:05:00.000Z",
  "maxAttempts": 3,
  "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 o se haya usado. Para un token nuevo, usa otra clave.

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 apiKey = process.env.COBRIX_API_KEY

export async function pedirTokenDeVuelto(vuelto) {
  const url = new URL(`${baseUrl}/integrations/v1/${companyId}/customer-payouts/tokens`)
  const body = JSON.stringify({
    customerId: vuelto.clienteId, // el companyCustomerId del cliente
    amountMinor: vuelto.montoEnCentimos, // 150000 es Bs 1.500,00
    concept: 'Vuelto de compra',
    reason: `Vuelto del pedido ${vuelto.pedidoId}`,
    externalReference: vuelto.pedidoId // 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', apiKey).update(signed).digest('hex')

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `vuelto-${vuelto.pedidoId}-${vuelto.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

Al emitir, Cobrix comprueba lo que ya puede saber del vuelto: la cuenta de origen, el concepto, la cédula que fijaste, el cliente y el tope por vuelto. Así la persona no gasta intentos en algo que nunca saldría.

| HTTP | Código | Cuándo |
| - | - | - |
| `403` | `embed_disabled` | El vuelto embebido o el checkout embebido no está activo para tu empresa. |
| `422` | `embed_domain_required` | Tu empresa no tiene ninguna web registrada. |
| `422` | `invalid_field` | Con `field: "concept"`: el banco de la cuenta de origen no acepta ese concepto. |
| `422` | `account_required` | Tu empresa tiene varias cuentas habilitadas y no enviaste `accountId`. |
| `422` | `account_not_available` | La cuenta no está habilitada para vueltos, o tu empresa no tiene ninguna. |
| `422` | `beneficiary_document_unsupported` | El banco de la cuenta de origen no paga el tipo de la cédula que fijaste, por ejemplo un RIF. |
| `422` | `customer_not_found` | El cliente no existe en tu empresa. |
| `422` | `payout_limit_not_configured` | Tu empresa no tiene tope por vuelto. |
| `422` | `payout_limit_exceeded` | El monto supera el tope por vuelto. |
| `422` | `rate_unavailable` | El tope por vuelto está en `USD` y no hay tasa certificada para medir el monto. |
| `422` | `customer_payout_rejected` | Cualquier otro rechazo. |

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 y se lo pasa a `checkout.js`.

```html theme={null}
<div id="vuelto"></div>
<script src="https://sandbox.cobrix.co/checkout.js"></script>
<script>
  const payout = Cobrix.customerPayout({
    token: 'TOKEN_DEL_VUELTO', // el token de POST /customer-payouts/tokens
    appearance: { primaryColor: '#7a4a1f', fontFamily: 'Lora' }, // opcional
  })

  payout.mount('#vuelto')

  payout.on('customer_payout.sent', (event) => {
    // Muestra «listo». El vuelto se da por pagado cuando tu servidor lo confirma.
  })
</script>
```

| Método | Qué hace |
| - | - |
| `Cobrix.customerPayout({ token, appearance? })` | Crea el formulario. Si falta el token o no tiene el formato `cpt_…_secret_…`, lanza un error. Un token de validación (`pvt_…`) también. |
| `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 el banco y el teléfono de pago móvil. Pide la cédula solo si no la fijaste, y ofrece solo los tipos de documento que paga el banco de la cuenta de origen.
* 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.
* **El formulario nunca reenvía un vuelto por su cuenta.** Si se pierde una respuesta, vuelve a leer el token.

### Eventos en el navegador

| Evento | `data.status` | Cuándo ocurre |
| - | - | - |
| `customer_payout.processing` | `processing` | Se creó el vuelto y va al banco. |
| `customer_payout.sent` | `sent` | El banco pagó el vuelto. |
| `customer_payout.failed` | `failed` | No salió dinero. El token terminó. |
| `customer_payout.unknown` | `unknown` | El banco no dio una respuesta clara. El dinero pudo salir. |
| `customer_payout_token.failed` | `exhausted` | El token se quedó sin intentos sin crear un vuelto. |
| `element.ready` | — | El formulario está listo para que la persona 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": "customer_payout.processing",
  "data": {
    "status": "processing",
    "payoutId": "5a9e3c1d-…",
    "attemptsRemaining": 0
  }
}
```

* **Un intento que no crea el vuelto no emite nada** mientras le queden intentos al token. La persona ve el aviso en el formulario y puede corregir los datos.
* **`customer_payout.processing` solo existe en el navegador.** No hay un webhook con ese nombre.
* **El formulario sigue el vuelto unos minutos.** Mientras está en `processing`, emite `sent`, `failed` o `unknown` si llega a tiempo. Después deja de consultar. Un `unknown` no se sigue en el navegador.
* **Un evento puede llegar más de una vez**, por ejemplo al volver a montar un token ya usado. Tu código debe tolerarlo.
* **Nunca traen el monto ni datos de quien recibe.**
* `payoutId` es el vuelto. Tu página se lo puede pasar a tu servidor.

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

## 3. Confirma el resultado en tu servidor

Elige una de estas formas, o varias:

* **Consulta el token** con `GET /customer-payouts/tokens/{tokenId}`. Dice si creó un vuelto y en qué estado está.
* **Consulta el vuelto** con [`GET /customer-payouts/{payoutId}`](https://docs.cobrix.co/api-guides/customer-payouts#consultar-un-vuelto). Es un vuelto de la API como cualquier otro.
* **Recibe los webhooks.** Consulta [Webhooks](#webhooks).

```http theme={null}
GET /integrations/v1/{companyId}/customer-payouts/tokens/{tokenId}
```

Requiere el permiso `customer_payouts:read`.

```json Respuesta 200 theme={null}
{
  "id": "0f8fad5b-…",
  "status": "used",
  "attemptsUsed": 1,
  "maxAttempts": 3,
  "expiresAt": "2026-11-17T12:05:00.000Z",
  "externalReference": "PED-1001",
  "payoutId": "5a9e3c1d-…",
  "payoutStatus": "sent",
  "lastErrorCode": null
}
```

| `status` | Qué significa | Qué hacer |
| - | - | - |
| `active` | Se puede usar. También mientras corre su último intento. | Espera. Vuelve a consultar o espera el webhook. |
| `used` | Creó su vuelto. `payoutStatus` dice dónde está. | Da el vuelto por pagado solo con `payoutStatus: sent`. Con `processing` o `unknown`, espera el webhook. |
| `exhausted` | Gastó sus intentos, o llegó a su tope de envíos, sin crear un vuelto. | No salió dinero. Si la persona reintenta, emite un token nuevo. |
| `expired` | Caducó sin crear un vuelto. | Igual que `exhausted`. |
| `revoked` | Lo revocaste, o la llave que lo emitió ya no sirve. | Igual que `exhausted`. |

* **`exhausted` solo se ve mientras el token vive.** Cuando caduca, un token agotado se lee `expired`; si lo revocas, `revoked`. `attemptsUsed` y `lastErrorCode` se conservan. Trata los tres estados igual.
* **`used` no cambia después.** El token sigue en `used` aunque caduque o lo revoques. `payoutStatus` sí cambia con el vuelto.
* **`payoutStatus: failed` también cierra el token.** No salió dinero. Para otro intento, emite un token nuevo.
* **`payoutStatus: unknown` no es final.** No emitas otro vuelto: Cobrix lo concilia con el banco y llega `sent` o `failed`.
* **`lastErrorCode`** es el código del último intento que no creó un vuelto, por ejemplo `invalid_request`, `beneficiary_document_unsupported` o `payout_daily_limit_exceeded`. Es `rate_limited` si lo frenó el límite de la llave.
* **`attemptsUsed`** cuenta los intentos gastados. Un intento que se devolvió no cuenta.
* Un token de otra empresa, un token de validación o uno que no existe responde `404 embed_token_not_found`. Un `tokenId` que no es un UUID responde `400 invalid_request`.

### Buscar el vuelto sin el token

El vuelto lleva tu `externalReference`. Búscalo con [`GET /customer-payouts?externalReference=`](https://docs.cobrix.co/api-guides/customer-payouts#buscar-un-vuelto-sin-su-id). La búsqueda por `idempotencyKey` no lo encuentra: tu `Idempotency-Key` emitió el token, no el vuelto.

### Revoca un token

```http theme={null}
DELETE /integrations/v1/{companyId}/customer-payouts/tokens/{tokenId}
```

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

* Revócalo si ya no quieres que la persona pida el vuelto. El navegador recibe `401 token_revoked` desde ese momento.
* **Revocar un token `used` no lo cambia** y no detiene su vuelto.
* 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 3 intentos y vive 5 minutos. No se pueden cambiar.

* **Un token crea como mucho un vuelto.** Cuando lo crea, queda `used` y no tiene más intentos. Un envío repetido, por ejemplo un doble clic, responde el estado de ese vuelto y no crea otro.
* **Un intento se gasta si el banco de la cuenta no acepta los datos que escribió la persona.** El navegador recibe `rejected` y la persona puede corregirlos.
* **Un intento se devuelve si el vuelto no se pudo preparar por algo que no depende de esos datos**, por ejemplo el tope diario o la cuenta de origen. El navegador recibe `unavailable`.
* **Cada token tiene además un tope de envíos:** 9. 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.
* **Si el banco rechaza el vuelto ya creado, el token terminó.** El vuelto queda `failed`. Para otro intento, emite un token nuevo.

Si el token se queda sin envíos sin crear un vuelto, queda `exhausted` y Cobrix envía `customer_payout_token.failed`.

## Topes

Los vueltos embebidos son vueltos de la API: usan los mismos [topes](https://docs.cobrix.co/api-guides/customer-payouts.md#topes) de tu empresa y cuentan para el tope diario.

| Tope | Cuándo se comprueba | Si no se cumple |
| - | - | - |
| Por vuelto | Al emitir el token y al crear el vuelto. | Al emitir, `422`. Al crear el vuelto, `unavailable`. |
| Diario | Solo al crear el vuelto. Depende de lo que haya salido hasta ese momento. | `unavailable`. El intento se devuelve. |

Si el tope diario frena todos los envíos, el token llega a su tope de envíos y queda `exhausted`. `lastErrorCode` dice `payout_daily_limit_exceeded`.

## 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 | 30 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 ni un envío a la persona. Responde `429 rate_limited`, y `lastErrorCode` del token queda en `rate_limited`.

## Rutas del navegador

`checkout.js` llama a estas rutas por ti. Te sirven para entender las respuestas y los errores.

* **Base:** `/api/embed/v1/customer-payouts`, sobre el dominio de la API del ambiente. En producción: `https://api.cobrix.co/api/embed/v1/customer-payouts`.
* **Autenticación:** `Authorization: Bearer <token>`. El token nunca va en la URL. Un token de validación (`pvt_…`) responde `401 invalid_token`.
* **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ó la persona. Responde `200`. |

### `GET /session`

```json Respuesta 200 theme={null}
{
  "status": "active",
  "companyName": "Tienda Demo, C.A.",
  "amountMinor": 150000,
  "currency": "VES",
  "documentTypes": ["V", "E"],
  "document": null,
  "attemptsRemaining": 3,
  "expiresAt": "2026-11-17T12:05:00.000Z",
  "payoutId": null,
  "payoutStatus": null
}
```

* **`status`:** `active`, `exhausted` o `used`. Con `used`, `payoutId` y `payoutStatus` dicen dónde está el vuelto, y `attemptsRemaining` es 0.
* **`documentTypes`:** los tipos de documento que paga el banco de la cuenta de origen.
* **`document`:** la cédula que fijaste, enmascarada, por ejemplo `V*****78`. `null` si la escribe la persona.
* No trae tu referencia, el concepto, el motivo, el cliente ni la cuenta de origen.

### `POST /`

```json Solicitud theme={null}
{
  "bankCode": "0102",
  "phone": "04120000000",
  "document": "V012345678"
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `bankCode` | Sí | Banco de quien recibe: el código de 4 dígitos de un banco de Venezuela. |
| `phone` | Sí | Teléfono de quien recibe: `04120000000` o `584120000000`. |
| `document` | Solo si no la fijaste | Cédula de quien recibe: la letra y 9 dígitos, de un tipo de `documentTypes`. |

Cualquier otro campo responde `400 invalid_request`, también `amountMinor`, `currency`, `customerId`, `concept` o `externalReference`: esos los fijó tu servidor. `document` también, si la fijaste al emitir el token.

```json Respuesta 200 theme={null}
{
  "status": "processing",
  "attemptsRemaining": 0,
  "payoutId": "5a9e3c1d-…"
}
```

| `status` | Qué significa | El intento | El token |
| - | - | - | - |
| `processing`, `sent`, `failed` o `unknown` | Se creó el vuelto. Es su estado en ese momento. | Se gasta. | `used`. |
| `rejected` | El banco no acepta los datos que escribió la persona. No hay vuelto. | Se gasta. | Sigue abierto, si le quedan intentos. |
| `unavailable` | El vuelto no se pudo preparar ahora, por ejemplo por el tope diario. No hay vuelto. | Se devuelve. | Sigue abierto. |

* **El navegador nunca recibe el motivo de un `rejected` o un `unavailable`.** El motivo es para tu servidor: `lastErrorCode` del token.
* **`payoutId`** es el vuelto. Es `null` en `rejected` y `unavailable`.
* **Un `POST` sobre un token `used`** responde `200` con el estado actual de su vuelto, sin gastar nada ni crear otro.

## 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, trae un campo que no existe o trae `document` cuando ya la fijaste. `field` dice 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 vuelto embebido o 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 hace falta, pide uno nuevo. |
| `409` | `request_in_progress` | Otro envío con este token está en curso. | Espera un momento y vuelve a leer el token. |
| `422` | `missing_fields` | Falta `document` y no la fijaste. `fields` la trae. | Pide la cédula a la persona. |
| `422` | `beneficiary_document_unsupported` | El banco de la cuenta de origen no paga ese tipo de documento. | Pide otro documento. |
| `422` | `invalid_field` | Con `field: "bankCode"`: ese código no es de un banco que pueda recibir el vuelto. | Pide otro banco. |
| `422` | `embed_domain_required` | Tu empresa se quedó sin webs registradas. | Registra la web en el panel. |
| `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. | Vuelve a leer el token antes de reintentar. |

**Ningún error gasta un intento.** Un token `used` responde su vuelto aunque después apagues el vuelto embebido o quites tus webs.

## 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` |
| - | - | - |
| [`customer_payout.sent`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-sent) | El banco pagó el vuelto que creó el token. | El vuelto, como en `GET /customer-payouts/{payoutId}`. |
| [`customer_payout.failed`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-failed) | No salió dinero de la cuenta. | El vuelto. |
| [`customer_payout.unknown`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-unknown) | Pudo llegar al banco, sin una respuesta clara. Después llega `sent` o `failed`. | El vuelto. |
| [`customer_payout_token.failed`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-token-failed) | El token se quedó sin envíos sin crear un vuelto. | El pedido del token, sin datos de quien recibe. |

* **Los tres `customer_payout.*` son los de [Vueltos por API](https://docs.cobrix.co/api-guides/customer-payouts.md#webhooks)**, con el mismo `data`. `data` no trae el token: relaciónalo con tu `externalReference` o con `payoutId` del token.
* **Un vuelto que se creó pero no llegó a la cola del banco termina en `failed` y envía `customer_payout.failed`**, normalmente en el momento o a los 30 minutos. En la API de servidor ese caso no envía el evento.
* **Un intento que no crea el vuelto no envía nada.**
* **`customer_payout_token.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ó, consulta el token.

## Seguridad

* **Tu llave no sale de tu servidor.** El navegador solo recibe el token.
* **El token vive poco y crea como mucho un vuelto.** Caduca a los 5 minutos y tiene 3 intentos.
* **El navegador no puede cambiar el vuelto.** Monto, moneda, cliente, concepto, motivo, tu referencia, la cuenta de origen y la cédula que fijaste 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, crea un solo vuelto, respeta los topes de tu empresa y puedes revocarlo.
* **El navegador no recibe datos de más:** ni el motivo de un rechazo, ni tu referencia, ni el concepto, ni el cliente, ni la cuenta de origen.
* **Tu servidor decide.** Da el vuelto por pagado con el token, el vuelto o el webhook firmado, nunca con el evento del navegador.

> [card] [Vueltos por API](https://docs.cobrix.co/api-guides/customer-payouts.md)
>
> Estados, topes, reintentos y errores de los vueltos.

> [card] [Webhooks de vueltos](https://docs.cobrix.co/guides/webhooks/categories/customer-payouts.md)
>
> Payload de cada evento `customer_payout.*` y `customer_payout_token.failed`.


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