# 概念 (/zh/docs/pix-processamento/concepts)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/getting-started" title="快速开始" />

  <QuickLink href="/docs/pix-processamento/endpoints" title="API 参考" />

  <QuickLink href="/docs/pix-processamento/glossary" title="术语表" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />
</QuickLinks>

## 概述 [#概述]

PayZu Processamento 是一个 REST API，endpoint 按功能分组。所有通信通过 HTTPS 以 JSON 格式进行，使用 Bearer token。金额始终以\*\*雷亚尔(BRL)\*\*为单位。

<Mermaid
  chart="`
flowchart LR
  App[&#x22;您的应用&#x22;] -->|&#x22;Bearer token&#x22;| API[&#x22;PayZu API&#x22;]
  API --> PIX[&#x22;Pix 收款&#x22;]
  API --> REF[&#x22;退款&#x22;]
  API --> WD[&#x22;Pix 付款&#x22;]
  API --> IT[&#x22;内部转账&#x22;]
  API --> ACC[&#x22;账户&#x22;]
  API --> REP[&#x22;报表&#x22;]
  API --> CB[&#x22;Callbacks&#x22;]
  API --> WH[&#x22;Webhooks&#x22;]
  API --> MED[&#x22;争议(MED)&#x22;]

  click PIX &#x22;/zh/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;Pix 收款 endpoint&#x22;
  click REF &#x22;/zh/docs/pix-processamento/endpoints/refunds/post_refund&#x22; &#x22;退款 endpoint&#x22;
  click WD &#x22;/zh/docs/pix-processamento/endpoints/withdrawals/post_withdraw&#x22; &#x22;Pix 付款 endpoint&#x22;
  click IT &#x22;/zh/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer&#x22; &#x22;内部转账 endpoint&#x22;
  click ACC &#x22;/zh/docs/pix-processamento/endpoints/account/get_user&#x22; &#x22;账户 endpoint&#x22;
  click REP &#x22;/zh/docs/pix-processamento/endpoints/reports/get_user_transactions&#x22; &#x22;报表 endpoint&#x22;
  click CB &#x22;/zh/docs/pix-processamento/endpoints/callbacks/get_user_callbacks&#x22; &#x22;Callbacks endpoint&#x22;
  click WH &#x22;/zh/docs/pix-processamento/endpoints/webhooks/post_user_webhook&#x22; &#x22;Webhooks endpoint&#x22;
  click MED &#x22;/zh/docs/pix-processamento/endpoints/infractions/get_infractions&#x22; &#x22;争议 endpoint&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Endpoint 分组 [#endpoint-分组]

完整的分组清单及每组包含的 endpoints 见 API 参考。

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints" title="API endpoints" />
</QuickLinks>

## 交易模型 [#交易模型]

PayZu 中的每一笔资金流动都以**交易**形式表示。无论是收款、Pix 付款还是内部转账,其基本结构都相同。

<Mermaid
  chart="`
flowchart TD
  T[&#x22;交易&#x22;]
  T --> D[&#x22;type DEPOSIT&#x22;]
  T --> W[&#x22;type WITHDRAW&#x22;]
  T --> I[&#x22;method INTERNAL_TRANSFER&#x22;]

  D --> D1[&#x22;接收第三方的 Pix&#x22;]
  W --> W1[&#x22;通过密钥或 QR 发送 Pix&#x22;]
  I --> I1[&#x22;在 PayZu 账户间划转余额<br/>两条腿:WITHDRAW 和 DEPOSIT&#x22;]

  style T fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

### 主要字段 [#主要字段]

| 字段                | 类型     | 用途                                                           |
| ----------------- | ------ | ------------------------------------------------------------ |
| `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 中操作的唯一标识符。在争议中用于追溯。                                    |

所有字段的详细说明见[术语表](/docs/pix-processamento/glossary#common-api-fields)。

## 典型生命周期 [#典型生命周期]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;您创建<br>POST /pix 或 /withdraw&#x22;] --> B[&#x22;交易 PENDING&#x22;]
  B --> C{&#x22;支付已处理?&#x22;}
  C -->|是| D[&#x22;COMPLETED&#x22;]
  C -->|过期| E[&#x22;EXPIRED&#x22;]
  C -->|错误| F[&#x22;ERROR&#x22;]
  D -.->|MED 争议| G[&#x22;REFUNDED&#x22;]

  click G &#x22;/zh/docs/pix-processamento/med&#x22; &#x22;MED,特殊退款机制&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
  style G fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

每种类型的完整状态请参见各 endpoint 的参考文档。快速查阅请见[术语表 · 交易状态](/docs/pix-processamento/glossary#status-de-transação-status)。

## API 约定 [#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`;响应外层结构因路由而异([详情](/docs/pix-processamento/best-practices/pagination)) |
| Webhooks     | 向 `callbackUrl` 发送 `POST`,最多重试 40 次                                                   |

## 下一步 [#下一步]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/authentication" title="Bearer 认证" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks(callbacks)" />

  <QuickLink href="/docs/pix-processamento/best-practices/idempotency" title="幂等性" />

  <QuickLink href="/docs/pix-processamento/med" title="MED(Pix 争议)" />

  <QuickLink href="/docs/pix-processamento/pix-key-types" title="Pix 密钥类型" />

  <QuickLink href="/docs/pix-processamento/glossary" title="完整术语表" />
</QuickLinks>