# 支付 Pix 复制粘贴码 (/zh/docs/conta-digital/qr-payments)
支付 Pix 复制粘贴码与[提现](/docs/conta-digital/withdrawals)的方式相同：同样的响应、同样的跟踪方式和同样的限额，手续费单独计算。目的地来自代码；代码固定了金额时，金额也来自代码。
### 解析 Pix 复制粘贴码 [#解析-pix-复制粘贴码]
可选。[`POST /transactions/pix/decode`](/docs/conta-digital/endpoints/pix/post_pix_decode)，作用域 `PIX_DICT_READ`，只解析代码，不付款，也不查询银行：不计入查询次数限制，也不会告诉你持有人是谁。
```bash
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" }'
```
```ts
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();
```
```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` 是生成代码的一方写入的内容，未经验证；要知道持有人，请使用[查询收款方](/docs/conta-digital/recipient)。动态码中 `pixKey` 为 `null`，只填写 `url`；持有人和金额来自[收款方查询](/docs/conta-digital/recipient)。
### 支付 Pix 复制粘贴码 [#支付-pix-复制粘贴码]
[`POST /transactions/pix/qr-payments`](/docs/conta-digital/endpoints/pix/post_pix_qr_payment)，作用域 `WITHDRAW`。在 `brCode` 中按读取到的原样发送完整代码：不接受用你的系统解析出的密钥代替它。只有代码未固定金额时，才发送以分为单位的 `amount`。
为每笔付款生成一个 `Idempotency-Key`；重复调用时，发送同一个。
```bash
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"
}'
```
```ts
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，需要[回调密钥](/docs/conta-digital/webhooks#操作的-callbackurl)。所有字段见[支付 Pix 复制粘贴码](/docs/conta-digital/endpoints/pix/post_pix_qr_payment)。
### 保存付款 [#保存付款]
响应（`201`）的格式与[提现](/docs/conta-digital/withdrawals#提现状态)相同。保存 `id`。
```json
{
"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}`](/docs/conta-digital/endpoints/withdrawals/get_withdraw)。
## 金额 [#金额]
| 代码 | 发送的 `amount` | 结果 |
| ---- | ------------ | ---------------------------------------------------------------------- |
| 固定金额 | 无 | 支付代码中的金额。 |
| 固定金额 | 相同 | 支付。 |
| 固定金额 | 不同 | `422` `QR_AMOUNT_MISMATCH`，带 `details.expected` 和 `details.requested`。 |
| 未固定 | 有金额 | 支付发送的金额。 |
| 未固定 | 无 | `422` `QR_AMOUNT_REQUIRED`。 |
## 动态码 [#动态码]
动态码只包含一个链接，PayZu 在付款前通过银行解析它；在此之前，余额不会扣减。请求体和响应相同。
* 解析失败时，拒绝使用[收款方查询](/docs/conta-digital/recipient)的代码：`404` `PIX_DEST_PIX_KEY`、`503` `PIX_DEST_UNAVAILABLE` 或 `PIX_DEST_THROTTLED`、`502` `PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER`。
* 代码上印的金额与银行为其返回的金额不一致时，付款会以 `422` `QR_AMOUNT_DISAGREES` 被拒绝。
## 重复请求 [#重复请求]
`Idempotency-Key` 遵循[提现](/docs/conta-digital/withdrawals#重复请求)的规则，比较时还会考虑所支付的代码。对于动态码，会先解析代码，再检查是否重复，因此重复请求可能返回解析阶段的拒绝，而不是原来的付款。
遇到 `502` 时，付款可能已经发出。请用同一个 `Idempotency-Key` 重试，或在再次付款前先在 [`GET /transactions/withdraw`](/docs/conta-digital/endpoints/withdrawals/get_withdraws) 中查找该付款。
## 手续费与限额 [#手续费与限额]
* 手续费是 Pix 复制粘贴码付款的手续费，即[限额](/docs/conta-digital/statement#限额)中的 `externalPayment`。
* 最小值和最大值与提现相同。每日上限和请求次数限制也相同，并与提现合计。
* 已支付或已过期的代码会被银行拒绝。
* 已损坏（`QR_CRC`）、格式无效（`QR_MALFORMED`）或不是 Pix 的代码（`QR_NOT_PIX`），在解析和付款时都会以 `400` 被拒绝。
各项拒绝及其 `code` 见[支付 Pix 复制粘贴码](/docs/conta-digital/endpoints/pix/post_pix_qr_payment)。