Skip to main content
Con la validación embebida, tu cliente escribe la referencia de su pago móvil, transferencia o Zelle en tu web. Cobrix la valida con el banco y tu servidor recibe el resultado. Tu llave nunca llega al navegador. Tu servidor pide un token para un pedido y tu página usa ese token. El token vive pocos minutos y sirve para un solo pedido.

Cuándo usarla

Usa la validación embebida cuando tu cliente está en tu web y no quieres construir el formulario. Usa la API cuando tu sistema ya tiene los datos del pago.

Cómo funciona

1

Tu servidor pide un token

POST /payment-verifications/tokens con la cuenta receptora, el monto y tu referencia del pedido. Cobrix responde con el token.
2

Tu página muestra el formulario

checkout.js con el token. Tu cliente escribe la referencia y Cobrix la valida con el banco.
3

Tu servidor confirma el resultado

Consulta el token o espera el webhook. Entrega el pedido solo con lo que dice tu servidor.
El evento del navegador es un aviso, no una prueba. Entrega el pedido solo cuando tu servidor confirma el resultado: consultando el token o con el webhook firmado.

Antes de empezar

  • Crea una llave con payment_verifications:write y payment_verifications:read. 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.
  • Tu empresa necesita el checkout embebido activo. Lo está por defecto. Si está apagado, emitir un token responde 403 embed_disabled: escribe a soporte de Cobrix.
  • Suscribe tu webhook a payment_verification.verified, payment_verification.rejected y payment_verification.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: payment_verifications:write.
  • Firma: como toda la API de integraciones. Consulta Firma de solicitudes.
  • Idempotency-Key: obligatorio. Consulta Idempotencia.
Pide un token por pedido, justo antes de mostrar el formulario.
Solicitud
Cada campo acepta solo el tipo JSON de la tabla: "150000" o "5" responden 400 invalid_request. Un campo que no está en la tabla también. La moneda es la de la cuenta receptora, con la misma regla que la API de servidor. Consulta La moneda es la de la cuenta. El pago móvil solo existe en VES: en una cuenta en USD o EUR, pedir pago_movil responde 422 method_not_available, y sin methods el token sale solo para bank_transfer. Lo mismo en una cuenta bancaria (bank:…) cuyo teléfono receptor Cobrix no conoce. Consulta El pago móvil necesita su teléfono.
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, se haya revocado o se haya usado. Para un token nuevo, usa otra clave. El estado actual lo da GET /payment-verifications/tokens/{tokenId}.
Este ejemplo pide el token y lo devuelve a tu página:
Node.js (tu servidor)

Errores al pedir el token

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, por ejemplo al cargar la página de pago, y se lo pasa a checkout.js.
  • El formulario pide los datos que exige el banco de la cuenta receptora. 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.

Eventos en el navegador

Los eventos de resultado traen:
  • Un intento que no verifica no emite nada mientras le queden intentos al token. Tu cliente ve el aviso en el formulario y puede corregir los datos.
  • payment_verification.pending_review solo existe en el navegador. No hay un webhook con ese nombre.
  • Un evento puede llegar más de una vez, por ejemplo al volver a montar un token ya cerrado. Tu código debe tolerarlo.
  • Nunca traen el motivo, el monto ni datos del pagador.
  • verificationId es la validación del intento. Tu página se lo puede pasar a tu servidor.
No marques el pedido como pagado con estos eventos. Ocurren en el navegador de tu cliente: pueden no llegar si cierra la pestaña y cualquiera puede alterarlos desde su equipo. Úsalos solo para cambiar lo que ve tu cliente.

3. Confirma el resultado en tu servidor

Elige una de estas formas, o las dos:
  • Consulta el token con GET /payment-verifications/tokens/{tokenId}. Es la fuente de verdad.
  • Recibe los webhooks payment_verification.verified, payment_verification.rejected y payment_verification.failed. Consulta Webhooks.
Para el detalle de un intento, consulta la validación con GET /payment-verifications/{verificationId}. Es la misma validación de la API de servidor, con tokenId.
Requiere el permiso payment_verifications:read.
Respuesta 200
  • Un token cerrado muestra el estado actual de su validación. Un Zelle pasa de pending_review a verified o rejected cuando alguien lo revisa.
  • verificationId es la validación que cerró el token.
  • lastErrorCode es el resultado del último intento que no verificó, por ejemplo not_found, mismatch, ambiguous, already_used o unverifiable. Es rate_limited si lo frenó el límite de la llave. El detalle está en la validación.
  • attemptsUsed cuenta los intentos gastados. Un intento que se devolvió no cuenta.
  • Un token de otra empresa o que no existe responde 404 embed_token_not_found. Un tokenId que no es un UUID responde 400 invalid_request.

Revoca un token

