List Transactions

Use this endpoint to list transactions with filters.

Available Environments

Production

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

Endpoint

• Method: GET
• Endpoint: /transaction
• Authentication: Bearer token

Query Params

ℹ️ Dates in ISO

The startDate and endDate fields must be sent as an ISO date string with time.

Example:

• 2026-03-06T12:00:00.000Z

ℹ️ Snapshot pagination

The snapshot is not a pointer to the "next page": it is a fixed identifier of the pagination session, used together with page (which is still sent and incremented normally) to keep the results consistent even if new records are created while you navigate.

Take the snapshot value from the first response (sent without a snapshot on the first request) and resend that same value, unchanged, on the requests for the following pages, along with the same filters and the same perPage used originally. If any of those values changes while an old snapshot is resent, the API returns an error.

Name	Type	Required	Description	Validations
snapshot	string	No	Identifier of the pagination session (received in the snapshot field of the first response); resend it unchanged along with page on the following pages	Must match the same filters and the same perPage of the original request
startDate	string	No	Start date of the filter	Must be an ISO date string with time
endDate	string	No	End date of the filter	Must be an ISO date string with time
status	string[] (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	No	List of statuses to filter by	Must be a non-empty array with no duplicates
customerEmail	string	No	E-mail of the customer	Must have a valid e-mail format
customerName	string	No	Name of the customer	Must be international alphanumeric
customerDocument	string	No	Document of the customer	Must be a valid CPF or CNPJ
customerPhone	string	No	Document of the customer
id	string (UUID v4)	No	Transaction identifier	Must be a valid UUID v4
endToEnd	string	No	End-to-end identifier of the transaction	Must be between 8 and 255 characters
endToEndRefund	string	No	End-to-end identifier of the refund	Must be between 8 and 255 characters
externalCode	string	No	Your reference code	Must be between 8 and 255 characters
paymentMethod	string[] (enum) - PIX	No	List of payment methods to filter by	Must be a non-empty array with no duplicates
minAmount	number	No	Minimum transaction amount (cents)	Must be an integer in cents; minimum 1 (R$0.01) and maximum 10000000 (R$100,000.00)
maxAmount	number	No	Maximum transaction amount (cents)	Must be an integer in cents; minimum 1 (R$0.01) and maximum 10000000 (R$100,000.00); must be greater than or equal to minAmount when both are provided

Request Example

cURL

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 your-jwt-token'

JavaScript

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 your-jwt-token'
  }
});
const data = await response.json();

Success Response

Field	Type	Required	Description
totalPages	number	Yes	Total pages
currentPage	number	Yes	Current page
perPage	number	Yes	Items per page
snapshot	string	No	Identifier of the pagination session; resend it unchanged on the following pages
data	array	Yes	List of transactions

Fields of the item in data

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the transaction
acquirerCode	string	No	Acquirer code
acquirer	string	Yes	Acquirer of the transaction
amount	number	Yes	Transaction amount (integer, in cents)
paymentMethod	string (enum) - PIX	Yes	Payment method
webhookUrl	string	No	Configured webhook URL
externalCode	string	No	Your reference code
paymentReceipt	object	No	Payment receipt (see Sub-Object PaymentReceiptUrl)
refundReceipt	object	No	Refund receipt (see Sub-Object PaymentReceiptUrl)
customer	object	No	Customer data (see Sub-Object Customer)
seller	object	No	Seller data (see Sub-Object Seller)
isInfoProduct	boolean	Yes	Flag for digital or physical products
address	object	No	Customer address (see Sub-Object Address)
items	object[]	No	List of products (see Sub-Object Item)
metadata	object	No	Metadata
createdAt	string (ISO)	Yes	Creation date
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Yes	PENDING: Transaction created, awaiting processing PIX_QRCODE_GENERATED: PIX QR Code generated, awaiting payment PAID: Transaction paid PROCESSING_REFUND: Refund being processed PROCESSING_INFRACTION: Infraction being processed REFUNDED: Transaction refunded INFRACTION: Transaction refunded (MED) FAILED: Processing error BLOCKED: Blocked because a MED was opened
statusHistory	array	Yes	Status history (see Sub-Object StatusHistory)
updatedAt	string (ISO)	Yes	Last update date
amountPaid	number	No	Amount actually paid (integer, in cents)
paymentDate	string (ISO)	No	Payment date
infractionDate	string (ISO)	No	Infraction date
infractionAmount	number	No	Infraction amount (integer, in cents)
refundDate	string (ISO)	No	Refund date
refundAmount	number	No	Refund amount (integer, in cents)
pixResponse	object	No	PIX data (see Sub-Object PixResponse)
errorMessage	string	No	Error message
errorMessageRefund	string	No	Refund error message
endToEnd	string	No	End-to-end identifier of the transaction
endToEndRefund	string	No	End-to-end identifier of the refund
payer	object	No	Payer data (see Sub-Object AccountHolder)
receiver	object	No	Receiver data (see Sub-Object AccountHolder)
feeAmount	number	No	Fee amount

Sub-Objects

Customer

Field	Type	Required	Description
ip	string	No	IP
name	string	Yes	Name
email	string	No	E-mail
document	object	Yes	Document (see Sub-Object DocumentVo)
landline	string	No	Landline phone
mobilePhone	string	No	Mobile phone

Seller

Field	Type	Required	Description
name	string	Yes	Name
document	object	Yes	Document (see Sub-Object DocumentVo)

DocumentVo

Field	Type	Required	Description
value	string	Yes	Document
type	string (enum) - CPF, CNPJ	Yes	Document type

Address

Field	Type	Required	Description
postalCode	string	Yes	Brazilian CEP
number	string	Yes	House number
street	string	Yes	Street name
neighborhood	string	Yes	Neighborhood name
city	string	Yes	City name
state	string	Yes	State name or abbreviation
country	string	Yes	Country name
complement	string	No	Additional information

Item

Field	Type	Required	Description
title	string	Yes	Title
unitPrice	number	Yes	Item amount (integer, in cents)
quantity	number	Yes	Quantity of this item
description	string	No	Additional information

StatusHistory (item)

Field	Type	Required	Description
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Yes	Transaction status
date	string (ISO)	Yes	Date of the status
durationInMilliseconds	number	Yes	Duration of the status in milliseconds

PixResponse

Field	Type	Required	Description
uri	string	Yes	Copy-and-paste code of the QR Code
qrCodeBase64	string	Yes	QR Code image
expirationDate	string	Yes	Expiration date of the QR Code

AccountHolder

Field	Type	Required	Description
type	string (enum) - PF, PJ	Yes	Holder type
name	string	Yes	Holder name
document	string	Yes	Holder document
bankAccount	object	Yes	Bank data (see Sub-Object BankAccount)
pix	object	Yes	PIX key of the holder (see Sub-Object PixKeyVo)

BankAccount

Field	Type	Required	Description
type	string	Yes	Account type
digit	string	Yes	Account check digit
ispb	string	Yes	ISPB of the bank

PaymentReceiptUrl

Field	Type	Required	Description
url	string	Yes	URL of the receipt
expirationDate	string (ISO)	Yes	Expiration date of the receipt

Response Example

Masked data

Sensitive values may be masked with ***.

{
  "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
    }
  ]
}

Possible Errors

Code	Description	Solution
401	Invalid credentials	Check your credentials
403	No permission/authorization	Contact support
422	Invalid or missing data	Check the format of the data
422	Validations	Contact support
500	Internal error	Contact support