Detalles de pago normalizados (paymentInfo)
Cuando consultas una transacción con GET /transactions, la respuesta incluye un campo paymentInfo con el resumen del pago en una forma estándar, sin importar qué procesador lo atendió —tarjeta, billetera, QR o transferencia—. Está pensado para soporte, conciliación y reportería: no necesitas conocer el formato de respuesta particular de cada procesador para leer marca de tarjeta, últimos 4 dígitos, resultado de 3D Secure o el evento de autorización.
paymentInfo es null (o el campo puede estar ausente) hasta que la transacción tiene al menos un intento de cobro. Una vez que existe, se va completando progresivamente: cada nuevo evento del procesador (autorización, captura, resultado 3DS) se combina con lo que ya había, en lugar de reemplazarlo. Un dato que ya se guardó no se borra porque una respuesta posterior no lo traiga.
Forma general
{
"paymentMethodInfo": { "...": "ver abajo" },
"user": { "...": "ver abajo" },
"authentication": { "...": "ver abajo" },
"authorization": { "...": "ver abajo" },
"capture": [{ "...": "ver abajo" }]
}
| Campo | Tipo | Descripción |
|---|---|---|
| paymentMethodInfo | object o null | Datos no sensibles del método de pago usado (marca, últimos 4 dígitos, vencimiento, o datos de cuenta/banco para métodos no tarjeta). |
| user | object o null | Datos del pagador. Solo se incluye cuando hay al menos un dato real disponible. |
| authentication | object o null | Resultado de 3D Secure, cuando el procesador lo ejecuta. |
| authorization | object o null | El evento en el que el procesador aprobó, rechazó o dejó pendiente el cobro. |
| capture | array de objetos o null | Uno o más eventos de captura confirmada (puede haber varias en capturas parciales). |
paymentMethodInfo
Nunca incluye el número completo de tarjeta ni el CVV — solo los datos que necesitas para mostrarle al comercio o al cliente qué medio se usó.
{
"type": "card",
"brand": "VISA",
"last4": "1111",
"bin": "411111",
"holderName": "Juan Perez",
"expirationMonth": "12",
"expirationYear": "2028",
"accountHolder": null,
"accountNumber": null,
"bankCode": null,
"bankName": null
}
| Campo | Descripción |
|---|---|
| type | card, cardToken, wallet, bankTransfer, cash, credit o null. Si el procesador reporta un pago con tarjeta guardada como token, se normaliza a cardToken. |
| brand | Marca de la tarjeta (VISA, MASTERCARD, AMEX, …), siempre en mayúsculas. |
| last4 | Últimos 4 dígitos de la tarjeta o cuenta. |
| bin | Primeros 6–8 dígitos de la tarjeta (identifica banco emisor y red). |
| holderName | Nombre del tarjetahabiente, cuando el procesador lo reporta. |
| expirationMonth / expirationYear | Vencimiento de la tarjeta (mes en formato MM, año en 4 dígitos). |
| accountHolder / accountNumber / bankCode / bankName | Datos de cuenta para métodos no tarjeta (wallets, transferencias). |
user
Datos del pagador, derivados principalmente del billTo que se envió al cobrar.
{
"name": "Juan Perez",
"email": "juan@example.com",
"phone": "50255555555",
"address": "Ciudad de Guatemala",
"documentType": null,
"documentNumber": null
}
Si el procesador reporta el nombre del tarjetahabiente (paymentMethodInfo.holderName), ese valor tiene prioridad sobre el nombre enviado en billTo.
authentication
Presente cuando el pago pasó (o intentó pasar) por 3D Secure — la validación adicional que el banco emisor puede pedirle al cliente antes de aprobar el pago.
{
"active": true,
"eci": "05",
"authenticationStatus": "Y",
"cavv": "<cryptogram>",
"xid": null,
"dsTransactionId": "<ds-transaction-id>",
"protocolVersion": "2.2.0"
}
| Campo | Descripción |
|---|---|
| active | Si hubo autenticación 3DS. Una vez queda en true, se mantiene en true en actualizaciones posteriores aunque una respuesta no lo repita. |
| eci | Electronic Commerce Indicator reportado por el procesador. |
| authenticationStatus | Estado de autenticación reportado por el procesador o el sistema 3DS. |
| cavv | Cardholder Authentication Verification Value — criptograma de evidencia técnica de la autenticación. |
| xid | Identificador de transacción de flujos 3DS 1.x, cuando aplica. |
| dsTransactionId | Identificador del Directory Server en flujos 3DS 2.x. |
| protocolVersion | Versión del protocolo 3DS (por ejemplo 2.1.0, 2.2.0). |
authorization y capture
Ambos comparten la misma forma de evento. authorization es un único evento y describe una preautorización: el procesador reservó los fondos y el cobro se confirma en una llamada aparte. capture es una lista de cobros confirmados, porque puede haber varias capturas parciales sobre la misma autorización.
Muchos métodos de pago cobran en un solo paso: billeteras como Nequi, los QR, las transferencias y la mayoría de los pagos con tarjeta. Esos procesadores no tienen etapa de preautorización, así que authorization viene con todos sus campos en null y el resultado del pago se lee en capture.
Para saber si un pago prosperó, usá el campo status de la transacción. paymentInfo es el registro de los eventos del pago, no su estado actual.
{
"timestamp": "2026-06-26T18:29:00.000Z",
"transactionId": "processor-auth-123",
"reference": "123456789012",
"authorizationCode": "ABC123",
"statusCode": "00",
"statusMessage": "APPROVED",
"approved": true
}
| Campo | Descripción |
|---|---|
| timestamp | Fecha/hora del evento en ISO 8601. |
| transactionId | Identificador que el procesador le dio a ese evento (autorización, cargo o captura). |
| reference | Referencia del procesador — RRN, número de orden u otro identificador útil para conciliación. |
| authorizationCode | Código de autorización del procesador, cuando existe. |
| statusCode / statusMessage | Código y mensaje de estado reportados por el procesador. |
| approved | true = aprobado, false = rechazado, null = pendiente o no determinado. |
Si el mismo evento de captura llega más de una vez (reintentos, reconciliación), se deduplica por la combinación de transactionId + reference + statusCode + authorizationCode — no verás duplicados en capture.
Ejemplo completo
{
"paymentMethodInfo": {
"type": "card",
"brand": "VISA",
"last4": "1111",
"bin": "411111",
"holderName": "Juan Perez",
"expirationMonth": "12",
"expirationYear": "2028",
"accountHolder": null,
"accountNumber": null,
"bankCode": null,
"bankName": null
},
"user": {
"name": "Juan Perez",
"email": "juan@example.com",
"phone": "50255555555",
"address": "Ciudad de Guatemala",
"documentType": null,
"documentNumber": null
},
"authentication": {
"active": true,
"eci": "05",
"authenticationStatus": "Y",
"cavv": "<cryptogram>",
"xid": null,
"dsTransactionId": "<ds-transaction-id>",
"protocolVersion": "2.2.0"
},
"authorization": {
"timestamp": "2026-06-26T18:29:00.000Z",
"transactionId": "processor-auth-123",
"reference": "123456789012",
"authorizationCode": "ABC123",
"statusCode": "00",
"statusMessage": "APPROVED",
"approved": true
},
"capture": [
{
"timestamp": "2026-06-26T18:30:00.000Z",
"transactionId": "processor-capture-123",
"reference": "123456789012",
"authorizationCode": "ABC123",
"statusCode": "00",
"statusMessage": "CAPTURED",
"approved": true
}
]
}
Pago de un solo paso
El mismo objeto para un pago que se cobra en una sola llamada — acá una billetera Nequi ya confirmada. authorization está presente pero vacío, y el resultado del pago se lee en capture:
{
"paymentMethodInfo": {
"type": "wallet",
"brand": null,
"last4": null,
"bin": null,
"holderName": null,
"expirationMonth": null,
"expirationYear": null,
"accountHolder": null,
"accountNumber": "3001234567",
"bankCode": null,
"bankName": null
},
"authentication": {
"active": false,
"eci": null,
"authenticationStatus": null,
"cavv": null,
"xid": null,
"dsTransactionId": null,
"protocolVersion": null
},
"authorization": {
"timestamp": null,
"transactionId": null,
"reference": null,
"authorizationCode": null,
"statusCode": null,
"statusMessage": null,
"approved": null
},
"capture": [
{
"timestamp": "2026-11-17T18:21:38.369Z",
"transactionId": "4HdTqyWzW48lRN5fi29ZQ",
"reference": "4HdTqyWzW48lRN5fi29ZQ",
"authorizationCode": "NEQUI-AUTH",
"statusCode": "00",
"statusMessage": "Transaccion aprobada",
"approved": true
}
]
}
La especificación en vivo documenta la forma general de la transacción, pero todavía no describe la estructura interna de paymentInfo campo por campo. Esta página es la referencia autoritativa mientras tanto — está verificada contra el comportamiento real del endpoint.
Relacionado
- Flujo de pago por API → Consultar la transacción — cómo pedir la transacción completa, incluido paymentInfo.
- Crear un link de pago — cómo se crea la transacción que luego consultas.
- Webview hospedado — dónde ocurre el 3D Secure que llena authentication.