Listar Transacciones

Utilice este endpoint para listar transacciones con filtros.

Entornos Disponibles

Producción

https://api.gateway.com.br/core

Endpoint

Método: GET
Endpoint: /transaction
Autenticación: Bearer token

Query Params

ℹ️ Fechas en ISO

Los campos startDate y endDate deben enviarse como ISO date string con hora.

Ejemplo:

2026-03-06T12:00:00.000Z

ℹ️ Paginación por snapshot

El snapshot no es un puntero a la "página siguiente": es un identificador fijo de la sesión de paginación, usado junto con page (que sigue siendo enviado e incrementado normalmente) para mantener los resultados consistentes incluso si se crean nuevos registros durante la navegación.

Tome el valor de snapshot de la primera respuesta (enviada sin snapshot en la primera solicitud) y reenvíe ese mismo valor, sin modificarlo, en las solicitudes de las páginas siguientes, junto con los mismos filtros y el mismo perPage usados originalmente. Si alguno de esos valores cambia mientras se reenvía un snapshot antiguo, la API devuelve un error.

Nombre	Tipo	Obligatorio	Descripción	Validaciones
`snapshot`	string	No	Identificador de la sesión de paginación (recibido en el campo `snapshot` de la primera respuesta); reenvíelo sin modificar junto con `page` en las páginas siguientes	Debe corresponder a los mismos filtros y al mismo `perPage` de la solicitud original
`startDate`	string	No	Fecha inicial del filtro	Debe ser una ISO date string con hora
`endDate`	string	No	Fecha final del filtro	Debe ser una ISO date string con hora
`status`	string[] (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	No	Lista de estados para filtrar	Debe ser un arreglo no vacío y sin duplicados
`customerEmail`	string	No	Correo electrónico del customer	Debe tener un formato de correo válido
`customerName`	string	No	Nombre del customer	Debe ser alfanumérico internacional
`customerDocument`	string	No	Documento del customer	Debe ser un CPF o CNPJ válido
`customerPhone`	string	No	Documento del customer
`id`	string (UUID v4)	No	Identificador de la transacción	Debe ser un UUID v4 válido
`endToEnd`	string	No	Identificador end-to-end de la transacción	Debe tener entre 8 y 255 caracteres
`endToEndRefund`	string	No	Identificador end-to-end del reembolso	Debe tener entre 8 y 255 caracteres
`externalCode`	string	No	Su código de referencia	Debe tener entre 8 y 255 caracteres
`paymentMethod`	string[] (enum) - `PIX`	No	Lista de métodos de pago para filtrar	Debe ser un arreglo no vacío y sin duplicados
`minAmount`	number	No	Monto mínimo de la transacción (centavos)	Debe ser entero en centavos; mínimo `1` (BRL 0.01) y máximo `10000000` (BRL 100,000.00)
`maxAmount`	number	No	Monto máximo de la transacción (centavos)	Debe ser entero en centavos; mínimo `1` (BRL 0.01) y máximo `10000000` (BRL 100,000.00); debe ser mayor o igual que `minAmount` cuando ambos se informan

Ejemplo de Solicitud

cURL
JavaScript

curl --request GET \
--url https://api.gateway.com.br/core/transaction?status=PAID&startDate=2026-03-06T00:00:00.000Z&endDate=2026-03-06T23:59:59.999Z \
--header 'Authorization: Bearer su-token-jwt'

const params = new URLSearchParams({
  startDate: '2026-03-06T00:00:00.000Z',
  endDate: '2026-03-06T23:59:59.999Z'
});
params.append('status', 'PAID');

const response = await fetch(`https://api.gateway.com.br/core/transaction?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer su-token-jwt'
  }
});
const data = await response.json();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
`totalPages`	number	Sí	Total de páginas
`currentPage`	number	Sí	Página actual
`perPage`	number	Sí	Elementos por página
`snapshot`	string	No	Identificador de la sesión de paginación; reenvíelo sin modificar en las páginas siguientes
`data`	array	Sí	Lista de transacciones

Campos del elemento en `data`

Campo	Tipo	Obligatorio	Descripción
`id`	string (UUID)	Sí	Identificador único de la transacción
`acquirerCode`	string	No	Código del adquirente
`acquirer`	string	Sí	Adquirente de la transacción
`amount`	number	Sí	Monto de la transacción (entero, en centavos)
`paymentMethod`	string (enum) - `PIX`	Sí	Método de pago
`webhookUrl`	string	No	URL de webhook configurada
`externalCode`	string	No	Su código de referencia
`paymentReceipt`	object	No	Comprobante de pago (ver Sub-Objeto `PaymentReceiptUrl`)
`refundReceipt`	object	No	Comprobante de reembolso (ver Sub-Objeto `PaymentReceiptUrl`)
`customer`	object	No	Datos del cliente (ver Sub-Objeto `Customer`)
`seller`	object	No	Datos del vendedor (ver Sub-Objeto `Seller`)
`isInfoProduct`	boolean	Sí	Indicador de productos digitales o físicos
`address`	object	No	Dirección del cliente (ver Sub-Objeto `Address`)
`items`	object[]	No	Lista de productos (ver Sub-Objeto `Item`)
`metadata`	object	No	Metadatos
`createdAt`	string (ISO)	Sí	Fecha de creación
`status`	string (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	Sí	PENDING: Transacción creada, en espera de procesamiento PIX_QRCODE_GENERATED: QR Code PIX generado, en espera de pago PAID: Transacción pagada PROCESSING_REFUND: Reembolso en procesamiento PROCESSING_INFRACTION: Infracción en procesamiento REFUNDED: Transacción reembolsada INFRACTION: Transacción reembolsada (MED) FAILED: Error en el procesamiento BLOCKED: Bloqueada por la apertura de un MED
`statusHistory`	array	Sí	Historial de estados (ver Sub-Objeto `StatusHistory`)
`updatedAt`	string (ISO)	Sí	Fecha de la última actualización
`amountPaid`	number	No	Monto efectivamente pagado (entero, en centavos)
`paymentDate`	string (ISO)	No	Fecha de pago
`infractionDate`	string (ISO)	No	Fecha de la infracción
`infractionAmount`	number	No	Monto de la infracción (entero, en centavos)
`refundDate`	string (ISO)	No	Fecha del reembolso
`refundAmount`	number	No	Monto del reembolso (entero, en centavos)
`pixResponse`	object	No	Datos del PIX (ver Sub-Objeto `PixResponse`)
`errorMessage`	string	No	Mensaje de error
`errorMessageRefund`	string	No	Mensaje de error del reembolso
`endToEnd`	string	No	Identificador end-to-end de la transacción
`endToEndRefund`	string	No	Identificador end-to-end del reembolso
`payer`	object	No	Datos del pagador (ver Sub-Objeto `AccountHolder`)
`receiver`	object	No	Datos del receptor (ver Sub-Objeto `AccountHolder`)
`feeAmount`	number	No	Monto de la comisión

Sub-Objetos

Customer

Campo	Tipo	Obligatorio	Descripción
`ip`	string	No	IP
`name`	string	Sí	Nombre
`email`	string	No	Correo electrónico
`document`	object	Sí	Documento (ver Sub-Objeto `DocumentVo`)
`landline`	string	No	Teléfono fijo
`mobilePhone`	string	No	Teléfono celular

Seller

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre
`document`	object	Sí	Documento (ver Sub-Objeto `DocumentVo`)

DocumentVo

Campo	Tipo	Obligatorio	Descripción
`value`	string	Sí	Documento
`type`	string (enum) - `CPF`, `CNPJ`	Sí	Tipo del documento

Address

Campo	Tipo	Obligatorio	Descripción
`postalCode`	string	Sí	CEP de Brasil
`number`	string	Sí	Número de la casa
`street`	string	Sí	Nombre de la calle
`neighborhood`	string	Sí	Nombre de la colonia o barrio
`city`	string	Sí	Nombre de la ciudad
`state`	string	Sí	Nombre o sigla del estado
`country`	string	Sí	Nombre del país
`complement`	string	No	Información adicional

Item

Campo	Tipo	Obligatorio	Descripción
`title`	string	Sí	Título
`unitPrice`	number	Sí	Monto del artículo (entero, en centavos)
`quantity`	number	Sí	Cantidad de este artículo
`description`	string	No	Información adicional

StatusHistory (elemento)

Campo	Tipo	Obligatorio	Descripción
`status`	string (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	Sí	Estado de la transacción
`date`	string (ISO)	Sí	Fecha del estado
`durationInMilliseconds`	number	Sí	Duración del estado en milisegundos

PixResponse

Campo	Tipo	Obligatorio	Descripción
`uri`	string	Sí	Código de copiar y pegar del QR Code
`qrCodeBase64`	string	Sí	Imagen del QR Code
`expirationDate`	string	Sí	Fecha de expiración del QR Code

AccountHolder

Campo	Tipo	Obligatorio	Descripción
`type`	string (enum) - `PF`, `PJ`	Sí	Tipo de titular
`name`	string	Sí	Nombre del titular
`document`	string	Sí	Documento del titular
`bankAccount`	object	Sí	Datos bancarios (ver Sub-Objeto `BankAccount`)
`pix`	object	Sí	Clave PIX del titular (ver Sub-Objeto `PixKeyVo`)

BankAccount

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	Tipo de cuenta
`digit`	string	Sí	Dígito de la cuenta
`ispb`	string	Sí	ISPB del banco

PaymentReceiptUrl

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	URL del comprobante
`expirationDate`	string (ISO)	Sí	Fecha de expiración del comprobante

Ejemplo de Respuesta

Datos enmascarados

Los valores sensibles pueden estar enmascarados con ***.

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-436251480000",
      "acquirerCode": "ACQ-123",
      "acquirer": "ACQUIRER_EXEMPLO",
      "amount": 500,
      "paymentMethod": "PIX",
      "webhookUrl": "https://sua-api.com/webhooks/transaction",
      "externalCode": "TRANSACTION-123",
      "paymentReceipt": {
        "url": "https://files.exemplo.com.br/receipts/transaction-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "refundReceipt": {
        "url": "https://files.exemplo.com.br/receipts/transaction-refund-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "customer": {
        "ip": "123123123123",
        "name": "Customer",
        "email": "customer@gmail.com",
        "document": {
          "value": "***123123**",
          "type": "CPF"
        },
        "landline": "12123451234",
        "mobilePhone": "12123451234"
      },
      "seller": {
        "name": "Seller",
        "document": {
          "value": "***123123**",
          "type": "CPF"
        }
      },
      "isInfoProduct": false,
      "address": {
        "postalCode": "54753-800",
        "number": "155",
        "street": "Rua Santa Mariana",
        "neighborhood": "São Pedro",
        "city": "Camaragibe",
        "state": "Pernambuco",
        "country": "Brazil",
        "complement": "Casa Azul"
      },
      "items": [
        {
          "title": "Fone Bluetooth PulseWave X200",
          "unitPrice": 500,
          "quantity": 1,
          "description": "Fone de ouvido sem fio com cancelamento ativo de ruído, bateria de 30h e microfone embutido. Compatível com Android e iOS."
        }
      ],
      "metadata": {
        "moeda": "BRL",
        "autorizacao": "A1B2C3",
        "status": "aprovada"
      },
      "createdAt": "2026-03-06T12:49:04.681Z",
      "status": "REFUNDED",
      "statusHistory": [
        {
          "status": "PENDING",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 1000
        },
        {
          "status": "PIX_QRCODE_GENERATED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "PAID",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "PROCESSING_REFUND",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 7000
        },
        {
          "status": "REFUNDED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 5000
        }
      ],
      "updatedAt": "2026-03-06T12:49:04.681Z",
      "amountPaid": 500,
      "paymentDate":  "2026-03-06T12:49:04.681Z",
      "infractionDate": "2026-03-06T13:49:04.681Z",
      "infractionAmount": 500,
      "refundDate": "2026-03-06T14:49:04.681Z",
      "refundAmount": 500,
      "pixResponse": {
        "uri": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
        "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
        "expirationDate": "2026-03-06T12:49:04.681Z"
      },
      "errorMessage": null,
      "errorMessageRefund": null,
      "endToEnd": "0123456789",
      "endToEndRefund": "0123456789-REFUND",
      "payer": {
        "type": "PF",
        "name": "Fulano de Tal",
        "document": "***456789**",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "7",
          "ispb": "12345678"
        },
        "pix": {
          "key": "12345678910",
          "type": "CPF"
        }
      },
      "receiver": {
        "type": "PJ",
        "name": "Empresa Exemplo LTDA",
        "document": "12345678000199",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "0",
          "ispb": "12345678"
        },
        "pix": {
          "key": "contato@exemplo.com",
          "type": "EMAIL"
        }
      },
      "feeAmount": 150
    }
  ]
}

Errores Posibles

Código	Descripción	Solución
401	Credenciales inválidas	Verifique sus credenciales
403	Sin permiso/autorización	Contacte al soporte
422	Datos inválidos o faltantes	Verifique el formato de los datos
422	Validaciones	Contacte al soporte
500	Error interno	Contacte al soporte

Entornos Disponibles​

Endpoint​

Query Params​

Ejemplo de Solicitud​

Respuesta Exitosa​

Campos del elemento en data​

Sub-Objetos​

Customer​

Seller​

DocumentVo​

Address​

Item​

StatusHistory (elemento)​

PixResponse​

AccountHolder​

BankAccount​

PaymentReceiptUrl​

Ejemplo de Respuesta​

Errores Posibles​