Pix 提现

把资金从账户发送到 Pix 密钥，并得知资金何时到达目的地。

POST提现到 Pix 密钥/transactions/withdraw GET查询提现/transactions/withdraw/{withdrawId}查询收款方

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

发起提现

POST /transactions/withdraw，作用域 WITHDRAW。必填：以分为单位的 amount，以及目标密钥 pixKey。

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

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"
  }'

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();

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

收款方的银行显示 comment 时，它会传给收款方。callbackUrl 接收这笔提现的 Webhook，需要回调密钥。所有字段见提现到 Pix 密钥。

保存提现

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

{
  "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。

确认送达

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

随时核对：用响应中的 id 或 Webhook 中的 withdrawId 查询 GET /transactions/withdraw/{withdrawId}，作用域 WITHDRAW_READ。

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

提现状态

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

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

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

余额与限额

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

查询与凭证

列表：GET /transactions/withdraw，作用域 WITHDRAW_READ，按游标分页。也包括 Pix 复制粘贴码付款，带 operation: "EXTERNAL_PAYMENT"。
凭证：GET /transactions/withdraw/{withdrawId}/receipt 以 base64 返回 PDF，适用于 CONFIRMED 的提现。

被退回的 Pix

收款方退回 Pix 时，金额会回到余额。大多数情况下会收到 WITHDRAW_REFUND_RECEIVED Webhook，不收手续费。详见无收款单的入账 Pix。

各项拒绝及其 code 见提现到 Pix 密钥。