Skip to main content
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.
Un vuelto mueve dinero de la cuenta de tu empresa. Lee 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.

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. 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.
  • Firma cada llamada. La ruta que firmas empieza en /api e incluye el query string. Consulta Firma de solicitudes.
  • El POST lleva Idempotency-Key, de hasta 255 caracteres. Una más larga no se acepta: acórtala, repetirla no sirve. Consulta Idempotencia.
  • 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, 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.

1. Envía el vuelto

Solicitud
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.
Respuesta 201
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

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

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.
Respuesta 200
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}. 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: 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. 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 antes de usar otra. 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.
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 también. Configúralos en Integraciones › Webhooks y verifica su firma. Consulta Firma de webhooks. data es el mismo vuelto que devuelve GET /{payoutId}. processing no envía webhook.
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 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.

Referencia de la API

Campos, respuestas y códigos de cada ruta.

Webhooks de vueltos

Payload de customer_payout.sent, customer_payout.failed y customer_payout.unknown.