Requiere el permiso payment_verifications:write. Responde 200 con el token, igual que el GET.
  • Revócalo si el pedido se cancela o se paga por otra vía. El navegador recibe 401 token_revoked desde ese momento.
  • Revocar un token cerrado no lo cambia: sigue mostrando su resultado.
  • 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 pocos intentos: maxAttempts, 5 como máximo.
  • Un intento se gasta cuando Cobrix tiene una respuesta sobre el pago: el banco lo confirma, no lo encuentra o un dato no coincide, o la referencia ya se usó. Un Zelle enviado también gasta su intento.
  • Si Cobrix no pudo consultar al banco, el intento se devuelve. Por ejemplo, porque el banco no respondió. Tu cliente puede probar de nuevo más tarde.
  • Cada token tiene además un tope de envíos: 3 veces maxAttempts, 15 en un token de 5 intentos. 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.
  • Un Zelle se envía una sola vez por token. El token se cierra en pending_review.
  • Una referencia ya usada nunca verifica, aunque la haya usado una validación anterior del mismo pedido. Una referencia paga un solo token. Si tu cliente reintenta con un token nuevo un pedido que ya quedó verificado, lo sabes por el token anterior.
Si el token gasta sus intentos sin un pago verificado, queda exhausted y Cobrix envía payment_verification.failed.

Límites

  • Un envío que frena el límite de la llave no llega al banco ni le cuesta un intento a tu cliente. Responde 429 rate_limited, y lastErrorCode del token queda en rate_limited.
  • Las validaciones que el banco confirma cuentan para el número de validaciones de tu empresa, igual que las de la API de servidor.

Rutas del navegador

checkout.js llama a estas rutas por ti. Te sirven para entender las respuestas y los errores, o para llamarlas desde tu página con el token.
  • Base: /api/embed/v1/payment-verifications, sobre el dominio de la API del ambiente. En producción: https://api.cobrix.co/api/embed/v1/payment-verifications.
  • Autenticación: Authorization: Bearer <token>. El token nunca va en la URL.
  • Origen: solo responden a una página de una web registrada por tu empresa.

GET /session

Respuesta 200
  • status: active, verified, pending_review, not_verified (un Zelle rechazado) o exhausted. Con verified, pending_review o not_verified el token ya está cerrado y verificationId trae su validación.
  • fields dice, por método, qué datos pide el banco de la cuenta.
  • methods son los del token que la cuenta sigue aceptando. Si la cuenta dejó de existir, methods es [] y receiver es null.
  • No trae tu referencia del pedido, ni metadata, ni la clave de la cuenta.

POST /

Solicitud
Cualquier otro campo responde 400 invalid_request, también amountMinor, currency o receiverAccountKey: esos los fijó tu servidor.
Respuesta 200
  • El navegador nunca recibe el motivo. Decir «el monto no coincide» o «ya está usada» confirmaría que esa referencia existe. El motivo es para tu servidor: lastErrorCode del token y GET /payment-verifications/{verificationId}.
  • verificationId es la validación de este intento. Es null cuando no se llegó a crear ninguna.
  • Un POST sobre un token ya cerrado responde 200 con su resultado, sin gastar nada.

Errores en el navegador

Todos traen { "error": { "code", "message" } }. Casi ningún error gasta un intento. Los 400, 401, 403, 409, 422 y 429 no gastan nada. Un 500 casi nunca gasta uno.

Webhooks

Configúralos en Integraciones › Webhooks y verifica su firma. Consulta Firma de webhooks.
  • Un intento que no verifica no envía nada.
  • Un Zelle enviado no envía nada hasta que alguien de tu empresa lo revisa.
  • payment_verification.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ó un pedido, consulta el token.

Seguridad

  • Tu llave no sale de tu servidor. El navegador solo recibe el token.
  • El token vive poco y sirve para un solo pedido. Caduca en 15 minutos por defecto, 30 como máximo.
  • El navegador no puede cambiar el pedido. Monto, moneda, cuenta receptora, métodos, tu referencia y metadata 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, sirve para un solo pedido y puedes revocarlo.
  • El navegador no recibe datos de más: ni el motivo de un rechazo, ni tu referencia del pedido, ni metadata, ni la clave de la cuenta.
  • Tu servidor decide. Entrega el pedido con el token o con el webhook firmado, nunca con el evento del navegador.

Lista para probar en sandbox

  1. Crea una llave en sandbox con payment_verifications:write y payment_verifications:read.
  2. Registra la dirección de tu web de pruebas en Configuración › Integraciones › Checkout embebido.
  3. Pide un token con POST /payment-verifications/tokens. Guarda id y entrega token a tu página.
  4. Muestra el formulario con checkout.js de sandbox.
  5. Configura un webhook y confirma el resultado con GET /payment-verifications/tokens/{tokenId}.

Validación por API

Cuentas receptoras, estados, motivos y la regla de la moneda.

Webhooks de validación

Payload de cada evento payment_verification.*.