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
422y no envía. - Cada vuelto se registra a un cliente de tu empresa en Cobrix.
customerIdes sucompanyCustomerId, el que devuelvenPOST /customers/upsertyGET /customers. - Crea una llave con
customer_payouts:writeycustomer_payouts:readen Configuración → Integraciones → Llaves API. Solo el dueño de la empresa puede darcustomer_payouts:write. Consulta Autenticación. - Firma cada llamada. La ruta que firmas empieza en
/apie incluye el query string. Consulta Firma de solicitudes. - El
POSTllevaIdempotency-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.failedycustomer_payout.unknown.
/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
sentyfailedson finales. No cambian después.unknownno es final. Cobrix lo concilia con el banco y pasa asentofailed. Llega el webhook de ese resultado.
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,sentyunknown. Losfailedno 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
POSTsimultáneos no pasan los dos si juntos superan el tope diario.
Consultar un vuelto
404 customer_payout_not_found.
Buscar un vuelto sin su id
Para cuando se perdió la respuesta delPOST. Envía exactamente uno de los dos filtros. Con ninguno o con los dos responde 400 invalid_filter.
Respuesta 200
Reintentar sin pagar dos veces
La regla es una: no cambies deIdempotency-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.
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.
Límites
- Vueltos por llave: 30
POSTpor 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
idajeno responde404.
Qué no hace esta API
- No lista vueltos por fecha: la búsqueda pide tu
Idempotency-Keyo tu referencia. - No lista las cuentas de origen. El
accountIdusado 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.
