PayZuPayZu Docs

接收 Pix 付款

生成收款单

endpoint:POST /pix。仅 amount 为必填项;其他字段用于丰富 QR 和对账信息。

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
  }'
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();
import os, requests

res = requests.post(
    'https://api.payzu.processamento.com/v1/pix',
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        '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,
    },
)
charge = res.json()
body := strings.NewReader(`{
  "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
}`)

req, _ := http.NewRequest("POST", "https://api.payzu.processamento.com/v1/pix", body)
req.Header.Set("Authorization", "Bearer " + os.Getenv("PAYZU_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
<?php
$ch = curl_init('https://api.payzu.processamento.com/v1/pix');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PAYZU_TOKEN'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    '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,
  ]),
]);
$charge = json_decode(curl_exec($ch), true);

响应:

{
  "id": "PAYZU20250817215911F49RDOBJ",
  "status": "PENDING",
  "amount": 99.90,
  "qrCodeText": "00020126870014br.gov.bcb.pix...",
  "qrCodeUrl": "https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20250817215911F49RDOBJ",
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "expiresAt": "2025-08-17T22:00:00.000Z"
}

向客户展示 QR Code

两种方式:

直接图片,在 <img> 中使用 qrCodeUrl

<img src="https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU2025..." />

复制粘贴,将 qrCodeText 显示在带按钮的 input 中:

<input value="00020126870014br.gov.bcb.pix2565..." readonly />
<button onclick="navigator.clipboard.writeText(qrCodeText)">复制</button>

PayZu 只生成动态 QR。不支持静态 QR。

在付款时接收 callback

当客户完成 Pix 付款后,PayZu 将向您的 callbackUrl 发送 POST

{
  "id": "PAYZU20250817215911F49RDOBJ",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 99.90,
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "endToEndId": "E60746948202508172200X7H4K2P9M5",
  "paidAt": "2025-08-17T22:00:12.000Z"
}

处理器示例:

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();
});
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
http.HandleFunc("/webhooks/payzu", func(w http.ResponseWriter, r *http.Request) {
    var tx Transaction
    if err := json.NewDecoder(r.Body).Decode(&tx); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    if isProcessed(tx.ID, tx.Status) {
        w.WriteHeader(http.StatusOK)
        return
    }
    if tx.Type == "DEPOSIT" && tx.Status == "COMPLETED" {
        markOrderPaid(tx.ClientReference, tx)
    }
    w.WriteHeader(http.StatusNoContent)
})
<?php
$tx = json_decode(file_get_contents('php://input'), true);

if (isProcessed($tx['id'], $tx['status'])) {
    http_response_code(200);
    exit;
}

if ($tx['type'] === 'DEPOSIT' && $tx['status'] === 'COMPLETED') {
    markOrderPaid($tx['clientReference'], $tx);
}

http_response_code(204);

请在 5 秒内以 2xx 响应。否则,PayZu 将启动重试(最多 72 次,采用指数退避)。详情请见 Webhooks

通过 polling 后备查询

如果 callback 未送达,可直接通过 GET /pix 查询。接受 idclientReferenceendToEndIdvirtualAccount仅使用其中一个

curl "https://api.payzu.processamento.com/v1/pix?clientReference=pedido-2025-001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
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();
res = requests.get(
    'https://api.payzu.processamento.com/v1/pix',
    params={'clientReference': 'pedido-2025-001'},
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)

polling 应作为后备方案。请将 callback 配置为主要来源。

凭证

付款完成后,通过 GET /proof/{id} 下载官方凭证:

curl "https://api.payzu.processamento.com/v1/proof/PAYZU20250817215911F49RDOBJ" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

On this page