查询交易列表

使用此端点按筛选条件查询交易列表。

可用环境

生产环境

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

端点

方法：GET
端点：/transaction
认证方式：Bearer token

查询参数

ℹ️ 使用 ISO 日期

startDate 和 endDate 必须以带时间的 ISO date string 格式传入。

示例：

2026-03-06T12:00:00.000Z

ℹ️ snapshot 分页

snapshot 并不是指向“下一页”的指针：它是分页会话的固定标识，与 page（仍需正常传入并递增）配合使用，即使在翻页过程中产生了新记录，也能保持结果一致。

请从第一次响应中取得 snapshot 的值（首次请求不传 snapshot），并在后续各页的请求中原样重发该值，同时保持与最初相同的筛选条件和相同的 perPage。如果在重发旧 snapshot 时其中任一值发生变化，API 将返回错误。

名称	类型	必填	说明	校验规则
`snapshot`	string	否	分页会话的标识（取自第一次响应的 `snapshot` 字段）；在后续页中与 `page` 一起原样重发	必须与原始请求的筛选条件及 `perPage` 一致
`startDate`	string	否	筛选的起始日期	必须为带时间的 ISO date string
`endDate`	string	否	筛选的结束日期	必须为带时间的 ISO date string
`status`	string[] (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	否	用于筛选的状态列表	必须为非空且不含重复项的数组
`customerEmail`	string	否	customer 的电子邮箱	必须为有效的邮箱格式
`customerName`	string	否	customer 的姓名	必须为国际通用的字母数字字符
`customerDocument`	string	否	customer 的证件号	必须为有效的 CPF 或 CNPJ
`customerPhone`	string	否	customer 的证件号
`id`	string (UUID v4)	否	交易的标识	必须为有效的 UUID v4
`endToEnd`	string	否	交易的 end-to-end 标识	长度须在 8 到 255 个字符之间
`endToEndRefund`	string	否	退款的 end-to-end 标识	长度须在 8 到 255 个字符之间
`externalCode`	string	否	您的参考编号	长度须在 8 到 255 个字符之间
`paymentMethod`	string[] (enum) - `PIX`	否	用于筛选的支付方式列表	必须为非空且不含重复项的数组
`minAmount`	number	否	交易的最小金额（分）	必须为以分为单位的整数；最小 `1`（R$0.01），最大 `10000000`（R$100,000.00）
`maxAmount`	number	否	交易的最大金额（分）	必须为以分为单位的整数；最小 `1`（R$0.01），最大 `10000000`（R$100,000.00）；同时传入两者时，必须大于或等于 `minAmount`

请求示例

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

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();

成功响应

字段	类型	必填	说明
`totalPages`	number	是	总页数
`currentPage`	number	是	当前页
`perPage`	number	是	每页条数
`snapshot`	string	否	分页会话的标识；在后续页中原样重发
`data`	array	是	交易列表

`data` 中每一项的字段

字段	类型	必填	说明
`id`	string (UUID)	是	交易的唯一标识
`acquirerCode`	string	否	收单机构代码
`acquirer`	string	是	交易的收单机构
`amount`	number	是	交易金额（整数，以分为单位）
`paymentMethod`	string (enum) - `PIX`	是	支付方式
`webhookUrl`	string	否	已配置的 webhook URL
`externalCode`	string	否	您的参考编号
`paymentReceipt`	object	否	支付凭证（参见子对象 `PaymentReceiptUrl`）
`refundReceipt`	object	否	退款凭证（参见子对象 `PaymentReceiptUrl`）
`customer`	object	否	客户信息（参见子对象 `Customer`）
`seller`	object	否	卖方信息（参见子对象 `Seller`）
`isInfoProduct`	boolean	是	标识商品为数字商品或实物商品
`address`	object	否	客户地址（参见子对象 `Address`）
`items`	object[]	否	商品列表（参见子对象 `Item`）
`metadata`	object	否	元数据
`createdAt`	string (ISO)	是	创建日期
`status`	string (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	是	PENDING：交易已创建，等待处理 PIX_QRCODE_GENERATED：PIX 二维码已生成，等待付款 PAID：交易已支付 PROCESSING_REFUND：退款处理中 PROCESSING_INFRACTION：违规处理中 REFUNDED：交易已退款 INFRACTION：交易已退款（MED） FAILED：处理出错 BLOCKED：因开启 MED 而被冻结
`statusHistory`	array	是	状态历史（参见子对象 `StatusHistory`）
`updatedAt`	string (ISO)	是	最后更新日期
`amountPaid`	number	否	实际支付金额（整数，以分为单位）
`paymentDate`	string (ISO)	否	支付日期
`infractionDate`	string (ISO)	否	违规日期
`infractionAmount`	number	否	违规金额（整数，以分为单位）
`refundDate`	string (ISO)	否	退款日期
`refundAmount`	number	否	退款金额（整数，以分为单位）
`pixResponse`	object	否	PIX 数据（参见子对象 `PixResponse`）
`errorMessage`	string	否	错误信息
`errorMessageRefund`	string	否	退款的错误信息
`endToEnd`	string	否	交易的 end-to-end 标识
`endToEndRefund`	string	否	退款的 end-to-end 标识
`payer`	object	否	付款方信息（参见子对象 `AccountHolder`）
`receiver`	object	否	收款方信息（参见子对象 `AccountHolder`）
`feeAmount`	number	否	手续费金额

子对象

Customer

字段	类型	必填	说明
`ip`	string	否	IP
`name`	string	是	姓名
`email`	string	否	电子邮箱
`document`	object	是	证件信息（参见子对象 `DocumentVo`）
`landline`	string	否	固定电话
`mobilePhone`	string	否	手机号码

Seller

字段	类型	必填	说明
`name`	string	是	姓名
`document`	object	是	证件信息（参见子对象 `DocumentVo`）

DocumentVo

字段	类型	必填	说明
`value`	string	是	证件号
`type`	string (enum) - `CPF`, `CNPJ`	是	证件类型

Address

字段	类型	必填	说明
`postalCode`	string	是	巴西的 CEP 邮编
`number`	string	是	门牌号
`street`	string	是	街道名称
`neighborhood`	string	是	街区名称
`city`	string	是	城市名称
`state`	string	是	州/省的名称或简称
`country`	string	是	国家名称
`complement`	string	否	补充信息

Item

字段	类型	必填	说明
`title`	string	是	标题
`unitPrice`	number	是	商品金额（整数，以分为单位）
`quantity`	number	是	该商品的数量
`description`	string	否	补充信息

StatusHistory（列表项）

字段	类型	必填	说明
`status`	string (enum) - `PENDING`, `PIX_QRCODE_GENERATED`, `PAID`, `PROCESSING_REFUND`, `PROCESSING_INFRACTION`, `REFUNDED`, `INFRACTION`, `FAILED`, `BLOCKED`	是	交易状态
`date`	string (ISO)	是	该状态的日期
`durationInMilliseconds`	number	是	该状态的持续时长（毫秒）

PixResponse

字段	类型	必填	说明
`uri`	string	是	二维码的复制粘贴代码
`qrCodeBase64`	string	是	二维码图片
`expirationDate`	string	是	二维码的过期日期

AccountHolder

字段	类型	必填	说明
`type`	string (enum) - `PF`, `PJ`	是	持有人类型
`name`	string	是	持有人姓名
`document`	string	是	持有人证件号
`bankAccount`	object	是	银行信息（参见子对象 `BankAccount`）
`pix`	object	是	持有人的 PIX 密钥（参见子对象 `PixKeyVo`）

BankAccount

字段	类型	必填	说明
`type`	string	是	账户类型
`digit`	string	是	账户校验位
`ispb`	string	是	银行的 ISPB

PaymentReceiptUrl

字段	类型	必填	说明
`url`	string	是	凭证的 URL
`expirationDate`	string (ISO)	是	凭证的过期日期

响应示例

数据脱敏

敏感信息可能以 *** 脱敏显示。

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

可能的错误

状态码	说明	处理方式
401	凭据无效	请检查您的凭据
403	无权限或未授权	请联系技术支持
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
500	内部错误	请联系技术支持

可用环境​

端点​

查询参数​

请求示例​

成功响应​

data 中每一项的字段​

子对象​

Customer​

Seller​

DocumentVo​

Address​

Item​

StatusHistory（列表项）​

PixResponse​

AccountHolder​

BankAccount​

PaymentReceiptUrl​

响应示例​

可能的错误​