Skip to main content
Con el vuelto embebido, la persona que recibe el vuelto escribe su banco, su teléfono y, si no la sabes, su cédula en tu web. Cobrix le envía un pago móvil desde la cuenta de tu empresa y tu servidor recibe el resultado. Tu llave nunca llega al navegador. Tu servidor pide un token para un vuelto y tu página usa ese token. El token vive 5 minutos y crea como mucho un vuelto.
Un vuelto mueve dinero de la cuenta de tu empresa. Antes de empezar, lee Vueltos por API: los estados, los topes y los webhooks son los mismos.

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.
El evento del navegador es un aviso, no una prueba. Da el vuelto por pagado solo cuando tu servidor lo confirma: con customer_payout.sent o con status: sent en una consulta.

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:write y customer_payouts:read. Solo el dueño de la empresa puede dar customer_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.unknown y customer_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.
Pide un token por vuelto, justo antes de mostrar el formulario.
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
  • token solo 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-Key con el mismo cuerpo devuelve el mismo token, aunque ya haya caducado o se haya usado. Para un token nuevo, usa otra clave.
Este ejemplo pide el token y lo devuelve a tu página:
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 el token 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.
  • appearance acepta primaryColor y fontFamily, con las mismas reglas que el checkout embebido.
  • El token completo nunca va en una URL. checkout.js se 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.processing solo existe en el navegador. No hay un webhook con ese nombre.
  • El formulario sigue el vuelto unos minutos. Mientras está en processing, emite sent, failed o unknown si llega a tiempo. Después deja de consultar. Un unknown no 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.
  • payoutId es el vuelto. Tu página se lo puede pasar a tu servidor.
No des el vuelto por pagado con estos eventos. Ocurren en el navegador: pueden no llegar si la persona cierra la pestaña y cualquiera puede alterarlos desde su equipo. Úsalos solo para cambiar lo que ve la persona.

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.
Requiere el permiso customer_payouts:read.
Respuesta 200
  • exhausted solo se ve mientras el token vive. Cuando caduca, un token agotado se lee expired; si lo revocas, revoked. attemptsUsed y lastErrorCode se conservan. Trata los tres estados igual.
  • used no cambia después. El token sigue en used aunque caduque o lo revoques. payoutStatus sí cambia con el vuelto.
  • payoutStatus: failed también cierra el token. No salió dinero. Para otro intento, emite un token nuevo.
  • payoutStatus: unknown no es final. No emitas otro vuelto: Cobrix lo concilia con el banco y llega sent o failed.
  • lastErrorCode es el código del último intento que no creó un vuelto, por ejemplo invalid_request, beneficiary_document_unsupported o payout_daily_limit_exceeded. Es rate_limited si lo frenó el límite de la llave.
  • attemptsUsed cuenta 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. Un tokenId que no es un UUID responde 400 invalid_request.

Buscar el vuelto sin el token

El vuelto lleva tu externalReference. 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

Requiere el permiso 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_revoked desde ese momento.
  • Revocar un token used no 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 used y 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 rejected y 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 exhausted aunque 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.
Si el token se queda sin envíos sin crear un vuelto, queda 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_…) responde 401 invalid_token.
  • Origen: solo responden a una página de una web registrada por tu empresa.

GET /session

Respuesta 200
  • status: active, exhausted o used. Con used, payoutId y payoutStatus dicen dónde está el vuelto, y attemptsRemaining es 0.
  • documentTypes: los tipos de documento que paga el banco de la cuenta de origen.
  • document: la cédula que fijaste, enmascarada, por ejemplo V*****78. null si 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 rejected o un unavailable. El motivo es para tu servidor: lastErrorCode del token.
  • payoutId es el vuelto. Es null en rejected y unavailable.
  • Un POST sobre un token used responde 200 con 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 mismo data. data no trae el token: relaciónalo con tu externalReference o con payoutId del token.
  • Un vuelto que se creó pero no llegó a la cola del banco termina en failed y envía customer_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.failed llega 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.