概念
概述
PayZu Processamento 是一个 REST API,包含 29 个 endpoint,分为 7 个组。所有通信通过 HTTPS 以 JSON 格式进行,使用 Bearer token。金额始终以**雷亚尔(BRL)**为单位,而非分。
7 个 endpoint 组
| 组 | Endpoints | 功能说明 |
|---|---|---|
| Pix 收款 | 4 | 创建和查询 Pix 收款(存款)、QR Code、回执。 |
| 提现 | 6 | 通过 Pix 密钥或 QR Code 发送 Pix、DICT 查询、QR 读取。 |
| 内部转账 | 2 | 在 PayZu 账户之间即时划转余额。 |
| 账户 | 2 | 资料、权限、限额和余额。 |
| 报表 | 6 | 列出交易、异步生成 CSV。 |
| Callbacks | 4 | 检查和重新发送 webhook。 |
| 争议(MED) | 5 | 付款方发起的 Pix 争议及抗辩提交。 |
交易模型
PayZu 中的每一笔资金流动都以交易形式表示。无论是收款、提现还是内部转账,其基本结构都相同。
主要字段
| 字段 | 类型 | 用途 |
|---|---|---|
id | string | PayZu 中交易的唯一标识符。 |
type | string | DEPOSIT、WITHDRAW 或 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(2025-11-23T10:46:26.986Z) |
| 编码 | UTF-8 |
| 分页 | page + limit,附带 hasNextPage 标志 |
| Webhooks | 向 callbackUrl 发送 POST,最多重试 72 次 |