查询交易

使用此端点通过 id 查询某一笔具体的交易。

可用环境

生产环境

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

端点

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

路径参数

名称	类型	必填	说明	校验规则
`id`	string (UUID)	是	交易的标识	必须为有效的 UUID

请求示例

cURL
JavaScript

curl --request GET \
--url https://api.gateway.com.br/core/transaction/553e8400-e29b-41d4-a716-436251480000 \
--header 'Authorization: Bearer your-jwt-token'

const response = await fetch('https://api.gateway.com.br/core/transaction/553e8400-e29b-41d4-a716-436251480000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});
const data = await response.json();

成功响应

字段	类型	必填	说明
`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)	是	凭证的过期日期

响应示例

数据脱敏

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

{
  "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	无权限或未授权	请联系技术支持
404	未找到记录	请检查所传入的 `id`
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
500	内部错误	请联系技术支持

可用环境​

端点​

路径参数​

请求示例​

成功响应​

子对象​

Customer​

Seller​

DocumentVo​

Address​

Item​

StatusHistory（列表项）​

PixResponse​

AccountHolder​

BankAccount​

PaymentReceiptUrl​

响应示例​

可能的错误​

可用环境

端点

路径参数

请求示例

成功响应

子对象

Customer

Seller

DocumentVo

Address

Item

StatusHistory（列表项）

PixResponse

AccountHolder

BankAccount

PaymentReceiptUrl

响应示例

可能的错误