# 接收 Pix 付款 (/zh/docs/pix-processamento/tutoriais/receive-pix)
### 生成收款单 [#生成收款单]
endpoint：[`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix)。仅 `amount` 为必填项，[以雷亚尔为单位](/docs/pix-processamento/best-practices/money)，绝不用分；其他字段用于丰富 QR 和对账信息。
```bash
curl -X POST https://api.payzu.processamento.com/v1/pix \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 99.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/payzu",
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"expiresIn": 600
}'
```
```ts
const res = await fetch('https://api.payzu.processamento.com/v1/pix', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 99.90,
generatedName: 'João da Silva',
generatedDocument: '12345678909',
callbackUrl: 'https://seusite.com.br/webhooks/payzu',
clientReference: 'pedido-2025-001',
virtualAccount: 'loja-rj-01',
expiresIn: 600,
}),
});
const charge = await res.json();
```
响应：
```json
{
"id": "PAYZU20260811R4TZ8WD1NC000000",
"status": "PENDING",
"amount": 99.90,
"qrCodeText": "00020126870014br.gov.bcb.pix...",
"qrCodeUrl": "https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20260811R4TZ8WD1NC000000",
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"expiresAt": "2025-08-17T22:00:00.000Z"
}
```
### 向客户展示 QR Code [#向客户展示-qr-code]
两种方式：
**直接图片**，在 `![]()
` 中使用 `qrCodeUrl`：
```html
```
**复制粘贴**，将 `qrCodeText` 显示在带按钮的 input 中：
```html
```
PayZu 每笔收款生成**动态** QR。
### 在付款时接收 callback [#在付款时接收-callback]
当客户完成 Pix 付款后，PayZu 将向您的 `callbackUrl` 发送 `POST`：
```json
{
"id": "PAYZU20260811R4TZ8WD1NC000000",
"type": "DEPOSIT",
"status": "COMPLETED",
"amount": 99.90,
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"endToEndId": "E60746948202508172200X7H4K2P9M5Q",
"paidAt": "2025-08-17T22:00:12.000Z"
}
```
处理器示例：
```ts
import express from 'express';
const app = express();
app.post('/webhooks/payzu', express.json(), async (req, res) => {
const tx = req.body;
if (await isProcessed(tx.id, tx.status)) return res.status(200).end();
if (tx.type === 'DEPOSIT' && tx.status === 'COMPLETED') {
await markOrderPaid(tx.clientReference, tx);
}
res.status(204).end();
});
```
```python
from flask import Flask, request
app = Flask(__name__)
@app.post('/webhooks/payzu')
def payzu_webhook():
tx = request.get_json()
if is_processed(tx['id'], tx['status']):
return '', 200
if tx['type'] == 'DEPOSIT' and tx['status'] == 'COMPLETED':
mark_order_paid(tx['clientReference'], tx)
return '', 204
```
请在 **5 秒**内以 `2xx` 响应；完整的重试策略请见 [Webhooks](/docs/pix-processamento/webhooks)。
### 通过 polling 后备查询 [#通过-polling-后备查询]
如果 callback 未送达，可直接通过 [`GET /pix`](/docs/pix-processamento/endpoints/pix-operations/get_pix) 查询。接受 `id`、`clientReference`、`endToEndId` 或 `virtualAccount`，**仅使用其中一个**。
```bash
curl "https://api.payzu.processamento.com/v1/pix?clientReference=pedido-2025-001" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"
```
```ts
const res = await fetch(
`https://api.payzu.processamento.com/v1/pix?clientReference=pedido-2025-001`,
{
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
},
);
const charge = await res.json();
```
polling 应作为后备方案。请将 callback 配置为主要来源。
### 凭证 [#凭证]
付款完成后，通过 [`GET /proof/{id}`](/docs/pix-processamento/endpoints/pix-operations/get_proof) 下载官方凭证：
```bash
curl "https://api.payzu.processamento.com/v1/proof/PAYZU20260811R4TZ8WD1NC000000" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"
```
## 下一步 [#下一步]