Skip to main content
POST
Validar un pago

Authorizations

Authorization
string
header
required

Llave cbx_live creada para el partner.

Headers

Idempotency-Key
string
required

Identificador estable de la operación.

Minimum string length: 1
Cobrix-Timestamp
string
required

Segundos Unix dentro de una ventana de cinco minutos.

Pattern: ^[0-9]{10}$
Cobrix-Signature
string
required

HMAC-SHA256 de timestamp, método, ruta y cuerpo crudo.

Pattern: ^v1=[a-f0-9]{64}$
X-Request-Id
string

Identificador opcional para correlación de soporte.

Path Parameters

companyId
string<uuid>
required

Empresa vinculada a la llave.

Body

application/json

Cada campo acepta solo el tipo JSON de su esquema; Cobrix no convierte tipos.

method
enum<string>
required

pago_movil y bank_transfer: Cobrix consulta al banco. zelle: lo revisa una persona de la empresa.

Available options:
pago_movil,
bank_transfer,
zelle
reference
string
required

La referencia del comprobante, completa. En Zelle, la confirmación completa.

Required string length: 1 - 64
amountMinor
integer
required

Monto en unidades menores, como número entero JSON: 150000 es Bs 1.500,00. Un texto ("150000", "1500.00") responde 400 invalid_request.

Required range: x >= 1
paymentDate
string<date>
required

El día del pago, YYYY-MM-DD.

receiverAccountKey
string

La cuenta de la empresa que recibió el pago, de GET payment-verifications/receiver-accounts. Obligatoria en pago_movil y bank_transfer. Opcional en zelle: si la empresa tiene una sola cuenta Zelle, Cobrix usa esa.

Pattern: ^(pago_movil|pago_movil_method|bank|zelle):[0-9a-f-]{36}$
currency
string

La moneda de la cuenta receptora, la que trae currency en GET payment-verifications/receiver-accounts. Si no la envías, es esa. Otra responde 422 invalid_field con field: "currency". Zelle es siempre USD.

Pattern: ^[A-Z]{3}$
payerBankCode
string

Banco desde el que pagó la persona. Obligatorio si el banco de la cuenta receptora lo exige.

Pattern: ^[0-9]{4}$
payerPhone
string

Teléfono del pagador. Obligatorio si el banco de la cuenta receptora lo exige.

Required string length: 1 - 32
payerDocument
string

Cédula o RIF del pagador. Obligatorio si el banco de la cuenta receptora lo exige.

Required string length: 1 - 32
payerName
string

Nombre de quien envió el Zelle. Lo ve quien revisa; nunca vuelve en la respuesta.

Required string length: 1 - 200
externalReference
string

Tu referencia. Vuelve tal cual.

Required string length: 1 - 128
metadata
object

Objeto JSON que vuelve tal cual. Hasta 2048 bytes serializado.

Response

La validación con su resultado

Una validación. También es el data de los webhooks payment_verification.verified y payment_verification.rejected.

id
string<uuid>
required
method
enum<string>
required

pago_movil y bank_transfer: Cobrix consulta al banco. zelle: lo revisa una persona de la empresa.

Available options:
pago_movil,
bank_transfer,
zelle
status
enum<string>
required

verified: el banco confirmó el pago, o una persona de la empresa aprobó el Zelle. not_found: el banco no tiene un pago con esos datos. mismatch: el banco rechazó el pago porque un dato no coincide; ver reason. already_used: la referencia ya se usó en otra validación de la empresa. ambiguous: más de un pago coincide y no se marcó ninguno. unverifiable: no se pudo consultar al banco; ver reason. pending_review: Zelle en revisión, sin vencimiento. rejected: una persona de la empresa rechazó el Zelle. Solo pending_review cambia después.

Available options:
verified,
not_found,
mismatch,
already_used,
ambiguous,
unverifiable,
pending_review,
rejected
reason
string | null
required

Por qué no quedó verified. En mismatch: amount_mismatch, date_mismatch, phone_mismatch, document_mismatch, bank_mismatch, duplicate_reference, already_reconciled o bank_rejected. En unverifiable: bank_unavailable, payment_too_old, invalid_payer_data o provider_misconfigured. En already_used: reference_already_used. En ambiguous: multiple_matches. En rejected: rejected_by_reviewer.

warnings
enum<string>[]
required

Solo en verified. already_recorded_in_cobrix: Cobrix ya tiene un pago de la empresa con esa referencia aplicado a un documento de cobro. pending_in_cobrix: Cobrix tiene un pago con esa referencia esperando aprobación. bank_amount_differs: el banco informó un monto distinto de amountMinor.

Available options:
already_recorded_in_cobrix,
pending_in_cobrix,
bank_amount_differs
reference
string
required

La referencia enmascarada: solo sus últimos 4 caracteres.

amountMinor
integer
required

El monto que enviaste.

currency
string
required
paymentDate
string<date>
required
bank
object | null
required

Lo que informó el banco sobre la cuenta de la empresa. Solo en verified tras una respuesta del banco.

receiverAccountKey
string | null
required
externalReference
string | null
required
metadata
object | null
required
createdAt
string<date-time>
required
resolvedAt
string<date-time> | null
required

null mientras está en pending_review.

resolvedBy
enum<string> | null
required

bank: Cobrix la resolvió en el POST. reviewer: una persona de la empresa (Zelle). null mientras está en pending_review.

Available options:
bank,
reviewer,
null
reviewNote
string | null
required

La nota de quien revisó el Zelle, si dejó una. Su identidad nunca se expone.

tokenId
string<uuid> | null
required

El token de validación embebida con el que tu cliente envió el pago. null si la validación la pidió tu servidor con POST payment-verifications.

originalVerificationId
string<uuid>

Solo en already_used, y solo si la referencia la usó antes una validación de tu misma integración: el id de esa validación.