data. Esta página evita repetir tablas extensas en cada evento.
Envelope general
{
"id": "evt_40544883-5dd6-420d-960a-f473ec2a754a",
"event": "payment.succeeded",
"created_at": "2026-07-14T16:00:00.000Z",
"api_version": "2025-01-21",
"data": {}
}
| Campo | Tipo | Uso |
|---|---|---|
id | string | Identificador estable para deduplicar el evento. |
event | string | Tipo que selecciona el manejador correspondiente. |
created_at | ISO 8601 | Momento en que Cobrix construyó el payload. |
api_version | string | Versión del contrato del envelope. |
data | object | Datos específicos descritos en la página del evento. |
customer
| Campo | Tipo | Nulable | Significado |
|---|---|---|---|
companyCustomerId | string | No | Cliente dentro de la empresa. |
name, email, phone, taxId | string | Sí | Identidad disponible del cliente. |
externalRef, customerCode | string | Sí | Correlación con sistemas externos. |
metadata, customFieldsData | object | Sí | Datos adicionales configurados. |
labels | string[] | No | Etiquetas actuales. |
status, type | string | Sí | Estado y tipo de relación. |
address | object | Sí | street, city, state, postalCode y country, todos nulables. |
payment
| Campo | Tipo | Nulable | Significado |
|---|---|---|---|
id, companyId | string | No | Pago y empresa propietarios. |
companyCustomerId, checkoutSessionId, subscriptionId | string | Sí | Relaciones del pago. |
status, reconciliationStatus | string | Sí | Estado persistido y conciliación. |
amount, amountMinor, currency | number/string | Sí | Monto en unidades mayores, menores y moneda. |
referenceAmountMinor, referenceCurrency | number/string | Sí | Resultado de conversión. |
provider, providerChargeId | string | Sí | Proveedor y transacción externa. |
paymentReference, paymentReferenceMasked | string | Sí | Referencia y versión enmascarada. |
hasPaymentReference, hasProof | boolean | No | Presencia de referencia y comprobante. |
paidAt, valueDate, createdAt, updatedAt | ISO 8601 | Sí | Fechas financieras y operativas. |
exchange | object | Sí | Conversión aplicada. |
Estado financiero en eventos de checkout y pago
checkout.session.completed y payment.succeeded comparten los siguientes campos en data. Sus valores reflejan el estado exacto en el momento de crear cada evento.
| Campo | Tipo | Nulable | Significado |
|---|---|---|---|
amount, amountMinor | number | No | Dinero recibido en currency. |
amountSource | string | No | Fuente financiera: ocr, provider o customer_reported. |
expectedAmount, expectedAmountMinor | number | No | Monto elegido en currency; el comprobante OCR debe coincidir exactamente. |
documentAmountDue, documentAmountDueMinor | number | Sí | Deuda congelada al enviar el checkout, en documentCurrency. |
documentCurrency | string | Sí | Moneda de deuda, aplicación y saldo. |
isPartialPayment | boolean | Sí | Indica si el monto elegido era inferior a la deuda, después de considerar la conversión certificada. |
appliedAmount, appliedAmountMinor | number | No | Monto aplicado en documentCurrency; es cero mientras el pago está pendiente. |
remainingBalance, remainingBalanceMinor | number | Sí | Saldo restante en documentCurrency. |
verification.status | string | No | Estado observable: por ejemplo queued, verified, not_found o manual_review_required. |
verification.attemptCount | number | No | Cantidad de intentos persistidos al crear el evento. |
verification.automaticApproval | boolean | No | Indica si la evidencia permitió aprobación automática. |
verification.provider | string | Sí | Adaptador o proveedor consultado. |
verification.lastOutcome | string | Sí | Último código o razón de fallo disponible. |
documents | object[] | No | Documentos relacionados, cada uno con moneda, saldo y metadata pública. |
requiresReview, reviewReasons | boolean/string[] | No | Decisión consolidada de revisión y sus razones legibles por máquina. |
Los campos sin prefijo de documento (
amountMinor, expectedAmountMinor) usan currency. Los campos de deuda, aplicación y saldo usan documentCurrency. No los compares directamente si las monedas son distintas.paymentMethod
| Campo | Tipo | Significado |
|---|---|---|
kind, method, label | string o null | Identidad técnica, valor de dominio y etiqueta. |
channel | string | Canal automatic, manual, proof o unknown. |
provider | string o null | Proveedor asociado. |
isManual | boolean | Indica captura administrativa/manual. |
requiresReconciliation | boolean | Indica que el pago todavía requiere revisión. |
receiver | object o null | Cuenta receptora con teléfono y documento enmascarados. |
receiverCheck | object o null | Resultado de comparación OCR: estado, confianza y campos coincidentes. |
submitted | object o null | Datos enviados por el cliente, siempre enmascarados cuando son sensibles. |
review.requiresReview | boolean | Señal consolidada para revisión manual. |
review.reasons | string[] | Razones legibles por máquina. |
review.ocrVerdict | string o null | approve_recommended o needs_review. |
review.ocrConfidence | number o null | Confianza OCR de 0 a 100. |
exchange
| Campo | Tipo | Significado |
|---|---|---|
targetCurrency | string | Moneda destino. |
rate | number | Tasa usada; moneda origen dividida por esta tasa produce destino. |
rateDate | ISO 8601 | Fecha efectiva. |
rateSource | string | Fuente como bcv_usd, manual o api_auto. |
convertedAmount | number | Monto convertido en unidades mayores. |
convertedAmountMinor | number | Monto convertido en unidades menores. |
Documento compacto en pagos
| Campo | Tipo | Significado |
|---|---|---|
invoiceId | string | Identificador técnico del documento en Cobrix. |
invoiceNumber | string opcional | Número visible del documento. |
externalInvoiceId | string opcional | Correlación externa conservada. |
source | string opcional | Sistema que originó el documento. |
currency | string | Moneda del documento. |
appliedAmountMinor | string opcional | Monto aplicado. |
remainingBalanceMinor | string opcional | Saldo después de aplicar. |
metadata | object | Metadata pública persistida en el documento; {} cuando no existe. |
Los campos son aditivos: tu parser debe ignorar propiedades desconocidas y tolerar
null donde el contrato lo permita.