Skip to main content
POST
Enviar un vuelto

Authorizations

Authorization
string
header
required

Llave cbx_live creada para el partner.

Headers

Idempotency-Key
string
required

Identificador estable de la operación.

Minimum string length: 1
Cobrix-Timestamp
string
required

Segundos Unix dentro de una ventana de cinco minutos.

Pattern: ^[0-9]{10}$
Cobrix-Signature
string
required

HMAC-SHA256 de timestamp, método, ruta y cuerpo crudo.

Pattern: ^v1=[a-f0-9]{64}$
X-Request-Id
string

Identificador opcional para correlación de soporte.

Path Parameters

companyId
string<uuid>
required

Empresa vinculada a la llave.

Body

application/json

Cada campo acepta solo el tipo JSON de su esquema; Cobrix no convierte tipos.

customerId
string<uuid>
required

El cliente de la empresa en Cobrix: el companyCustomerId que devuelven POST customers/upsert y GET customers.

amountMinor
integer
required

Monto en unidades menores de currency, como número entero JSON: 500 es USD 5,00. Un texto ("500", "5.00") responde 400 invalid_request.

Required range: 1 <= x <= 999999999999999
currency
enum<string>
required

USD y EUR se convierten a bolívares con la tasa certificada de la empresa.

Available options:
VES,
USD,
EUR
bankCode
string
required

Banco del beneficiario.

Pattern: ^[0-9]{4}$
phone
string
required

Teléfono del beneficiario: 04120000000 o 584120000000.

Pattern: ^(0[0-9]{10}|58[0-9]{10})$
document
string
required

Documento del beneficiario: V, E o J y 9 dígitos.

Pattern: ^[VEJ][0-9]{9}$
concept
string
required

Concepto del pago móvil: solo letras y espacios, hasta 60.

Pattern: ^[A-Za-zÁÉÍÓÚÜÑáéíóúüñ ]{1,60}$
reason
string
required

Por qué se devuelve el dinero. Queda en la auditoría de la empresa.

Required string length: 10 - 300
accountId
string<uuid>

Cuenta de origen. Opcional si la empresa tiene una sola cuenta habilitada para vueltos.

paymentId
string<uuid>

El pago de Cobrix de ese cliente que originó el vuelto.

externalReference
string

Tu referencia. Vuelve tal cual y viaja en los webhooks.

Required string length: 1 - 100

Response

El vuelto, ya en la cola del banco

Un vuelto. También es el data de los webhooks customer_payout.*.

id
string<uuid>
required
status
enum<string>
required

processing: en camino al banco. sent: el banco lo pagó. failed: no salió dinero. unknown: pudo llegar al banco sin una respuesta clara; no lo reintentes: Cobrix lo concilia con el banco y pasa a sent o failed. sent y failed son finales.

Available options:
processing,
sent,
failed,
unknown
amountMinor
integer
required

Lo que recibe el beneficiario, en unidades menores de currency. Es el monto que se envía.

currency
string
required

La moneda del banco: VES.

sourceAmountMinor
integer
required

Lo que pediste.

sourceCurrency
string
required
rateEffectiveAt
string<date-time> | null
required

Fecha de la tasa certificada usada. null si pediste en bolívares.

customerId
string<uuid>
required
accountId
string<uuid>
required

La cuenta de origen usada.

beneficiaryMasked
string
required

Banco, últimos 4 dígitos del teléfono y documento enmascarado. El teléfono y el documento completos nunca vuelven.

externalReference
string | null
required
failureCode
string | null
required

Solo en failed o unknown. Es diagnóstico y depende del banco: no programes lógica sobre él.

bankReferenceMasked
string | null
required

Los últimos 4 dígitos de la referencia del banco, cuando la hay.

createdAt
string<date-time>
required
finishedAt
string<date-time> | null
required

Cuándo se registró su resultado. null si todavía no lo tiene.