Skip to main content
Tu servidor envía los datos de un pago que recibió tu empresa y Cobrix responde si es bueno. 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:write y payment_verifications:read en Configuración → Integraciones → Llaves API. Consulta Autenticación.
  • Firma cada llamada. La ruta que firmas empieza en /api. Consulta Firma de solicitudes.
  • El POST lleva Idempotency-Key, de hasta 255 caracteres. Consulta Idempotencia.
  • Para Zelle, suscribe tu webhook a payment_verification.verified y payment_verification.rejected.
Las rutas de esta guía van después de la URL base del ambiente, que ya termina en /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 receiverAccountKey tal 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_field con field: "currency". detail dice cuál es la moneda de la cuenta. No consulta al banco.
  • El pago móvil solo existe en bolívares. pago_movil sobre una cuenta en USD o EUR responde 422 invalid_receiver_account.
  • Una cuenta bancaria cuya moneda no sea VES, USD ni EUR no aparece en la lista. Tampoco una cuenta en USD o EUR que su banco solo deja consultar por pago móvil. Si envías una de ellas, responde 422 invalid_receiver_account.

El pago móvil necesita su teléfono

Cobrix ofrece pago_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 receiverAccountKey pago_movil:… o pago_movil_method:….
  • Si no, la cuenta bancaria (bank:…) ofrece pago_movil solo si su conexión con el banco tiene el teléfono receptor configurado. Sin él, ofrece solo bank_transfer. Si su banco solo deja consultar pago móvil, no aparece.
  • pago_movil sobre 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.
Por qué. El banco compara solo la cifra, no la moneda. Sin esta regla, un pago de Bs 1.500,00 confirmaría una validación por USD 1.500,00 sobre una cuenta en bolívares.

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.
  • tokenId es null en una validación que pide tu servidor. Trae el id del 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 201 con su status.
  • reference vuelve enmascarada: solo sus últimos 4 caracteres, después de limpiarla. El teléfono, el documento y el nombre del pagador nunca vuelven.
  • bank es lo que informó el banco. Solo viene en verified tras una respuesta del banco.

3. Lee el resultado

Solo verified confirma el pago. unverifiable y pending_review no son un rechazo ni una aprobación.
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 2345 y 00012345 son la misma referencia.
  • Lo que vuelve en reference son 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
Un Zelle en revisión no vence. Queda en pending_review hasta que alguien de tu empresa lo resuelve: Cobrix no lo aprueba ni lo rechaza solo, y no avisa mientras espera. Te enteras por el webhook o consultando GET /{verificationId}. Si tu flujo necesita un plazo, ponlo en tu sistema.
  • Si tu empresa no tiene Zelle configurado, el POST responde 422 method_not_available.
  • Con otra moneda que no sea USD, responde 422 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 segundo POST 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_review hasta que una persona de tu empresa la rechaza. Entonces llega payment_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

Devuelve la validación con su estado actual. Un id de otra empresa o que no existe responde 404 payment_verification_not_found.

Reintentos

Toda respuesta 201 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.
Un unverifiable porque el banco no respondió es una respuesta completa. Si reintentas con la misma Idempotency-Key, recibes el mismo unverifiable. Para consultar al banco otra vez, envía el POST con una clave nueva.
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.
Es la respuesta a "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 del POST. 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 POST por 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 POST responde 403 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 id ajeno responde 404.

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.