通过二维码发送 PIX 付款（Cash-Out QR Code）
POST /api/pix/cash-out-qrcode
POST https://<api-host>/api/pix/cash-out-qrcode需要在 Authorization 头中提供 Bearer token。请参阅 生成令牌 获取。
通过扫描或复制的二维码（复制粘贴）发送 PIX 付款。二维码必须符合中央银行 EMV PIX 标准。
认证
需要在 Authorization 头中提供 Bearer 令牌。
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
value | number | 是 | 付款金额（巴西雷亚尔，最多 2 位小数）。如果二维码中包含金额，必须与之匹配 |
qrCode | string | 是 | PIX 二维码内容（EMV 字符串）。最少 50 个字符，最多 500 个字符。必须以 000201 开头 |
externalId | string | 是 | 每个账户唯一的外部标识符（最多 36 个字符） |
description | string | 否 | 可选的付款描述（最多 140 个字符） |
name | string | 否 | 收款人姓名，仅供参考（最多 100 个字符；可能包含在二维码中） |
document | string | 否 | 有效的收款人 CPF 或 CNPJ，仅数字（最多 14 个字符；可能包含在二维码中） |
{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
}代码示例
curl -X POST "https://<api-host>/api/pix/cash-out-qrcode" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/cash-out-qrcode',
{
"value": 15.50,
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD",
"externalId": "QRPAY-987654-20240119",
"description": "Pagamento fornecedor XYZ via QR Code",
"name": "Destinatário Ltda",
"document": "12345678000195"
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);响应 (201)
| 字段 | 类型 | 描述 |
|---|---|---|
transactionId | string | 生成的交易内部标识符 |
externalId | string | 请求中提供的外部标识符 |
status | string | 当前交易状态（PENDING、CONFIRMED、ERROR） |
generateTime | string | 交易生成日期/时间（ISO 8601） |
{
"transactionId": "456",
"externalId": "QRPAY-987654-20240119",
"status": "PENDING",
"generateTime": "2024-01-19T14:30:00.000Z"
}错误
| 状态码 | 描述 |
|---|---|
| 400 | 数据无效、二维码无效、金额不匹配或余额不足 |
| 401 | 令牌缺失或无效 |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — 该账户下 externalId 已被使用 |
| 422 | 支付服务商声明的拒绝。若返回 QRCODE_ALREADY_PAID 或 QRCODE_NOT_AVAILABLE，则二维码已被消费，状态为最终状态：请勿重试。若未返回上述代码，请先调用 Get Transaction 确认，再视为确定性失败 |
| 500 | 内部错误或状态不确定——交易状态未知。请勿视为最终失败：请调用 Get Transaction 查询（内部故障时可能不会发送 Webhook） |