支付 Pix 复制粘贴码
用账户余额支付静态或动态的 Pix 复制粘贴码。
支付 Pix 复制粘贴码与提现的方式相同：同样的响应、同样的跟踪方式和同样的限额，手续费单独计算。目的地来自代码；代码固定了金额时，金额也来自代码。
解析 Pix 复制粘贴码
可选。POST /transactions/pix/decode，作用域 PIX_DICT_READ，只解析代码，不付款，也不查询银行：不计入查询次数限制，也不会告诉你持有人是谁。
curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/pix/decode \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572" }'const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/pix/decode', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
brCode: '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572',
}),
});
const codigo = await res.json();{
"pixKey": "fulano@exemplo.com",
"url": null,
"amount": 2500,
"merchantName": "FULANO DE TAL",
"merchantCity": "SAO PAULO",
"txid": "PEDIDO4821",
"isDynamic": false,
"isAmountFixed": true
}isAmountFixed 表示代码是否已带有金额。merchantName 和 merchantCity 是生成代码的一方写入的内容，未经验证；要知道持有人，请使用查询收款方。动态码中 pixKey 为 null，只填写 url；持有人和金额来自收款方查询。
支付 Pix 复制粘贴码
POST /transactions/pix/qr-payments，作用域 WITHDRAW。在 brCode 中按读取到的原样发送完整代码：不接受用你的系统解析出的密钥代替它。只有代码未固定金额时，才发送以分为单位的 amount。
为每笔付款生成一个 Idempotency-Key；重复调用时，发送同一个。
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/pix/qr-payments \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572",
"comment": "Pedido 4821"
}'import crypto from 'node:crypto';
const idempotencyKey = crypto.randomUUID();
const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/pix/qr-payments', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({
brCode: '00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572',
comment: 'Pedido 4821',
}),
});
const pagamento = await res.json();comment 会传给收款方；不传时，传的是代码中的收款方名称。callbackUrl 接收这笔付款的 Webhook，需要回调密钥。所有字段见支付 Pix 复制粘贴码。
保存付款
响应（201）的格式与提现相同。保存 id。
{
"id": "hubp-20261005H2P6XC8VNM127431",
"status": "APPROVED",
"amount": 2500,
"serviceFee": 100,
"totalDebited": 2600,
"pixKey": "f***@exemplo.com",
"comment": "Pedido 4821",
"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
}pixKey 已脱敏。APPROVED 表示付款正在途中，不代表资金已送达。
确认送达
收到 WITHDRAW_COMPLETED Webhook，且带 status: "CONFIRMED" 和 operation: "EXTERNAL_PAYMENT" 时，付款即已送达。失败时，会收到 WITHDRAW_FAILED，金额和手续费退回余额。
查询使用提现的路由：GET /transactions/withdraw/{withdrawId}。
金额
| 代码 | 发送的 amount | 结果 |
|---|---|---|
| 固定金额 | 无 | 支付代码中的金额。 |
| 固定金额 | 相同 | 支付。 |
| 固定金额 | 不同 | 422 QR_AMOUNT_MISMATCH，带 details.expected 和 details.requested。 |
| 未固定 | 有金额 | 支付发送的金额。 |
| 未固定 | 无 | 422 QR_AMOUNT_REQUIRED。 |
动态码
动态码只包含一个链接，PayZu 在付款前通过银行解析它；在此之前，余额不会扣减。请求体和响应相同。
- 解析失败时，拒绝使用收款方查询的代码：
404PIX_DEST_PIX_KEY、503PIX_DEST_UNAVAILABLE或PIX_DEST_THROTTLED、502PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER。 - 代码上印的金额与银行为其返回的金额不一致时，付款会以
422QR_AMOUNT_DISAGREES被拒绝。
重复请求
Idempotency-Key 遵循提现的规则，比较时还会考虑所支付的代码。对于动态码，会先解析代码，再检查是否重复，因此重复请求可能返回解析阶段的拒绝，而不是原来的付款。
遇到 502 时，付款可能已经发出。请用同一个 Idempotency-Key 重试，或在再次付款前先在 GET /transactions/withdraw 中查找该付款。
手续费与限额
- 手续费是 Pix 复制粘贴码付款的手续费，即限额中的
externalPayment。 - 最小值和最大值与提现相同。每日上限和请求次数限制也相同，并与提现合计。
- 已支付或已过期的代码会被银行拒绝。
- 已损坏（
QR_CRC）、格式无效（QR_MALFORMED）或不是 Pix 的代码（QR_NOT_PIX），在解析和付款时都会以400被拒绝。
各项拒绝及其 code 见支付 Pix 复制粘贴码。