被 Bacen 的缩写或响应中返回的字段卡住了？这里是集成日常中出现的术语、状态和代码，全部用中文解释。
| 术语 | 定义 |
|---|
| Pix | 巴西中央银行的即时支付系统。全天候 24/7 运行，秒级结算。 |
| DICT | 交易账户标识符目录。Bacen 的数据库，用于将 Pix 密钥映射到账户。付款前请先查询。 |
| EMV / BR Code | Pix 使用的国际标准，用于生成复制粘贴 QR Code。以 00020126... 开头的字符串。 |
| 动态 QR | 带有 id 且（可选）每笔收款金额的 QR Code。 |
| 静态 QR | 可重复使用的 QR Code，同一个代码用于多笔付款。 |
| MED | 特殊退款机制。Bacen 用于在欺诈或错误情况下对 Pix 提出异议的流程。在 PayZu 中会变成 infraction。 |
| Bearer token | 在 header Authorization: Bearer SEU_TOKEN 中发送的认证令牌。PayZu 唯一的认证方式。 |
| Callback / Webhook | 当交易状态变化时，PayZu 向您的 callbackUrl 发送的 POST。最多重试 40 次，采用退避策略。 |
| 幂等性 | 保证多次执行相同操作与执行一次具有相同效果。创建时请使用 clientReference。 |
| 指数退避 | 一种重试策略，重试间隔时间翻倍（1s、2s、4s、8s）。PayZu 使用此策略，并推荐您在 5xx/429 重试时也使用。 |
| 抖动 (Jitter) | 添加到退避时间的随机变化，用于避免"惊群效应"（客户端同时发起请求）。 |
| 值 | 含义 |
|---|
DEPOSIT | Pix 收款，资金进入您的账户。 |
WITHDRAW | Pix 付款，资金流出到 Pix 密钥或 QR Code。 |
COMMISSION | 佣金入账记录。可能出现在列表和报表中。 |
| 值 | 含义 |
|---|
PIX | 通过 Pix 结算的操作。 |
BANK_SLIP | 通过 boleto 的操作。 |
INTERNAL_TRANSFER | PayZu 账户之间的即时转账。每一方到达时 type 为 WITHDRAW（付款方）或 DEPOSIT（收款方）。 |
状态因类型而异。完整列表：
| 状态 | 含义 |
|---|
PENDING | 等待付款（收款）或等待处理（Pix 付款）。 |
COMPLETED | 成功完成。收款时：客户已付款。Pix 付款时：资金已发出。 |
CANCELED | 在完成前被取消（手动或按规则）。 |
WAITING_FOR_REFUND | 等待退款处理（通常在 MED 被接受后）。 |
REFUNDED | 已退款，金额已归还给付款方。 |
EXPIRED | 收款在未付款情况下过期（超过 expiresIn）。 |
ERROR | 操作过程中出现技术错误。请查看 payload 中的 cancellationReason。 |
| 值 | 含义 |
|---|
PENDING | 退款在处理队列中。 |
COMPLETED | 退款已处理，金额已归还。 |
CANCELED | 退款在完成前被取消。 |
五种密钥类型（cpf、cnpj、phone、email、evp），每种的格式和示例请参见 Pix 密钥类型。
| 值 | 描述 |
|---|
WAITING_PSP | 等待提供方响应。 |
OPEN | Infraction 已激活并正在分析中。 |
ACKNOWLEDGED | 已被机构确认。 |
DEFENDED | 抗辩已提交。 |
ANSWERED | 已提供补充信息。 |
WAITING_ADJUSTMENTS | 等待文件资料。 |
CLOSED | 已解决并有最终决定（请查看 analysisResult）。 |
CANCELLED | 在解决前被取消。 |
| 值 | 描述 |
|---|
REFUND_REQUEST | 标准退款请求。 |
FRAUD | 与安全相关的投诉。 |
REFUND_CANCELLED | 取消先前的退款。 |
| 值 | 描述 |
|---|
AGREED | Infraction 被接受。将处理退款。 |
DISAGREED | Infraction 被拒绝。不退款，交易保留。 |
| 值 | 描述 |
|---|
DEBITED_PARTICIPANT | 付款方机构发起。 |
CREDITED_PARTICIPANT | 收款方机构发起。 |
我们保留英文名称，因为 JSON 中就是这样传输的。
| 字段 | 用途 |
|---|
id | PayZu 中交易的唯一标识符。环境前缀 + UTC 日期（YYYYMMDD）+ 随机片段 + 由账户派生的 6 位数字。请视为不透明：用于确定日期或排序时，请使用 createdAt 和 paidAt，切勿切分 id。 |
clientReference | 由 您 定义的外部标识符。在每个 callback 中返回。最多 64 个字符。 |
virtualAccount | 用于多租户（门店、分支机构、marketplace）的虚拟子账户（最多 50 个字符）。在 callback 中返回。 |
endToEndId | Bacen 中操作的唯一标识符。格式为 E + 32 个字符。在争议中有用。 |
requestId | PayZu 中调用的唯一 ID。出现在所有错误响应（4xx 和 5xx）中。请始终记录并在开启支持时发送，调查会直接追踪。参见 错误格式。 |
accountNumber | PayZu 账户号（6 位数字）。在内部转账和交易 payload 中标识账户。 |
| 字段 | 用途 |
|---|
amount | 以**巴西雷亚尔（BRL）**为单位的金额。例：10.90 表示 R$ 10,90。 |
serviceFeeCharged | PayZu 就该操作收取的费用，以雷亚尔为单位。 |
| 字段 | 用途 |
|---|
qrCodeText | Pix 复制粘贴代码（EMV BR Code）。在带复制按钮的输入框中使用。 |
qrCodeUrl | 将 QR 渲染为 PNG 的公共 URL。可直接在 <img> 中使用。 |
qrCodeBase64 | Base64 格式的 QR Code 图像。 |
generatedName | 与收款相关的引用名称。 |
generatedDocument | 与收款相关的 CPF 或 CNPJ。 |
generatedEmail | 与收款关联的邮箱。 |
expiresIn | 收款过期时间（秒）。最大 172000（47 小时）。 |
| 字段 | 用途 |
|---|
payerName | 付款方姓名（付款后在 callback 中返回）。 |
payerDocument | 付款方的 CPF/CNPJ。 |
payerInstitutionIspb | 付款方银行的 ISPB（8 位数字）。 |
payerInstitutionName | 付款方银行名称。 |
payerAccountNumber | 付款方的 PayZu 账户（Pix 付款和内部转账中）。 |
| 字段 | 用途 |
|---|
receiverName | 收款方姓名（Pix 付款中）。 |
receiverDocument | 收款方的 CPF/CNPJ。 |
receiverInstitutionIspb | 收款方银行的 ISPB。 |
receiverInstitutionName | 收款方银行名称。 |
receiverAccountNumber | 收款方的 PayZu 账户（收款和内部转账中）。 |
| 字段 | 用途 |
|---|
pixKey | 收款方的 Pix 密钥。格式取决于 pixType。 |
pixType | 密钥类型：cpf、cnpj、phone、email、evp。 |
withdrawPixKey | Pix 付款中使用的密钥（在 callback 中）。 |
withdrawPixType | Pix 付款中使用的密钥类型。 |
| 字段 | 用途 |
|---|
paidAt | 付款时间戳（ISO 8601）。COMPLETED 后出现。 |
cancellationReason | 取消原因。 |
refundEndToEndId | 退款的 EndToEnd ID。 |
refundAmount | 退款金额。 |
refundStatus | 退款状态：PENDING、COMPLETED、CANCELED。 |
refundReason | 退款原因。 |
refundDescription | 退款描述。 |
refundedAt | 退款时间戳（ISO 8601）。 |
| 字段 | 用途 |
|---|
callbackUrl | PayZu 发送交易更新的 URL。 |
description | 交易的自由文本；在内部转账中，最多 500 个字符。 |
createdAt | 交易创建时间戳（ISO 8601）。 |
updatedAt | 最后更新时间（ISO 8601）。 |
infraction | 当交易变成 MED 争议时，callback 中出现的对象。 |
完整的 HTTP 代码列表以及如何对每个代码作出反应，请参见 错误代码。
| 缩写 | 全称 |
|---|
| Bacen | 巴西中央银行。 |
| PSP | 支付服务提供商。每家银行/金融科技公司都是一个 PSP。 |
| ISPB | 巴西支付系统标识符。识别每个 PSP 的 8 位代码。 |
| SPI | 即时支付系统。处理 Pix 的 Bacen 基础设施。 |
| CACC | 活期账户（Bacen 使用的 ISO 20022 命名法）。 |
| SVGS | 储蓄账户。 |
| TRAN | 支付账户（过渡性）。 |
| CUID | PayZu 在内部资源中使用的字符串唯一标识符（例：infraction 的 id）。 |
