第一次调用前的思维导图：这套 API 覆盖哪些能力、操作如何分组，以及在 PayZu 里一笔交易意味着什么，全部以雷亚尔计价、走 HTTPS。
概述
PayZu Processamento 是一个 REST API，endpoint 按功能分组。所有通信通过 HTTPS 以 JSON 格式进行，使用 Bearer token。金额始终以**雷亚尔(BRL)**为单位。
Endpoint 分组
完整的分组清单及每组包含的 endpoints 见 API 参考。
交易模型
PayZu 中的每一笔资金流动都以交易形式表示。无论是收款、Pix 付款还是内部转账,其基本结构都相同。
主要字段
| 字段 | 类型 | 用途 |
|---|---|---|
id | string | PayZu 中交易的唯一标识符。 |
type | string | DEPOSIT、WITHDRAW 或 COMMISSION。 |
method | string | PIX、BANK_SLIP 或 INTERNAL_TRANSFER。 |
status | string | 当前状态。最常见:PENDING、COMPLETED、REFUNDED、EXPIRED、ERROR。 |
amount | number | 金额,以**雷亚尔(BRL)**为单位。例如:10.90 表示 R$ 10,90。 |
clientReference | string | 您的外部标识符。每个 callback 都会返回。用于幂等性和查询。 |
virtualAccount | string | 虚拟子账户(最多 50 字符)。用于多租户场景(门店、分支机构、marketplace)。 |
callbackUrl | string | 通过 webhook 接收状态更新的 URL。 |
endToEndId | string | Bacen 中操作的唯一标识符。在争议中用于追溯。 |
所有字段的详细说明见术语表。
典型生命周期
每种类型的完整状态请参见各 endpoint 的参考文档。快速查阅请见术语表 · 交易状态。
API 约定
| 项目 | 值 |
|---|---|
| Base URL | https://api.payzu.processamento.com/v1 |
| 认证 | Authorization: Bearer SEU_TOKEN |
| Content-Type | application/json(每次调用必需) |
| 金额 | 以雷亚尔(BRL)为单位,绝不用分 |
| 日期 | ISO 8601(2026-08-11T10:46:26.986Z) |
| 编码 | UTF-8 |
| 分页 | page + limit;响应外层结构因路由而异(详情) |
| Webhooks | 向 callbackUrl 发送 POST,最多重试 40 次 |