Llama siempre desde tu servidor. La llave nunca va en el navegador. Si quieres que tu cliente escriba la referencia en tu web, usa la validación embebida.
Desde el 17/11/2026, la moneda es la de la cuenta receptora. Antes, un
POST con una currency distinta de la de la cuenta se aceptaba. Ahora responde 422 invalid_field. Si no envías currency, o envías la de la cuenta, no cambia nada. En una cuenta bancaria en USD o EUR, el valor por defecto ahora es la moneda de la cuenta (antes era VES), y esa cuenta ya no acepta pago_movil. Consulta La moneda es la de la cuenta.También desde el 17/11/2026, una cuenta bancaria ofrece pago_movil solo si Cobrix conoce el teléfono que lo recibe. Consulta El pago móvil necesita su teléfono.Cómo funciona
1
Lista las cuentas receptoras
GET /receiver-accounts trae las cuentas de tu empresa contra las que puedes validar.2
Envía el pago
POST / con la cuenta receptora, la referencia, el monto y el día del pago.3
Lee el resultado
La respuesta
201 trae status. En pago móvil y transferencia ya es el resultado del banco.4
Si es Zelle, espera la revisión
Queda en
pending_review. Tu servidor recibe un webhook cuando alguien de tu empresa lo resuelve.Antes de empezar
- Crea una llave con
payment_verifications:writeypayment_verifications:readen Configuración → Integraciones → Llaves API. Consulta Autenticación. - Firma cada llamada. La ruta que firmas empieza en
/api. Consulta Firma de solicitudes. - El
POSTllevaIdempotency-Key, de hasta 255 caracteres. Consulta Idempotencia. - Para Zelle, suscribe tu webhook a
payment_verification.verifiedypayment_verification.rejected.
/api: https://api.cobrix.co/api/integrations/v1/{companyId}/payment-verifications en producción. Las rutas cortas (POST /, GET /receiver-accounts) 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.
Bancos con respuesta inmediata
Cobrix consulta al banco cuando la cuenta receptora es de Banco de Venezuela (0102), Mercantil (0105) o Banesco (0134), en pago móvil y en transferencia.
La lista de tu empresa la da GET /receiver-accounts. Una cuenta de banco aparece solo si Cobrix puede consultarla: el banco admite la consulta y tu empresa tiene esa cuenta conectada en Cobrix. Contra una cuenta que no aparece no puedes validar con esta API.
1. Lista las cuentas receptoras
Respuesta 200
Cómo elegir la cuenta receptora
- Usa la cuenta de tu empresa a la que tu cliente dice que pagó.
- La cuenta debe traer el método del pago en
methods. - Si hay dos cuentas del mismo banco, distínguelas por
maskedIdentifier. - Envía
receiverAccountKeytal como viene. No lo armes tú. - Cobrix consulta solo al banco de esa cuenta.
- La cuenta fija la moneda. Consulta La moneda es la de la cuenta.
- Una cuenta que no existe, está inactiva o no acepta el método responde
422 invalid_receiver_account. - En Zelle es opcional: si tu empresa tiene una sola cuenta Zelle, Cobrix usa esa. Con varias, envíala para que quien revisa sepa a cuál llegó el pago.
La moneda es la de la cuenta
La moneda de una validación es la moneda de su cuenta receptora.GET /receiver-accounts la trae en currency.
- Si no envías
currency, Cobrix usa la de la cuenta. - Si envías otra, responde
422 invalid_fieldconfield: "currency".detaildice cuál es la moneda de la cuenta. No consulta al banco. - El pago móvil solo existe en bolívares.
pago_movilsobre una cuenta enUSDoEURresponde422 invalid_receiver_account. - Una cuenta bancaria cuya moneda no sea
VES,USDniEURno aparece en la lista. Tampoco una cuenta enUSDoEURque su banco solo deja consultar por pago móvil. Si envías una de ellas, responde422 invalid_receiver_account.
El pago móvil necesita su teléfono
Cobrix ofrecepago_movil solo donde conoce el teléfono al que tu cliente envía el dinero.
- Si tu empresa tiene un pago móvil configurado en ese banco, aparece como su propia cuenta, con
receiverAccountKeypago_movil:…opago_movil_method:…. - Si no, la cuenta bancaria (
bank:…) ofrecepago_movilsolo si su conexión con el banco tiene el teléfono receptor configurado. Sin él, ofrece solobank_transfer. Si su banco solo deja consultar pago móvil, no aparece. pago_movilsobre una cuenta bancaria sin teléfono responde como un método que la cuenta no acepta. No consulta al banco.
Para validar pago móvil en ese banco, configura el pago móvil de tu empresa en Configuración › Pago Móvil, o escribe a soporte de Cobrix.
2. Envía el pago
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 un número: 150000, no "150000", "1500.00" ni true. Los demás campos son textos entre comillas, también payerBankCode y payerPhone. Otro tipo responde 400 invalid_request con su field. Consulta el ejemplo.
Qué datos del pagador son obligatorios depende del banco de la cuenta receptora y del método. Si falta alguno, Cobrix responde 422 missing_fields con todos en fields, sin consultar al banco:
Respuesta 201
- Guarda
id. Con él consultas la validación. tokenIdesnullen una validación que pide tu servidor. Trae eliddel token cuando tu cliente envió el pago desde tu web con la validación embebida.- Un resultado negativo no es un error HTTP. La respuesta es
201con sustatus. referencevuelve enmascarada: solo sus últimos 4 caracteres, después de limpiarla. El teléfono, el documento y el nombre del pagador nunca vuelven.bankes lo que informó el banco. Solo viene enverifiedtras una respuesta del banco.
3. Lee el resultado
Una validación
verified marca la referencia como usada en tu empresa. La siguiente validación de esa referencia responde already_used, venga de esta API, del panel de Cobrix o del checkout. Si la usó antes una validación de tu misma integración, la respuesta trae originalVerificationId con el id de esa validación.
Cómo compara Cobrix la referencia
- Antes de comparar, Cobrix limpia la referencia: quita espacios, guiones, puntos y comas, y pasa las letras a mayúsculas.
0001-2345,0001 2345y00012345son la misma referencia. - Lo que vuelve en
referenceson los últimos 4 caracteres de la referencia ya limpia. - En pago móvil y transferencia, «ya usada» se decide con los últimos 6 caracteres, por empresa y por banco de la cuenta receptora. Dos referencias distintas que terminan en los mismos 6 caracteres cuentan como la misma: la segunda responde
already_used. - En Zelle cuenta la confirmación completa.
Motivos en reason
Avisos en warnings
Solo vienen en verified. El pago está confirmado; el aviso agrega contexto.
Zelle
Zelle no tiene consulta al banco. Cobrix guarda la validación y una persona de tu empresa la revisa.1
Envía el Zelle
POST / con method: "zelle", la confirmación completa en reference, el monto en USD y el día. Responde 201 con status: pending_review.2
Tu empresa lo revisa en el panel de Cobrix
Una persona de tu empresa lo compara con el estado de cuenta de Zelle y lo aprueba o lo rechaza. Puede dejar una nota.
3
Tu servidor recibe el resultado
Llega
payment_verification.verified o payment_verification.rejected. La nota viene en reviewNote.Zelle en revisión
- Si tu empresa no tiene Zelle configurado, el
POSTresponde422 method_not_available. - Con otra moneda que no sea
USD, responde422 invalid_field. - La revisión se hace solo en el panel de Cobrix. No hay una ruta de esta API para aprobar o rechazar.
La misma confirmación dos veces
Cobrix no compara confirmaciones al crear la validación. Un segundoPOST con la misma confirmación y otra Idempotency-Key crea otra validación en pending_review, aunque la primera siga en revisión o ya esté aprobada.
- Solo una de las dos se puede aprobar.
- La otra no cambia sola: sigue en
pending_reviewhasta que una persona de tu empresa la rechaza. Entonces llegapayment_verification.rejected. - No envíes dos veces la misma confirmación. Antes de enviarla, busca en tu sistema si ya la validaste.
Consultar una validación
id de otra empresa o que no existe responde 404 payment_verification_not_found.
Reintentos
Toda respuesta201 queda guardada con su Idempotency-Key, también unverifiable, not_found y pending_review. La misma clave con el mismo cuerpo devuelve esa respuesta guardada: Cobrix no consulta al banco otra vez.
Si una respuesta
verified se pierde y validas el mismo pago con otra clave, recibes already_used con originalVerificationId: es el id de la validación que ya lo confirmó.
Errores
Los errores traen{ "error": { "code", "message" } }. Los comunes a toda la API están en Errores y rate limits.
Ningún
4xx consulta al banco ni crea la validación.
Un campo que falta, con otro tipo JSON, con formato incorrecto o que no está en esta página, y un verificationId que no es un UUID, responden 400 invalid_request. 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.
"amountMinor": "1500.00": el monto va como número entero en unidades menores.
Un cuerpo vacío o que no es JSON válido también responde 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 ni de tus datos. El mensaje es genérico y no trae detalles internos. Si envías X-Request-Id, vuelve como requestId en los errores 400, 401, 429 y 500, y en 403 company_mismatch y 403 insufficient_scope: dáselo a soporte. No vuelve en 403 verification_limit_reached, 404, 409 ni 422.
Webhooks
Un pago móvil o una transferencia que envía tu servidor no manda webhooks: su resultado llega en la respuesta delPOST. Los webhooks avisan de un Zelle revisado y de lo que tu cliente envía desde tu web con la validación embebida. Configúralos en Integraciones › Webhooks y verifica su firma. Consulta Firma de webhooks.
En
verified y rejected, data es la misma validación que devuelve GET /{verificationId}.
Límites
- Validaciones por llave: 60
POSTpor minuto. Las consultas, 120 por minuto por ruta. - Validaciones por empresa: las que el banco confirma cuentan para el número configurado de tu empresa. Al alcanzarlo, el
POSTresponde403 verification_limit_reached. - Datos mínimos: las respuestas y los webhooks traen la referencia enmascarada y nunca el teléfono, el documento o el nombre del pagador.
- Cada validación es de su empresa. Un
idajeno responde404.
Referencia de la API
Campos, respuestas y códigos de cada ruta.
Webhooks de validación
Payload de cada evento
payment_verification.*.Validación embebida
Tu cliente escribe la referencia en tu web, con un token corto.

