curl --request POST \
--url https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts \
--header 'Authorization: Bearer <token>' \
--header 'Cobrix-Signature: <cobrix-signature>' \
--header 'Cobrix-Timestamp: <cobrix-timestamp>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"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"
}
'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'Cobrix-Timestamp': '<cobrix-timestamp>',
'Cobrix-Signature': '<cobrix-signature>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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'
})
};
fetch('https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts"
payload = {
"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"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Cobrix-Timestamp": "<cobrix-timestamp>",
"Cobrix-Signature": "<cobrix-signature>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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
}{
"error": {
"code": "invalid_request",
"message": "amountMinor must not be less than 1",
"field": "amountMinor",
"details": [
{
"field": "amountMinor",
"message": "amountMinor must not be less than 1"
}
],
"requestId": "req-1001"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing or invalid.",
"requestId": "req-1001"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "payout_daily_limit_exceeded",
"message": "The amount would exceed the company daily limit for API payouts (Venezuela day).",
"requestId": "req-1001"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "internal_error",
"message": "Something failed on our side. Try again in a few minutes; if it keeps failing, contact Cobrix support.",
"requestId": "req-1001"
}
}Enviar un vuelto
Crea el vuelto y lo envía al banco: un pago móvil desde la cuenta de la empresa al beneficiario. Responde 201 con el vuelto, normalmente en processing. El resultado llega por webhook o con GET. La misma Idempotency-Key con el mismo cuerpo devuelve la respuesta guardada y no envía dinero otra vez. No cambies de clave hasta confirmar que el vuelto quedó failed. El límite es 30 solicitudes por minuto por llave.
curl --request POST \
--url https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts \
--header 'Authorization: Bearer <token>' \
--header 'Cobrix-Signature: <cobrix-signature>' \
--header 'Cobrix-Timestamp: <cobrix-timestamp>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"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"
}
'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'Cobrix-Timestamp': '<cobrix-timestamp>',
'Cobrix-Signature': '<cobrix-signature>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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'
})
};
fetch('https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.cobrix.co/api/integrations/v1/{companyId}/customer-payouts"
payload = {
"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"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Cobrix-Timestamp": "<cobrix-timestamp>",
"Cobrix-Signature": "<cobrix-signature>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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
}{
"error": {
"code": "invalid_request",
"message": "amountMinor must not be less than 1",
"field": "amountMinor",
"details": [
{
"field": "amountMinor",
"message": "amountMinor must not be less than 1"
}
],
"requestId": "req-1001"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing or invalid.",
"requestId": "req-1001"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "payout_daily_limit_exceeded",
"message": "The amount would exceed the company daily limit for API payouts (Venezuela day).",
"requestId": "req-1001"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"requestId": "<string>"
}
}{
"error": {
"code": "internal_error",
"message": "Something failed on our side. Try again in a few minutes; if it keeps failing, contact Cobrix support.",
"requestId": "req-1001"
}
}Headers
Body
Cada campo acepta solo el tipo JSON de su esquema; Cobrix no convierte tipos.
Response
El vuelto, ya en la cola del banco
Un vuelto. También es el data de los webhooks customer_payout.*.
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.
processing, sent, failed, unknown 
