# 术语表 (/zh/docs/pix-processamento/glossary)
## 通用概念 [#通用概念]
| 术语 | 定义 |
| ---------------------- | ------------------------------------------------------------------ |
| **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)** | 添加到退避时间的随机变化，用于避免"惊群效应"（客户端同时发起请求）。 |
## 交易类型 (`type`) [#交易类型-type]
| 值 | 含义 |
| ------------ | ----------------------------- |
| `DEPOSIT` | Pix 收款，资金进入您的账户。 |
| `WITHDRAW` | Pix 付款，资金流出到 Pix 密钥或 QR Code。 |
| `COMMISSION` | 佣金入账记录。可能出现在列表和报表中。 |
## 交易方式 (`method`) [#交易方式-method]
| 值 | 含义 |
| ------------------- | ---------------------------------------------------------------- |
| `PIX` | 通过 Pix 结算的操作。 |
| `BANK_SLIP` | 通过 boleto 的操作。 |
| `INTERNAL_TRANSFER` | PayZu 账户之间的即时转账。每一方到达时 `type` 为 `WITHDRAW`（付款方）或 `DEPOSIT`（收款方）。 |
## 交易状态 (`status`) [#交易状态-status]
状态因类型而异。完整列表：
| 状态 | 含义 |
| -------------------- | ------------------------------------------------ |
| `PENDING` | 等待付款（收款）或等待处理（Pix 付款）。 |
| `COMPLETED` | 成功完成。收款时：客户已付款。Pix 付款时：资金已发出。 |
| `CANCELED` | 在完成前被取消（手动或按规则）。 |
| `WAITING_FOR_REFUND` | 等待退款处理（通常在 MED 被接受后）。 |
| `REFUNDED` | 已退款，金额已归还给付款方。 |
| `EXPIRED` | 收款在未付款情况下过期（超过 `expiresIn`）。 |
| `ERROR` | 操作过程中出现技术错误。请查看 payload 中的 `cancellationReason`。 |
## 退款状态 (`refundStatus`) [#退款状态-refundstatus]
| 值 | 含义 |
| ----------- | ------------ |
| `PENDING` | 退款在处理队列中。 |
| `COMPLETED` | 退款已处理，金额已归还。 |
| `CANCELED` | 退款在完成前被取消。 |
## Pix 密钥类型 (`pixType`) [#pix-密钥类型-pixtype]
五种密钥类型（`cpf`、`cnpj`、`phone`、`email`、`evp`），每种的格式和示例请参见 [Pix 密钥类型](/docs/pix-processamento/pix-key-types)。
## Infraction / MED [#infraction--med]
### 状态 (`infraction.status`) [#状态-infractionstatus]
| 值 | 描述 |
| --------------------- | -------------------------------- |
| `WAITING_PSP` | 等待提供方响应。 |
| `OPEN` | Infraction 已激活并正在分析中。 |
| `ACKNOWLEDGED` | 已被机构确认。 |
| `DEFENDED` | 抗辩已提交。 |
| `ANSWERED` | 已提供补充信息。 |
| `WAITING_ADJUSTMENTS` | 等待文件资料。 |
| `CLOSED` | 已解决并有最终决定（请查看 `analysisResult`）。 |
| `CANCELLED` | 在解决前被取消。 |
### 类型 (`infraction.type`) [#类型-infractiontype]
| 值 | 描述 |
| ------------------ | --------- |
| `REFUND_REQUEST` | 标准退款请求。 |
| `FRAUD` | 与安全相关的投诉。 |
| `REFUND_CANCELLED` | 取消先前的退款。 |
### 分析结果 (`infraction.analysisResult`) [#分析结果-infractionanalysisresult]
| 值 | 描述 |
| ----------- | ------------------------ |
| `AGREED` | Infraction 被接受。将处理退款。 |
| `DISAGREED` | Infraction 被拒绝。不退款，交易保留。 |
### 报告方 (`infraction.reportedBy`) [#报告方-infractionreportedby]
| 值 | 描述 |
| ---------------------- | -------- |
| `DEBITED_PARTICIPANT` | 付款方机构发起。 |
| `CREDITED_PARTICIPANT` | 收款方机构发起。 |
## 常见 API 字段 [#common-api-fields]
我们保留英文名称，因为 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）中。请始终记录并在开启支持时发送，调查会直接追踪。参见 [错误格式](/docs/pix-processamento/authentication#formato-de-erro)。 |
| `accountNumber` | PayZu 账户号（6 位数字）。在内部转账和交易 payload 中标识账户。 |
### 金额 [#金额]
| 字段 | 用途 |
| ------------------- | ------------------------------------------------ |
| `amount` | 以\*\*巴西雷亚尔（BRL）\*\*为单位的金额。例：`10.90` 表示 R$ 10,90。 |
| `serviceFeeCharged` | PayZu 就该操作收取的费用，以雷亚尔为单位。 |
### 生成的收款 [#生成的收款]
| 字段 | 用途 |
| ------------------- | -------------------------------------- |
| `qrCodeText` | Pix 复制粘贴代码（EMV BR Code）。在带复制按钮的输入框中使用。 |
| `qrCodeUrl` | 将 QR 渲染为 PNG 的公共 URL。可直接在 `![]()
` 中使用。 |
| `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 账户（收款和内部转账中）。 |
### 通过密钥的 Pix 付款 [#通过密钥的-pix-付款]
| 字段 | 用途 |
| ----------------- | ---------------------------------------- |
| `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 代码 [#http-代码]
完整的 HTTP 代码列表以及如何对每个代码作出反应，请参见 [错误代码](/docs/pix-processamento/error-codes)。
## 其他缩写 (Bacen / Pix) [#其他缩写-bacen--pix]
| 缩写 | 全称 |
| --------- | --------------------------------------------- |
| **Bacen** | 巴西中央银行。 |
| **PSP** | 支付服务提供商。每家银行/金融科技公司都是一个 PSP。 |
| **ISPB** | 巴西支付系统标识符。识别每个 PSP 的 8 位代码。 |
| **SPI** | 即时支付系统。处理 Pix 的 Bacen 基础设施。 |
| **CACC** | 活期账户（Bacen 使用的 ISO 20022 命名法）。 |
| **SVGS** | 储蓄账户。 |
| **TRAN** | 支付账户（过渡性）。 |
| **CUID** | PayZu 在内部资源中使用的字符串唯一标识符（例：infraction 的 `id`）。 |
## 下一步 [#下一步]