# Pix 提现 (/zh/docs/conta-digital/withdrawals)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/withdrawals/post_withdraw" title="提现到 Pix 密钥" method="POST" path="/transactions/withdraw" />

  <QuickLink href="/docs/conta-digital/endpoints/withdrawals/get_withdraw" title="查询提现" method="GET" path="/transactions/withdraw/{withdrawId}" />

  <QuickLink href="/docs/conta-digital/recipient" title="查询收款方" />
</QuickLinks>

你请求的金额就是到达目的地的金额；手续费另加。两者在发起请求时从可用余额中扣出，提现失败时退回。

<Mermaid
  chart="`
flowchart LR
  A[&#x22;发起提现&#x22;] --> B[&#x22;金额和手续费从余额中扣出&#x22;]
  B --> C[&#x22;WITHDRAW_COMPLETED Webhook&#x22;]
  C --> D[&#x22;资金已送达&#x22;]
  B -.->|&#x22;失败&#x22;| E[&#x22;WITHDRAW_FAILED Webhook&#x22;]
  E -.-> F[&#x22;金额和手续费退回余额&#x22;]

  click A &#x22;/docs/conta-digital/endpoints/withdrawals/post_withdraw&#x22; &#x22;提现到 Pix 密钥&#x22;
  click C &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;
  click E &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

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

<Steps>
  <Step>
    ### 核对收款方 [#核对收款方]

    可选。要在确认前显示密钥的持有人，请使用[查询收款方](/docs/conta-digital/recipient)。
  </Step>

  <Step>
    ### 发起提现 [#发起提现]

    [`POST /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/post_withdraw)，作用域 `WITHDRAW`。必填：以分为单位的 `amount`，以及目标密钥 `pixKey`。

    为每笔提现生成一个 `Idempotency-Key`，并与你的记录一起保存。用同一个键重复调用会返回已有的提现，不会再发出一笔 Pix。

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        IDEMPOTENCY_KEY=$(uuidgen)

        curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/withdraw \
          -H "Authorization: Bearer $PAYZU_TOKEN" \
          -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 10000,
            "pixKey": "fulano@exemplo.com",
            "pixKeyType": "EMAIL",
            "comment": "Repasse semanal"
          }'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        import crypto from 'node:crypto';

        const idempotencyKey = crypto.randomUUID();

        const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/withdraw', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Idempotency-Key': idempotencyKey,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 10000,
            pixKey: 'fulano@exemplo.com',
            pixKeyType: 'EMAIL',
            comment: 'Repasse semanal',
          }),
        });
        const saque = await res.json();
        ```
      </Tab>
    </Tabs>

    同时发送 `pixKeyType`（`CPF`、`CNPJ`、`EMAIL`、`PHONE` 或 `EVP`）。不传时，类型根据格式推断，11 位的手机号可能被识别为 CPF。类型与密钥不符时，以 `400` `WITHDRAW_PIX_KEY_TYPE_MISMATCH` 拒绝，余额不会扣减。

    收款方的银行显示 `comment` 时，它会传给收款方。`callbackUrl` 接收这笔提现的 Webhook，需要[回调密钥](/docs/conta-digital/webhooks#操作的-callbackurl)。所有字段见[提现到 Pix 密钥](/docs/conta-digital/endpoints/withdrawals/post_withdraw)。
  </Step>

  <Step>
    ### 保存提现 [#保存提现]

    响应（`201`）返回提现。保存 `id`。

    ```json
    {
      "id": "hubp-20261005R4D8TN2WQZ127431",
      "status": "APPROVED",
      "amount": 10000,
      "serviceFee": 250,
      "totalDebited": 10250,
      "pixKey": "fulano@exemplo.com",
      "comment": "Repasse semanal",
      "e2e": null,
      "providerRejectedReason": null,
      "callbackUrl": null,
      "createdAt": "2026-10-05T14:40:11.002Z",
      "sentAt": "2026-10-05T14:40:11.380Z",
      "approvedAt": "2026-10-05T14:40:11.702Z",
      "confirmedAt": null
    }
    ```

    `totalDebited` 是从账户扣出的金额：`amount` + `serviceFee`。手续费为 1.5% + R$ 1,00 时，一笔 R$ 100,00 的提现扣款 R$ 102,50。
  </Step>

  <Step>
    ### 确认送达 [#确认送达]

    收到 `WITHDRAW_COMPLETED` Webhook 且 `status: "CONFIRMED"` 时，提现即已送达。失败时，会收到 `WITHDRAW_FAILED`。

    随时核对：用响应中的 `id` 或 Webhook 中的 `withdrawId` 查询 [`GET /transactions/withdraw/{withdrawId}`](/docs/conta-digital/endpoints/withdrawals/get_withdraw)，作用域 `WITHDRAW_READ`。

    在查询和列表中，密钥在 `destination.pixKey` 中，为 CPF、邮箱或电话时已脱敏。只有 `POST` 的响应在根级带有 `pixKey`。
  </Step>
</Steps>

## 提现状态 [#提现状态]

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> REQUESTED
  REQUESTED --> CREATED
  CREATED --> APPROVED
  APPROVED --> CONFIRMED
  REQUESTED --> FAILED
  CREATED --> FAILED
  APPROVED --> FAILED
  CONFIRMED --> [*]
  FAILED --> [*]
`"
/>

| 状态          | 含义                                                         |
| ----------- | ---------------------------------------------------------- |
| `REQUESTED` | 已收到请求。金额和手续费已从可用余额中扣出。                                     |
| `CREATED`   | 已在银行登记。                                                    |
| `APPROVED`  | 已批准，正在途中。还不代表资金已送达。                                        |
| `CONFIRMED` | 资金已到达。Webhook：`WITHDRAW_COMPLETED`。                        |
| `FAILED`    | 未发出，金额和手续费已退回余额。可能从之前的任一状态变为此状态。Webhook：`WITHDRAW_FAILED`。 |

## 重复请求 [#重复请求]

`Idempotency-Key` 为 1 到 255 个可见 ASCII 字符，不含空格。按账户生效，不会过期。

| 你发送                             | API 响应                                   |
| ------------------------------- | ---------------------------------------- |
| 相同的键，相同的 `amount` 和相同的 `pixKey` | 已有的提现及其当前状态。不会发出新的 Pix。                  |
| 相同的键，不同的 `amount` 或不同的 `pixKey` | `409` `WITHDRAW_IDEMPOTENCY_KEY_REUSED`。 |
| 没有键                             | 每次请求都创建一笔新提现。                            |

`comment` 和 `callbackUrl` 不参与比较。

遇到带 `PROVIDER_UNAVAILABLE` 的 `502`，或 `details.status` 为 `408` 或 `429` 的 `PROVIDER_REFUSED` 时，Pix 可能已经发出，金额会留在可用余额之外，直到与银行核对出结果。请用同一个 `Idempotency-Key` 重试，它会返回原提现；或者在再次请求前，先在 [`GET /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/get_withdraws) 中查找该提现。其他 `PROVIDER_REFUSED` 是最终拒绝：金额立即退回，提现变为 `FAILED`。

## 余额与限额 [#余额与限额]

* 余额不足会拒绝整笔提现，不存在部分提现：`422` `WITHDRAW_INSUFFICIENT_BALANCE`，带 `details.available` 和 `details.required`。`WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE`：即使 `available` 足够，银行当时也无法支付这笔提现。
* 金额必须在账户提现的最小值和最大值之间，见[限额](/docs/conta-digital/statement#限额)中的 `withdraw`。
* Pix 转出有每日上限，提现和 Pix 复制粘贴码付款合计。上限和当天已用金额在 `dailyWithdraw` 中；`0` 会阻止所有提现，`limit: null` 表示无上限。超出时返回 `422` `WITHDRAW_DAILY_LIMIT`。
* 每个凭证每分钟最多 5 次请求，每个账户 10 次，与 Pix 复制粘贴码付款和退款合计。超过后，API 返回 `429` 和 `Retry-After`。

## 查询与凭证 [#查询与凭证]

* **列表：**[`GET /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/get_withdraws)，作用域 `WITHDRAW_READ`，按游标分页。也包括 Pix 复制粘贴码付款，带 `operation: "EXTERNAL_PAYMENT"`。
* **凭证：**[`GET /transactions/withdraw/{withdrawId}/receipt`](/docs/conta-digital/endpoints/withdrawals/get_withdraw_receipt) 以 base64 返回 PDF，适用于 `CONFIRMED` 的提现。

## 被退回的 Pix [#被退回的-pix]

收款方退回 Pix 时，金额会回到余额。大多数情况下会收到 `WITHDRAW_REFUND_RECEIVED` Webhook，不收手续费。详见[无收款单的入账 Pix](/docs/conta-digital/deposits#已发出-pix-的退回)。

各项拒绝及其 `code` 见[提现到 Pix 密钥](/docs/conta-digital/endpoints/withdrawals/post_withdraw)。