创建 PIX 收款
POST
/api/v1/bank/wallet/charge/pix/Bearer Token请求头
| 请求头 | 值 | 必填 |
|---|---|---|
Authorization | Bearer {A55_ACCESS_TOKEN} | 是 |
Content-Type | application/json | 是 |
Idempotency-Key（幂等键） | UUID v4 | 建议 |
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
wallet_uuid | string (UUID) | 是 | 接收资金的钱包 |
merchant_id | string (UUID) | 是 | 商户标识符 |
payer_name | string | 是 | 付款人全名 |
payer_email | string | 是 | 付款人电子邮箱 |
payer_tax_id | string | 是 | CPF 或 CNPJ（例如 123.456.789-09） |
payer_cell_phone | string | 是 | 含国家代码的手机号码 |
amount | number | 是 | 收款金额，单位为 BRL（例如 100.00） |
currency | string | 是 | 必须为 BRL |
due_date | string | 是 | 过期日期 YYYY-MM-DD |
description | string | 是 | 显示给付款人的收款描述 |
webhook_url | string | 否 | 覆盖默认 webhook URL |
payer_address | object | 是 | 账单地址（street、city、state、postal_code） |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
charge_uuid | string | 唯一收款标识符 |
status | string | issued——等待付款人扫描二维码 |
pix_payload | object | PIX 支付数据 |
pix_payload.qr_code_base64 | string | Base64 编码的二维码 PNG 图片 |
pix_payload.copy_paste | string | EMV 复制粘贴字符串（pix copia e cola） |
pix_payload.expiration | string | 二维码过期时间 ISO 8601 时间戳 |
local_currency | number | BRL 金额 |
charge_payment_url | string | 托管支付页面 URL |
渲染二维码
解码 qr_code_base64 并将其显示为 <img> 标签：
<img src="data:image/png;base64,{qr_code_base64}" alt="PIX QR Code" width="250" />
或者，显示 copy_paste 字符串，以便付款人将其粘贴到银行应用程序中。
HTTP 状态码
| 状态码 | 说明 |
|---|---|
| 200 | PIX 收款已创建——已返回二维码 |
| 400 | 请求体无效或缺少必填字段 |
| 401 | Bearer Token（持有者令牌）无效或已过期 |
| 403 | 该钱包权限不足 |
| 404 | 钱包未找到 |
| 422 | 验证错误（CPF 无效、货币非 BRL） |
| 429 | 超出速率限制 |
| 500 | 服务器内部错误 - 请使用指数退避重试 |
代码示例
- cURL
- Python
- Node.js
curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/pix/ \
-H "Authorization: Bearer $A55_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
-d '{
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "王芳",
"payer_email": "wangfang@example.com",
"payer_tax_id": "111.222.333-44",
"payer_cell_phone": "+5521977777777",
"amount": 149.90,
"currency": "BRL",
"due_date": "2026-12-31",
"description": "订单 #100——PIX",
"webhook_url": "https://your-app.com/webhooks/a55",
"payer_address": {
"street": "Av. Rio Branco",
"address_number": "200",
"complement": "Sala 301",
"neighborhood": "Centro",
"city": "Rio de Janeiro",
"state": "RJ",
"postal_code": "20040-002",
"country": "BR"
}
}'
import requests
import os
token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")
try:
response = requests.post(
f"{base}/api/v1/bank/wallet/charge/pix/",
json={
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "王芳",
"payer_email": "wangfang@example.com",
"payer_tax_id": "111.222.333-44",
"payer_cell_phone": "+5521977777777",
"amount": 149.90,
"currency": "BRL",
"due_date": "2026-12-31",
"description": "订单 #100——PIX",
"webhook_url": "https://your-app.com/webhooks/a55",
"payer_address": {
"street": "Av. Rio Branco",
"address_number": "200",
"complement": "Sala 301",
"neighborhood": "Centro",
"city": "Rio de Janeiro",
"state": "RJ",
"postal_code": "20040-002",
"country": "BR",
},
},
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Idempotency-Key": "660e8400-e29b-41d4-a716-446655440001",
},
)
response.raise_for_status()
charge = response.json()
print(f"PIX 收款：{charge['charge_uuid']}")
print(f"复制粘贴：{charge['pix_payload']['copy_paste']}")
except requests.exceptions.HTTPError as e:
print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
print(f"请求失败：{e}")
const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";
try {
const response = await fetch(`${base}/api/v1/bank/wallet/charge/pix/`, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
"Idempotency-Key": "660e8400-e29b-41d4-a716-446655440001",
},
body: JSON.stringify({
wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
merchant_id: "11111111-1111-1111-1111-111111111111",
payer_name: "王芳",
payer_email: "wangfang@example.com",
payer_tax_id: "111.222.333-44",
payer_cell_phone: "+5521977777777",
amount: 149.90,
currency: "BRL",
due_date: "2026-12-31",
description: "订单 #100——PIX",
webhook_url: "https://your-app.com/webhooks/a55",
payer_address: {
street: "Av. Rio Branco",
address_number: "200",
complement: "Sala 301",
neighborhood: "Centro",
city: "Rio de Janeiro",
state: "RJ",
postal_code: "20040-002",
country: "BR",
},
}),
});
if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
const charge = await response.json();
console.log(`PIX 收款：${charge.charge_uuid}`);
console.log(`复制粘贴：${charge.pix_payload.copy_paste}`);
} catch (error) {
console.error("PIX 收款创建失败：", error.message);
}
错误响应示例
{
"charge_uuid": null,
"status": "error",
"message": [
{
"code": "INVALID_TAX_ID",
"source": "validation",
"description": "payer_tax_id is not a valid CPF or CNPJ"
}
]
}