Consultar estado de transacción
GET /api/pix/transaction/{id}
GET https://<api-host>/api/pix/transaction/{id}Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.
Retorna el estado actual de una transacción PIX con información detallada sobre montos, contraparte y marcas de tiempo.
El identificador puede ser:
- ID numérico: Identificador interno de la transacción retornado por Gateways
- externalId: Identificador externo que usted proporcionó al crear la transacción
Autenticación
Requiere un Bearer token en el header Authorization.
Parámetros de ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | ID de la transacción (numérico) o externalId (cadena) |
Ejemplos de Código
curl -X GET "https://<api-host>/api/pix/transaction/123" \
-H "Authorization: Bearer $PIX_API_TOKEN"const axios = require('axios');
const response = await axios.get('https://<api-host>/api/pix/transaction/123', {
headers: { 'Authorization': `Bearer ${process.env.PIX_API_TOKEN}` },
});
console.log(response.data);Respuesta (200)
| Campo | Tipo | Descripción |
|---|---|---|
id | string | ID de la transacción |
externalId | string | null | ID externo proporcionado por el cliente |
type | string | Tipo de transacción: PAYMENT, WITHDRAW, REFUND_IN, REFUND_OUT, TRANSFER |
status | string | Estado: PENDING, CONFIRMED, ERROR |
originalAmount | number | Monto efectivamente pagado en BRL. Antes de la confirmación, muestra el monto cobrado |
feeAmount | number | Monto de la tarifa en BRL |
finalAmount | number | Monto final en BRL |
amountPaid | number | null | Monto efectivamente pagado en BRL. null mientras el pago no se confirme |
mismatchAmount | number | null | Diferencia entre el monto cobrado y el pagado, en BRL. null sin divergencia; positivo = pagó de menos, negativo = pagó de más |
e2eId | string | null | ID End-to-end de PIX |
counterpartName | string | null | Nombre de la contraparte |
counterpartDocument | string | null | Documento de la contraparte (CPF/CNPJ) |
counterpartAccountBankCode | string | null | Código del banco de la contraparte |
counterpartAccountBranch | string | null | Sucursal de la contraparte |
counterpartAccountNumber | string | null | Número de cuenta de la contraparte |
counterpartAccountIspb | string | null | ISPB del banco de la contraparte |
counterpartAccountBankName | string | null | Nombre del banco de la contraparte |
createdAt | string | Fecha de creación (ISO 8601) |
updatedAt | string | Fecha de actualización (ISO 8601) |
processedAt | string | null | Fecha de procesamiento (ISO 8601) |
refunded | boolean | Indica si la transacción fue reembolsada (parcial o totalmente). True si hay al menos un reembolso CONFIRMED vinculado. |
partiallyRefunded | boolean | Indica si la transacción fue reembolsada parcialmente (refundedAmount > 0 y refundedAmount < amount). |
refundedAmount | number | Suma de los reembolsos CONFIRMED en reales. 0 cuando no hay reembolso o el tipo no es reembolsable. |
refundableAmount | number | Saldo aún reembolsable en reales. 0 para PENDING/ERROR o tipos no reembolsables. |
relatedTransactions | array | Transacciones relacionadas. Bidireccional: para PAYMENT/WITHDRAW lista los reembolsos (children); para REFUND_IN/REFUND_OUT lista el parent. |
{
"id": "123",
"externalId": "ext-001",
"type": "PAYMENT",
"status": "CONFIRMED",
"originalAmount": 100,
"feeAmount": 1.5,
"finalAmount": 98.5,
"amountPaid": 100,
"mismatchAmount": null,
"e2eId": "E00416968202512121343VX5Sx8fIpkY",
"counterpartName": "John Marvin",
"counterpartDocument": "12312312387",
"counterpartAccountBankCode": "001",
"counterpartAccountBranch": "0001",
"counterpartAccountNumber": "123456-7",
"counterpartAccountIspb": "00000000",
"counterpartAccountBankName": "Banco do Brasil",
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-15T10:35:00.000Z",
"processedAt": "2026-01-15T10:35:00.000Z",
"refunded": true,
"partiallyRefunded": true,
"refundedAmount": 30,
"refundableAmount": 70,
"relatedTransactions": [
{
"id": "456",
"externalId": "ext-refund-001",
"type": "REFUND_IN",
"status": "CONFIRMED",
"amount": 30,
"e2eId": "E0041696820260120ABCxyz1234567",
"createdAt": "2026-01-20T14:22:00.000Z"
}
]
}Reembolsos correlacionados
El campo relatedTransactions es bidireccional:
- Cuando consultas una transacción PAYMENT o WITHDRAW, lista todos los reembolsos vinculados (
REFUND_INoREFUND_OUT), en cualquier estado. - Cuando consultas una transacción REFUND_IN o REFUND_OUT, lista la transacción original (parent), con 1 elemento en el array.
- Para otros tipos (
TRANSFER, o transacciones sin relaciones registradas), retorna[].
Solo reembolsos con status: "CONFIRMED" entran en refundedAmount y refundableAmount. Reembolsos PENDING o ERROR aparecen en relatedTransactions pero no afectan los totales.
Errores
| Estado | Descripción |
|---|---|
| 401 | Token faltante o inválido |
| 404 | Transacción no encontrada |