Cuándo usarlo
Usa el vuelto embebido cuando no tienes los datos de pago móvil de la persona y no quieres construir el formulario. Usa la API cuando tu sistema ya los tiene.
Cómo funciona
1
Tu servidor pide un token
POST /customer-payouts/tokens con el cliente, el monto, el concepto, el motivo y tu referencia. Cobrix responde con el token.2
Tu página muestra el formulario
checkout.js con el token. La persona escribe dónde recibir el vuelto y Cobrix lo envía al banco.3
Tu servidor confirma el resultado
Consulta el token o el vuelto, o espera el webhook. Da el vuelto por pagado solo con lo que dice tu servidor.
Antes de empezar
- Cobrix activa el vuelto embebido para tu empresa. Viene apagado: pídeselo a soporte de Cobrix. También necesita el checkout embebido activo, que lo está por defecto. Si uno de los dos está apagado, emitir un token responde
403 embed_disabled. - Todo lo de Vueltos por API aplica igual: la cuenta de origen habilitada y los dos topes de tu empresa.
- Crea una llave con
customer_payouts:writeycustomer_payouts:read. Solo el dueño de la empresa puede darcustomer_payouts:write. Consulta Autenticación. - Registra tus webs en Configuración › Integraciones › Checkout embebido. El formulario solo funciona en esas webs, y sin ninguna emitir un token responde
422 embed_domain_required. Las reglas de la dirección están en Registra tu web. - Suscribe tu webhook a
customer_payout.sent,customer_payout.failed,customer_payout.unknownycustomer_payout_token.failed. Consulta Webhooks.
URLs por ambiente
Carga
checkout.js del mismo ambiente donde emitiste el token. Un token de sandbox no funciona con el script de producción.
1. Pide un token desde tu servidor
- Permiso de la llave:
customer_payouts:write. - Firma: como toda la API de integraciones. Consulta Firma de solicitudes.
Idempotency-Key: obligatorio. Consulta Idempotencia.
Solicitud
Cada campo acepta solo el tipo JSON de la tabla:
"150000" responde 400 invalid_request. Un campo que no está en la tabla también, por ejemplo bankCode, phone, expiresInSeconds o maxAttempts: el banco y el teléfono los escribe la persona, y la vida y los intentos del token son fijos.
Respuesta 201
tokensolo vuelve en esta respuesta. Ninguna otra ruta lo devuelve. Entrégaselo a tu página y no lo guardes en logs.- Guarda
id. Con él consultas o revocas el token. - La misma
Idempotency-Keycon el mismo cuerpo devuelve el mismo token, aunque ya haya caducado o se haya usado. Para un token nuevo, usa otra clave.
Node.js (tu servidor)
Errores al pedir el token
Al emitir, Cobrix comprueba lo que ya puede saber del vuelto: la cuenta de origen, el concepto, la cédula que fijaste, el cliente y el tope por vuelto. Así la persona no gasta intentos en algo que nunca saldría.
Ninguno emite un token. Los errores comunes a toda la API (
400 invalid_request, 403 company_mismatch, 409 idempotency_conflict, 429 rate_limited) están en Errores y rate limits.
2. Muestra el formulario en tu página
Tu página recibe eltoken de tu servidor y se lo pasa a checkout.js.
- El formulario pide el banco y el teléfono de pago móvil. Pide la cédula solo si no la fijaste, y ofrece solo los tipos de documento que paga el banco de la cuenta de origen.
- El monto no se puede cambiar: lo fijó tu servidor.
appearanceaceptaprimaryColoryfontFamily, con las mismas reglas que el checkout embebido.- El token completo nunca va en una URL.
checkout.jsse lo entrega solo al formulario de Cobrix. - El formulario nunca reenvía un vuelto por su cuenta. Si se pierde una respuesta, vuelve a leer el token.
Eventos en el navegador
Los eventos de resultado traen:
- Un intento que no crea el vuelto no emite nada mientras le queden intentos al token. La persona ve el aviso en el formulario y puede corregir los datos.
customer_payout.processingsolo existe en el navegador. No hay un webhook con ese nombre.- El formulario sigue el vuelto unos minutos. Mientras está en
processing, emitesent,failedounknownsi llega a tiempo. Después deja de consultar. Ununknownno se sigue en el navegador. - Un evento puede llegar más de una vez, por ejemplo al volver a montar un token ya usado. Tu código debe tolerarlo.
- Nunca traen el monto ni datos de quien recibe.
payoutIdes el vuelto. Tu página se lo puede pasar a tu servidor.
3. Confirma el resultado en tu servidor
Elige una de estas formas, o varias:- Consulta el token con
GET /customer-payouts/tokens/{tokenId}. Dice si creó un vuelto y en qué estado está. - Consulta el vuelto con
GET /customer-payouts/{payoutId}. Es un vuelto de la API como cualquier otro. - Recibe los webhooks. Consulta Webhooks.
customer_payouts:read.
Respuesta 200
exhaustedsolo se ve mientras el token vive. Cuando caduca, un token agotado se leeexpired; si lo revocas,revoked.attemptsUsedylastErrorCodese conservan. Trata los tres estados igual.usedno cambia después. El token sigue enusedaunque caduque o lo revoques.payoutStatussí cambia con el vuelto.payoutStatus: failedtambién cierra el token. No salió dinero. Para otro intento, emite un token nuevo.payoutStatus: unknownno es final. No emitas otro vuelto: Cobrix lo concilia con el banco y llegasentofailed.lastErrorCodees el código del último intento que no creó un vuelto, por ejemploinvalid_request,beneficiary_document_unsupportedopayout_daily_limit_exceeded. Esrate_limitedsi lo frenó el límite de la llave.attemptsUsedcuenta los intentos gastados. Un intento que se devolvió no cuenta.- Un token de otra empresa, un token de validación o uno que no existe responde
404 embed_token_not_found. UntokenIdque no es un UUID responde400 invalid_request.
Buscar el vuelto sin el token
El vuelto lleva tuexternalReference. Búscalo con GET /customer-payouts?externalReference=. La búsqueda por idempotencyKey no lo encuentra: tu Idempotency-Key emitió el token, no el vuelto.
Revoca un token
customer_payouts:write. Responde 200 con el token, igual que el GET.
- Revócalo si ya no quieres que la persona pida el vuelto. El navegador recibe
401 token_revokeddesde ese momento. - Revocar un token
usedno lo cambia y no detiene su vuelto. - Repetir la llamada no cambia nada.
- Si revocas la llave que emitió el token, el token también deja de servir.
Intentos
Cada token tiene 3 intentos y vive 5 minutos. No se pueden cambiar.- Un token crea como mucho un vuelto. Cuando lo crea, queda
usedy no tiene más intentos. Un envío repetido, por ejemplo un doble clic, responde el estado de ese vuelto y no crea otro. - Un intento se gasta si el banco de la cuenta no acepta los datos que escribió la persona. El navegador recibe
rejectedy la persona puede corregirlos. - Un intento se devuelve si el vuelto no se pudo preparar por algo que no depende de esos datos, por ejemplo el tope diario o la cuenta de origen. El navegador recibe
unavailable. - Cada token tiene además un tope de envíos: 9. Cuenta también los intentos devueltos. Al llegar al tope, el token queda
exhaustedaunque le queden intentos. attemptsRemaining, en el navegador, ya tiene en cuenta los dos límites.- Si el banco rechaza el vuelto ya creado, el token terminó. El vuelto queda
failed. Para otro intento, emite un token nuevo.
exhausted y Cobrix envía customer_payout_token.failed.
Topes
Los vueltos embebidos son vueltos de la API: usan los mismos topes de tu empresa y cuentan para el tope diario.
Si el tope diario frena todos los envíos, el token llega a su tope de envíos y queda
exhausted. lastErrorCode dice payout_daily_limit_exceeded.
Límites
Un envío que frena el límite de la llave no llega al banco ni le cuesta un intento ni un envío a la persona. Responde
429 rate_limited, y lastErrorCode del token queda en rate_limited.
Rutas del navegador
checkout.js llama a estas rutas por ti. Te sirven para entender las respuestas y los errores.
- Base:
/api/embed/v1/customer-payouts, sobre el dominio de la API del ambiente. En producción:https://api.cobrix.co/api/embed/v1/customer-payouts. - Autenticación:
Authorization: Bearer <token>. El token nunca va en la URL. Un token de validación (pvt_…) responde401 invalid_token. - Origen: solo responden a una página de una web registrada por tu empresa.
GET /session
Respuesta 200
status:active,exhaustedoused. Conused,payoutIdypayoutStatusdicen dónde está el vuelto, yattemptsRemaininges 0.documentTypes: los tipos de documento que paga el banco de la cuenta de origen.document: la cédula que fijaste, enmascarada, por ejemploV*****78.nullsi la escribe la persona.- No trae tu referencia, el concepto, el motivo, el cliente ni la cuenta de origen.
POST /
Solicitud
Cualquier otro campo responde
400 invalid_request, también amountMinor, currency, customerId, concept o externalReference: esos los fijó tu servidor. document también, si la fijaste al emitir el token.
Respuesta 200
- El navegador nunca recibe el motivo de un
rejectedo ununavailable. El motivo es para tu servidor:lastErrorCodedel token. payoutIdes el vuelto. Esnullenrejectedyunavailable.- Un
POSTsobre un tokenusedresponde200con el estado actual de su vuelto, sin gastar nada ni crear otro.
Errores en el navegador
Todos traen{ "error": { "code", "message" } }.
Ningún error gasta un intento. Un token
used responde su vuelto aunque después apagues el vuelto embebido o quites tus webs.
Webhooks
Configúralos en Integraciones › Webhooks y verifica su firma. Consulta Firma de webhooks.- Los tres
customer_payout.*son los de Vueltos por API, con el mismodata.datano trae el token: relaciónalo con tuexternalReferenceo conpayoutIddel token. - Un vuelto que se creó pero no llegó a la cola del banco termina en
failedy envíacustomer_payout.failed, normalmente en el momento o a los 30 minutos. En la API de servidor ese caso no envía el evento. - Un intento que no crea el vuelto no envía nada.
customer_payout_token.failedllega como mucho una vez por token, y puede no llegar: no se envía si el token caduca con intentos sin usar o si lo revocas. Si necesitas saber cómo terminó, consulta el token.
Seguridad
- Tu llave no sale de tu servidor. El navegador solo recibe el token.
- El token vive poco y crea como mucho un vuelto. Caduca a los 5 minutos y tiene 3 intentos.
- El navegador no puede cambiar el vuelto. Monto, moneda, cliente, concepto, motivo, tu referencia, la cuenta de origen y la cédula que fijaste los fija tu servidor al emitir el token. Si el navegador los envía, la respuesta es
400. - El formulario solo funciona en tus webs registradas. Esa comprobación frena a otras páginas, no a un programa que no es un navegador. Lo que limita un token robado es que caduca, tiene pocos intentos, crea un solo vuelto, respeta los topes de tu empresa y puedes revocarlo.
- El navegador no recibe datos de más: ni el motivo de un rechazo, ni tu referencia, ni el concepto, ni el cliente, ni la cuenta de origen.
- Tu servidor decide. Da el vuelto por pagado con el token, el vuelto o el webhook firmado, nunca con el evento del navegador.
Vueltos por API
Estados, topes, reintentos y errores de los vueltos.
Webhooks de vueltos
Payload de cada evento
customer_payout.* y customer_payout_token.failed.
