PIX
Quick Reference
WhatPIX 即时支付
Why零或接近零成本、7×24 即时结算、QR 码（二维码）——巴西增长最快的支付方式
Reading Time10 分钟
Difficulty初级
Prerequisites身份验证 → 环境配置
为何选择 PIX（巴西即时支付系统）
| 优势 | 说明 |
|---|---|
| 即时结算 | 7×24×365——资金数秒内到账 |
| 零或接近零成本 | 无卡组织费用；PIX 定价通常低于卡 |
| 覆盖最广 | 巴西 1.5 亿+ 用户 |
| 无拒付 | 不可撤销的 push 支付 |
| 体验简单 | 扫描 QR 或复制 PIX 字符串；确认后接收 Webhook（网络钩子）通知 |
PIX 生命周期
支付流程
创建 PIX 收费
- cURL
- Python
- JavaScript
curl -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"wallet_uuid": "00000000-0000-0000-0000-000000000000",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "张伟",
"payer_email": "zhangwei@example.com",
"payer_tax_id": "39999999999",
"payer_cell_phone": "+5511988887777",
"installment_value": 150,
"installment_count": 1,
"items": [{"name":"跑鞋","quantity":1,"total_amount":150,"unit_amount":150,"sku":"SHOE-001","code":"RS001"}],
"payer_address": {"street":"Av. Paulista","address_number":"1000","complement":"Apto 42","neighborhood":"Bela Vista","city":"São Paulo","state":"SP","postal_code":"01310-100","country":"BR"},
"currency": "BRL",
"due_date": "2026-12-31T23:59:59Z",
"description": "PIX 订单",
"type_charge": "pix",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation"
}'
import requests
charge = requests.post(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
json={
"wallet_uuid": "00000000-0000-0000-0000-000000000000",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "张伟",
"payer_email": "zhangwei@example.com",
"payer_tax_id": "39999999999",
"payer_cell_phone": "+5511988887777",
"installment_value": 150,
"installment_count": 1,
"items": [{"name": "跑鞋", "quantity": 1, "total_amount": 150, "unit_amount": 150, "sku": "SHOE-001", "code": "RS001"}],
"payer_address": {"street": "Av. Paulista", "address_number": "1000", "complement": "Apto 42", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR"},
"currency": "BRL",
"due_date": "2026-12-31T23:59:59Z",
"description": "PIX 订单",
"type_charge": "pix",
"webhook_url": "https://yoursite.com/webhook",
"redirect_url": "https://yoursite.com/confirmation",
},
)
charge.raise_for_status()
data = charge.json()
qr_png = data["pix_payload"]["qr_code"]
copy_paste = data["pix_payload"]["payload"]
const response = await fetch(
"https://core-manager.a55.tech/api/v1/bank/wallet/charge/",
{
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
wallet_uuid: "00000000-0000-0000-0000-000000000000",
merchant_id: "11111111-1111-1111-1111-111111111111",
payer_name: "张伟",
payer_email: "zhangwei@example.com",
payer_tax_id: "39999999999",
payer_cell_phone: "+5511988887777",
installment_value: 150,
installment_count: 1,
items: [{ name: "跑鞋", quantity: 1, total_amount: 150, unit_amount: 150, sku: "SHOE-001", code: "RS001" }],
payer_address: { street: "Av. Paulista", address_number: "1000", complement: "Apto 42", neighborhood: "Bela Vista", city: "São Paulo", state: "SP", postal_code: "01310-100", country: "BR" },
currency: "BRL",
due_date: "2026-12-31T23:59:59Z",
description: "PIX 订单",
type_charge: "pix",
webhook_url: "https://yoursite.com/webhook",
redirect_url: "https://yoursite.com/confirmation",
}),
}
);
if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
const { pix_payload, charge_payment_url } = await response.json();
展示 QR 码
| 字段 | 用途 |
|---|---|
pix_payload.qr_code | Base64 PNG——以 data:image/png;base64,… 渲染 |
pix_payload.payload | EMV（Europay-Mastercard-Visa 支付标准）复制粘贴字符串 |
pix_payload.expiration_date | 显示截止时间或倒计时 |
charge_payment_url | 含 QR 的托管支付页 |
展示建议
同时提供 QR 图片与复制粘贴字符串。同一设备上的移动用户无法扫描自己的屏幕。
QR 有效期
PIX QR 码（二维码）的有效期由 pix_payload.expiration_date 字段决定，默认 30 分钟，最长不超过 24 小时（BACEN（巴西中央银行）规定）。请注意 due_date 是收费的整体截止日期，与 QR 码有效期不同。请在界面中展示倒计时，提示客户在 QR 失效前完成付款。
响应示例
{
"charge_uuid": "81f0045c-301a-45c4-96bc-5395f7cf35f9",
"currency": "BRL",
"type": "pix",
"status": "issued",
"pix_payload": {
"qr_code": "iVBORw0KGgoAAAANSUh…",
"payload": "00020126580014br.gov.bcb.pix…",
"expiration_date": "2026-01-15 18:30:00.000000"
},
"charge_payment_url": "https://pay.a55.tech/charge/81f0045c-301a-45c4-96bc-5395f7cf35f9"
}
状态生命周期
| 状态 | 说明 |
|---|---|
issued | 已生成 QR；等待付款 |
paid | PIX 网络已确认 |
cancelled | 付款前已过期或取消 |
failed | 生成或处理错误 |
refunded | 退款已完成 |