# 内部转账 (/zh/docs/pix-processamento/tutoriais/internal-transfer)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer" title="POST /internal-transfer" method="POST" path="/internal-transfer" />

  <QuickLink href="/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer" title="GET /internal-transfer" method="GET" path="/internal-transfer" />

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

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

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /internal-transfer&#x22;] --> B[&#x22;付款方扣款&#x22;]
  B --> C[&#x22;收款方入账&#x22;]
  C --> D[&#x22;回调 COMPLETED&#x22;]
  D --> E[&#x22;GET /internal-transfer&#x22;]

  click A &#x22;/zh/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer&#x22; &#x22;POST /internal-transfer&#x22;
  click D &#x22;/zh/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;
  click E &#x22;/zh/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer&#x22; &#x22;GET /internal-transfer&#x22;

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

## 使用场景 [#使用场景]

* 同一业务实体下不同账户之间的划转（总部/分部）
* 向同为 PayZu 客户的合作伙伴付款
* 内部余额调拨（钱包、运营子账户）

## 创建转账 [#创建转账]

您需要付款方和收款方双方的 `accountNumber`（6 位数字）。付款方必须与 token 认证的账户一致。

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/internal-transfer \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "payerAccountNumber": "000000",
        "receiverAccountNumber": "987654",
        "amount": 100.50,
        "description": "Pagamento referente a fatura #1234",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu",
        "clientReference": "transfer-abc-123"
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://api.payzu.processamento.com/v1/internal-transfer', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        payerAccountNumber: '000000',
        receiverAccountNumber: '987654',
        amount: 100.50,
        description: 'Pagamento referente a fatura #1234',
        callbackUrl: 'https://seusite.com.br/webhooks/payzu',
        clientReference: 'transfer-abc-123',
      }),
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    res = requests.post(
        'https://api.payzu.processamento.com/v1/internal-transfer',
        headers={
            'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
            'Content-Type': 'application/json',
        },
        json={
            'payerAccountNumber': '000000',
            'receiverAccountNumber': '987654',
            'amount': 100.50,
            'description': 'Pagamento referente a fatura #1234',
            'callbackUrl': 'https://seusite.com.br/webhooks/payzu',
            'clientReference': 'transfer-abc-123',
        },
    )
    ```
  </Tab>
</Tabs>

### 字段说明 [#字段说明]

| 字段                      | 类型     | 是否必填 | 说明                        |
| ----------------------- | ------ | ---- | ------------------------- |
| `payerAccountNumber`    | string | 是    | 付款账户（6 位数字）。必须与 token 一致。 |
| `receiverAccountNumber` | string | 是    | 收款账户（6 位数字）。              |
| `amount`                | number | 是    | 金额（BRL）。最低 R$ 0,01。       |
| `description`           | string | 否    | 自由文本，最多 500 个字符。          |
| `callbackUrl`           | string | 否    | 接收状态更新的 URL。              |
| `clientReference`       | string | 否    | 外部标识符（幂等性）。最多 64 字符。      |
| `virtualAccount`        | string | 否    | 虚拟子账户（多租户）。最多 50 字符。      |

完整 schema 见 [`POST /internal-transfer`](/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer)。

## 查询 [#查询]

支持 `id`、`clientReference` 或 `virtualAccount`（**仅使用其中一个**）。

```bash
curl "https://api.payzu.processamento.com/v1/internal-transfer?clientReference=transfer-abc-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

## 与 Pix 付款的差异 [#与-pix-付款的差异]

| 维度  | 内部转账                   | Pix 付款 (`/withdraw`) |
| --- | ---------------------- | -------------------- |
| 目的地 | PayZu 账户               | 任意银行/账户              |
| 费率  | 按账户费率表                 | 按费率表                 |
| 清算  | 即时                     | Pix 秒级到账             |
| 标识符 | `accountNumber`（6 位数字） | Pix 密钥或 QR Code      |

<Callout type="info">
  收款账户的 `accountNumber` 由 PayZu 合作伙伴提供。平台不公开账户目录。
</Callout>