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

# Vueltos por API

> Envía desde tu servidor un pago móvil de la cuenta de tu empresa a una persona

Un vuelto es un **pago móvil desde la cuenta bancaria de tu empresa a una persona**, por ejemplo para devolver un pago duplicado. Tu servidor lo pide con una llamada, Cobrix lo envía al banco y te avisa el resultado por webhook.

> [!WARNING]
>
> Un vuelto mueve dinero de la cuenta de tu empresa. Lee [Reintentar sin pagar dos veces](#reintentar-sin-pagar-dos-veces) antes de programar los reintentos.

Llama siempre desde tu servidor. La llave nunca va en el navegador. Si quieres que la persona escriba su banco y su teléfono en tu web, usa el [vuelto embebido](https://docs.cobrix.co/api-guides/embedded-customer-payout.md).

## Cómo funciona

**1. Tu servidor pide el vuelto**

`POST /` con el cliente, el monto y los datos de pago móvil de quien recibe.

**2. Cobrix lo envía al banco**

Responde `201` con el vuelto, normalmente en `processing`.

**3. Tu servidor recibe el resultado**

Llega el webhook `customer_payout.sent`, `customer_payout.failed` o `customer_payout.unknown`. También puedes consultar el vuelto.

## Antes de empezar

* **Cobrix activa el servicio para tu empresa:** habilita la cuenta de origen y configura los dos [topes](#topes). Sin eso, la API responde `422` y no envía.
* **Cada vuelto se registra a un cliente de tu empresa en Cobrix.** `customerId` es su `companyCustomerId`, el que devuelven `POST /customers/upsert` y `GET /customers`.
* Crea una llave con `customer_payouts:write` y `customer_payouts:read` en **Configuración → Integraciones → Llaves API**. Solo el dueño de la empresa puede dar `customer_payouts:write`. Consulta [Autenticación](https://docs.cobrix.co/authentication.md#scopes).
* Firma cada llamada. La ruta que firmas empieza en `/api` e incluye el query string. Consulta [Firma de solicitudes](https://docs.cobrix.co/api-guides/request-signing.md).
* El `POST` lleva `Idempotency-Key`, de hasta 255 caracteres. Una más larga no se acepta: acórtala, repetirla no sirve. Consulta [Idempotencia](https://docs.cobrix.co/api-guides/idempotency.md).
* Suscribe tu webhook a `customer_payout.sent`, `customer_payout.failed` y `customer_payout.unknown`.

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}/customer-payouts` en producción. Las rutas cortas (`POST /`, `GET /{payoutId}`) 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 |
| - | - | - |
| [Enviar un vuelto](#1-envía-el-vuelto) | `customer_payouts:write` | `POST /` |
| [Consultar un vuelto](#consultar-un-vuelto) | `customer_payouts:read` | `GET /{payoutId}` |
| [Buscar un vuelto sin su `id`](#buscar-un-vuelto-sin-su-id) | `customer_payouts:read` | `GET /?idempotencyKey=` o `GET /?externalReference=` |

## 1. Envía el vuelto

```http theme={null}
POST /integrations/v1/{companyId}/customer-payouts
```

```json Solicitud theme={null}
{
  "customerId": "2c7a9e1b-4d6f-4a3c-8b5e-1f0d9c8b7a65",
  "amountMinor": 500,
  "currency": "USD",
  "bankCode": "0102",
  "phone": "04120000000",
  "document": "V012345678",
  "concept": "Vuelto de compra",
  "reason": "Pago duplicado del pedido PED-1001",
  "externalReference": "PED-1001"
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `customerId` | Sí | El `companyCustomerId` del cliente. No es el `customerId` de las respuestas de clientes. |
| `accountId` | Según la empresa | Cuenta de origen. Sin él, Cobrix usa la única cuenta habilitada. Con varias cuentas habilitadas es obligatorio. |
| `amountMinor` | Sí | Número entero JSON en unidades menores de `currency`, mínimo 1. `500` es USD 5,00. Nunca un texto ni un monto con decimales. |
| `currency` | Sí | `VES`, `USD` o `EUR`. `USD` y `EUR` se convierten a bolívares con la tasa certificada de tu empresa. |
| `bankCode` | Sí | Banco de quien recibe, 4 dígitos. |
| `phone` | Sí | Teléfono de quien recibe: `04120000000` o `584120000000`. |
| `document` | Sí | Documento de quien recibe: `V`, `E` o `J` y 9 dígitos. |
| `concept` | Sí | Concepto del pago móvil: solo letras y espacios, hasta 60. |
| `reason` | Sí | Por qué se devuelve el dinero, de 10 a 300 caracteres. Queda en la auditoría de tu empresa. |
| `paymentId` | No | El pago de Cobrix de ese cliente que originó el vuelto. |
| `externalReference` | No | Tu referencia, hasta 100 caracteres. Vuelve tal cual y viaja en los webhooks. |

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 el dinero que sale y va como número: `500`, no `"500"`, `"5.00"` ni `true`. Los demás campos son textos entre comillas, también `bankCode` y `phone`. Otro tipo responde `400 invalid_request` con su `field`: por ejemplo, `amountMinor must be an integer number`.

```json Respuesta 201 theme={null}
{
  "id": "5a9e3c1d-7f2b-4e86-b0c4-9d8a7f6e5b41",
  "status": "processing",
  "amountMinor": 437825,
  "currency": "VES",
  "sourceAmountMinor": 500,
  "sourceCurrency": "USD",
  "rateEffectiveAt": "2026-11-14T04:00:00.000Z",
  "customerId": "2c7a9e1b-4d6f-4a3c-8b5e-1f0d9c8b7a65",
  "accountId": "8d4f1a6c-3b7e-4c92-a5d0-6e1f2a3b4c5d",
  "beneficiaryMasked": "0102 · ***0000 · V*****78",
  "externalReference": "PED-1001",
  "failureCode": null,
  "bankReferenceMasked": null,
  "createdAt": "2026-11-14T10:00:00.000Z",
  "finishedAt": null
}
```

| Campo | Qué significa |
| - | - |
| `id` | El vuelto. Guárdalo para consultarlo. |
| `status` | Uno de los [cuatro estados](#estados). |
| `amountMinor`, `currency` | Lo que recibe la persona, en bolívares. Es el monto que se envía. |
| `sourceAmountMinor`, `sourceCurrency` | Lo que pediste. Iguales a los anteriores si pediste en `VES`. |
| `rateEffectiveAt` | Fecha de la tasa certificada usada. `null` si pediste en `VES`. |
| `accountId` | La cuenta de origen usada. |
| `beneficiaryMasked` | Banco, últimos 4 dígitos del teléfono y documento enmascarado. El teléfono y el documento completos nunca vuelven. |
| `failureCode` | Solo en `failed` o `unknown`. Es diagnóstico y depende del banco: no programes lógica sobre él. |
| `bankReferenceMasked` | Los últimos 4 dígitos de la referencia del banco, cuando la hay. |
| `finishedAt` | Cuándo se registró su resultado. `null` si todavía no lo tiene. |

Si la tasa cambia entre preparar y enviar, Cobrix cancela ese vuelto antes de responder y devuelve `409 rate_changed`: no sale dinero y no cuenta para el tope diario. Repite con otra `Idempotency-Key`.

## Estados

| `status` | Qué significa | ¿Salió dinero? | ¿Es final? |
| - | - | - | - |
| `processing` | En camino al banco. | Todavía no se sabe | No |
| `sent` | El banco pagó el vuelto. | Sí | Sí |
| `failed` | El banco lo rechazó, nunca llegó al banco o se canceló antes de salir. | No | Sí |
| `unknown` | Pudo llegar al banco, pero no hay una respuesta clara. | No se sabe | No |

* **`sent` y `failed` son finales.** No cambian después.
* **`unknown` no es final.** Cobrix lo concilia con el banco y pasa a `sent` o `failed`. Llega el webhook de ese resultado.

> [!WARNING]
>
> No reintentes un vuelto en `unknown` ni en `processing` con otra `Idempotency-Key`: puedes pagar dos veces.

## Topes

Cobrix configura dos topes para tu empresa, en la misma moneda (`USD` o `VES`).

| Tope | Qué limita | Si falta | Si se supera |
| - | - | - | - |
| Por vuelto | El monto de cada vuelto. | `422 payout_limit_not_configured` | `422 payout_limit_exceeded` |
| Diario | La suma de los vueltos pedidos por la API en el día. | `422 payout_daily_limit_not_configured` | `422 payout_daily_limit_exceeded` |

* **Sin tope diario, la API no envía.** Tampoco sin tope por vuelto.
* **El día es el de Venezuela**, de 00:00 a 23:59 (America/Caracas).
* **Cuentan para el tope diario** los vueltos de la API en `processing`, `sent` y `unknown`. Los `failed` no cuentan.
* Los vueltos que tu empresa hace desde el panel de Cobrix no cuentan para el tope diario.
* Si la moneda del vuelto es otra, Cobrix lo mide con la tasa certificada.
* Dos `POST` simultáneos no pasan los dos si juntos superan el tope diario.

## Consultar un vuelto

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

Devuelve el vuelto con su estado actual. Un vuelto hecho desde el panel de Cobrix, de otra empresa o que no existe responde `404 customer_payout_not_found`.

## Buscar un vuelto sin su id

Para cuando se perdió la respuesta del `POST`. Envía **exactamente uno** de los dos filtros. Con ninguno o con los dos responde `400 invalid_filter`.

```http theme={null}
GET /integrations/v1/{companyId}/customer-payouts?idempotencyKey=vuelto-PED-1001
```

| Filtro | Qué encuentra |
| - | - |
| `idempotencyKey` | El vuelto que **tu llave** creó con esa `Idempotency-Key`: 0 o 1. Otra llave con la misma clave no lo ve. |
| `externalReference` | Los vueltos de la API de tu empresa con esa referencia, de cualquier llave, del más nuevo al más viejo. Hasta 50. |

```json Respuesta 200 theme={null}
{
  "data": [
    {
      "id": "5a9e3c1d-7f2b-4e86-b0c4-9d8a7f6e5b41",
      "status": "sent",
      "amountMinor": 437825,
      "currency": "VES",
      "sourceAmountMinor": 500,
      "sourceCurrency": "USD",
      "rateEffectiveAt": "2026-11-14T04:00:00.000Z",
      "customerId": "2c7a9e1b-4d6f-4a3c-8b5e-1f0d9c8b7a65",
      "accountId": "8d4f1a6c-3b7e-4c92-a5d0-6e1f2a3b4c5d",
      "beneficiaryMasked": "0102 · ***0000 · V*****78",
      "externalReference": "PED-1001",
      "failureCode": null,
      "bankReferenceMasked": "********6789",
      "createdAt": "2026-11-14T10:00:00.000Z",
      "finishedAt": "2026-11-14T10:00:07.000Z"
    }
  ]
}
```

Una lista vacía significa que con ese filtro no hay ningún vuelto.

## Reintentar sin pagar dos veces

La regla es una: **no cambies de `Idempotency-Key` hasta confirmar que el vuelto quedó `failed`**.

La misma clave con el mismo cuerpo devuelve la respuesta guardada y no envía dinero otra vez. Esa respuesta es la del momento del `POST`: el estado actual lo da `GET /{payoutId}`.

| 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, también si dos reintentos de una llamada fallida llegan a la vez. Dura como mucho 30 segundos. Repite con la misma clave. Si esa llamada tarda más de 30 segundos, o se cortó en Cobrix, la clave pasa a responder `409 idempotency_result_ambiguous`. |
| `409 idempotency_result_ambiguous` | Deja de reintentar con esa clave. Busca el vuelto con `GET /?idempotencyKey=`. |
| `409 rate_changed` o `409 idempotency_key_expired` | No salió dinero. Repite con una clave nueva. |
| `422` | No salió dinero. Corrige la causa y envía con una clave nueva. La misma clave con otro cuerpo responde `409 idempotency_conflict`. |

Si un timeout, un `5xx` o un `409 idempotency_result_ambiguous` te deja sin respuesta, busca el vuelto con `GET /?idempotencyKey=` y esa clave antes de usar una nueva:

| Resultado de la búsqueda | Qué hacer |
| - | - |
| Lista vacía | Con esa clave no se creó ningún vuelto. Puedes usar otra. |
| `failed` | No salió dinero. Puedes usar otra. |
| `processing` | No uses otra clave. Consulta de nuevo hasta que cambie. Si Cobrix no llegó a ponerlo en la cola del banco, pasa a `failed` a los 30 minutos, sin webhook. |
| `sent` o `unknown` | No uses otra clave. En `unknown`, espera el webhook o consulta de nuevo. |

Dos llaves de la misma empresa nunca comparten claves.

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

Un `4xx` no envía dinero, con dos excepciones: tras `409 request_in_progress` o `409 idempotency_result_ambiguous`, el vuelto pudo haberse creado con esa clave. [Búscalo](#reintentar-sin-pagar-dos-veces) antes de usar otra.

| HTTP | Código | Cuándo |
| - | - | - |
| `400` | `missing_idempotency_key` | Falta `Idempotency-Key` en el `POST`. |
| `400` | `invalid_filter` | En la búsqueda, no enviaste ningún filtro o enviaste los dos. |
| `400` | `invalid_request` | El cuerpo, un filtro o el `payoutId` 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. |
| `404` | `customer_payout_not_found` | El vuelto no existe, es de otra empresa o no se pidió por la API. |
| `409` | `rate_changed` | La tasa cambió antes de enviar y Cobrix canceló el vuelto. |
| `409` | `idempotency_key_expired` | El vuelto preparado con esa clave venció. |
| `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. Busca el vuelto antes de usar otra. |
| `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` | `payout_limit_not_configured` | Tu empresa no tiene tope por vuelto. |
| `422` | `payout_limit_exceeded` | El monto supera el tope por vuelto. |
| `422` | `payout_daily_limit_not_configured` | Tu empresa no tiene tope diario. |
| `422` | `payout_daily_limit_exceeded` | Con este vuelto, lo enviado hoy por la API superaría el tope diario. |
| `422` | `beneficiary_document_unsupported` | El banco de la cuenta de origen no paga ese tipo de documento, por ejemplo un RIF. |
| `422` | `invalid_request` | El formato es correcto, pero el banco no acepta los datos de quien recibe, el concepto o el motivo. |
| `422` | `invalid_amount` | El monto no es válido una vez convertido a bolívares. |
| `422` | `rate_unavailable` | No hay tasa certificada para convertir esa moneda. |
| `422` | `customer_not_found` | El cliente no existe en tu empresa. |
| `422` | `payment_not_found` | El `paymentId` no existe o no es de ese cliente. |
| `422` | `customer_payout_rejected` | Cualquier otro rechazo. |
| `429` | `rate_limited` | Pasaste el [límite](#límites) de la llave. |
| `500` | `internal_error` | Falló algo de Cobrix. En el `POST`, no se sabe si el vuelto se creó: repite con la misma clave y no uses otra sin [buscar antes el vuelto](#reintentar-sin-pagar-dos-veces). En una consulta, repítela en unos minutos. |

`invalid_request` sale con dos estados HTTP. Con `400` es un error de formato: un campo que falta, con otro tipo JSON, con formato incorrecto o que no está en esta página, un filtro que no existe o un `payoutId` que no es un UUID. `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. Con `422` es un rechazo del banco y no trae `field`.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "bankCode must match /^\\d{4}$/ regular expression",
    "field": "bankCode",
    "details": [
      {
        "field": "bankCode",
        "message": "bankCode must match /^\\d{4}$/ regular expression"
      }
    ]
  }
}
```

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. El mensaje es siempre el mismo y no trae detalles internos: `Something failed on our side. Try again in a few minutes; if it keeps failing, contact Cobrix support.` Pide reintentar en unos minutos; en un `POST`, hazlo con la misma clave. Si envías `X-Request-Id`, vuelve como `requestId` en los errores de esta API: dáselo a soporte. La excepción son los `409` de idempotencia (`idempotency_conflict`, `request_in_progress` e `idempotency_result_ambiguous`), donde puede no venir.

## Webhooks

Solo los vueltos pedidos por la API envían estos eventos, una vez por evento y vuelto. Los del [vuelto embebido](https://docs.cobrix.co/api-guides/embedded-customer-payout.md#webhooks) también. Configúralos en **Integraciones › Webhooks** y verifica su firma. Consulta [Firma de webhooks](https://docs.cobrix.co/guides/webhooks/signature).

| Evento | Qué confirma |
| - | - |
| [`customer_payout.sent`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-sent) | El banco pagó el vuelto. Es final. |
| [`customer_payout.failed`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-failed) | No salió dinero de la cuenta. Es final. |
| [`customer_payout.unknown`](https://docs.cobrix.co/guides/webhooks/events/customer-payout-unknown) | No confirma nada: pudo llegar al banco. Después llega `sent` o `failed`. |

`data` es el mismo vuelto que devuelve `GET /{payoutId}`. `processing` no envía webhook.

> [!WARNING]
>
> Da el vuelto por pagado solo con `customer_payout.sent` o con `status: sent` en una consulta desde tu servidor.

## Límites

* **Vueltos por llave:** 30 `POST` por minuto. Las consultas y las búsquedas, 120 por minuto por ruta.
* **Dinero:** los dos [topes](#topes) de tu empresa.
* **Datos mínimos:** las respuestas y los webhooks nunca traen el teléfono ni el documento completos.
* **Cada vuelto es de su empresa.** Un `id` ajeno responde `404`.

## Qué no hace esta API

* No lista vueltos por fecha: la búsqueda pide tu `Idempotency-Key` o tu referencia.
* No lista las cuentas de origen. El `accountId` usado viene en cada vuelto.
* No cancela ni concilia un vuelto.
* No lee ni envía los vueltos que tu empresa hace desde el panel de Cobrix.

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

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


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