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.
Antes de empezar
- Crea una llave con
payment_verifications:writeypayment_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.rejectedypayment_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.
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
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, se haya revocado o se haya usado. Para un token nuevo, usa otra clave. El estado actual lo daGET /payment-verifications/tokens/{tokenId}.
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 eltoken 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.
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.
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_reviewsolo 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.
verificationIdes la validación del intento. Tu página se lo puede pasar a tu servidor.
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.rejectedypayment_verification.failed. Consulta Webhooks.
GET /payment-verifications/{verificationId}. Es la misma validación de la API de servidor, con tokenId.
payment_verifications:read.
Respuesta 200
- Un token cerrado muestra el estado actual de su validación. Un Zelle pasa de
pending_reviewaverifiedorejectedcuando alguien lo revisa. verificationIdes la validación que cerró el token.lastErrorCodees el resultado del último intento que no verificó, por ejemplonot_found,mismatch,ambiguous,already_usedounverifiable. Esrate_limitedsi lo frenó el límite de la llave. El detalle está en la validación.attemptsUsedcuenta 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. UntokenIdque no es un UUID responde400 invalid_request.
Revoca un token
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_revokeddesde 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 quedaexhaustedaunque 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.
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, ylastErrorCodedel token queda enrate_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) oexhausted. Converified,pending_reviewonot_verifiedel token ya está cerrado yverificationIdtrae su validación.fieldsdice, por método, qué datos pide el banco de la cuenta.methodsson los del token que la cuenta sigue aceptando. Si la cuenta dejó de existir,methodses[]yreceiveresnull.- 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:
lastErrorCodedel token yGET /payment-verifications/{verificationId}. verificationIdes la validación de este intento. Esnullcuando no se llegó a crear ninguna.- Un
POSTsobre un token ya cerrado responde200con 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.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ó 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
metadatalos fija tu servidor al emitir el token. Si el navegador los envía, la respuesta es400. - 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
- Crea una llave en sandbox con
payment_verifications:writeypayment_verifications:read. - Registra la dirección de tu web de pruebas en Configuración › Integraciones › Checkout embebido.
- Pide un token con
POST /payment-verifications/tokens. Guardaidy entregatokena tu página. - Muestra el formulario con
checkout.jsde sandbox. - 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.*.
