PIX 二维码 Cash-Out

概述

PIX 二维码 Cash-Out 端点允许您通过扫描或复制的二维码（复制粘贴）进行 PIX 付款。二维码必须遵循巴西中央银行的 EMV 标准。收款方数据会自动从二维码中提取，简化付款流程。

此端点需要有效的 Bearer token。详情请参阅认证文档。

PIX 密钥 vs 二维码：该使用哪个端点？

Avista API 提供两个端点用于发送 PIX 付款。请根据您的使用场景选择最合适的端点：

标准	按 PIX 密钥 Cash-Out	二维码 Cash-Out
端点	`POST /api/pix/cash-out`	`POST /api/pix/cash-out-qrcode`
适用场景	已知收款方的 PIX 密钥	拥有收款方生成的二维码
收款方数据	必填（密钥、类型、姓名、证件号）	嵌入在二维码中（请求中可选）
金额验证	仅验证余额和限额	验证余额、限额 + 二维码金额与提供金额的匹配
密钥类型	CPF、CNPJ、邮箱、手机号、随机密钥	不适用（信息在二维码内）
确认 webhook	`CashOut` 事件	相同的 `CashOut` 事件
响应	相同结构	相同结构

使用密钥 Cash-Out：当您的应用已有收款方数据时（如工资发放、程序化付款）
使用二维码 Cash-Out：当付款从扫描的二维码发起时（如 POS 终端、账单支付、复制粘贴）

两个端点返回相同的响应结构，并在确认时触发相同的 CashOut webhook。

功能特性

支持静态或动态二维码付款
自动验证二维码嵌入的金额
发送前自动验证余额
通过 externalId 唯一标识（幂等性）
自动计算手续费

端点

POST /api/pix/cash-out-qrcode

通过二维码发起 PIX 付款。

必需请求头

Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "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": "Destinatario Ltda",
  "document": "12345678000190"
}

请求

curl -X POST https://api.safirapay.com/api/pix/cash-out-qrcode \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -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": "Destinatario Ltda",
    "document": "12345678000190"
  }'

响应 (201 Created)

{
  "transactionId": "456",
  "externalId": "QRPAY-987654-20240119",
  "status": "PENDING",
  "generateTime": "2024-01-19T14:30:00.000Z"
}

请求参数

valuenumberobrigatorio

付款金额，单位为 BRL（巴西雷亚尔）。最多 2 位小数。如果二维码包含嵌入金额，提供的金额必须匹配（容差 1 分）。

最小值： 0.01

示例： 15.50

qrCodestringobrigatorio

PIX 二维码内容（EMV 字符串）。可通过相机扫描或从复制粘贴字段获取。

最小长度： 50 个字符

最大长度： 500 个字符

格式： 必须以 000201 开头（中央银行 PIX EMV 标准）

示例： "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540515.505802BR5925DESTINATARIO LTDA6009SAO PAULO62070503***6304ABCD"

externalIdstringobrigatorio

唯一的外部交易标识符。确保幂等性 -- 重复发送相同的 externalId 会导致 409 错误。

最大长度： 255 个字符

建议： 使用确保唯一性的格式

示例： "QRPAY-987654-20240119"

descriptionstring

付款描述，将显示在收款方的账单中。

最大长度： 140 个字符

默认值： 空

示例： "Pagamento fornecedor XYZ via QR Code"

namestring

收款方名称。可选 -- 省略时使用二维码数据。

示例： "Destinatario Ltda"

documentstring

收款方的 CPF 或 CNPJ（仅数字）。可选 -- 省略时使用二维码数据。

CPF： 11 位数字

CNPJ： 14 位数字

示例： "12345678000190"

响应结构

transactionIdstringsempre presente

Avista 生成的内部交易 ID。

示例： "456"

externalIdstringsempre presente

请求中提供的外部 ID（与输入值相同）。

示例： "QRPAY-987654-20240119"

statusstringsempre presente

当前交易状态。

可选值：

PENDING：付款处理中
CONFIRMED：付款已确认并完成
ERROR：处理错误

示例： "PENDING"

注意： 大多数 PIX 付款在几秒内即可确认

generateTimestringsempre presente

付款创建日期和时间（ISO 8601 UTC）。

示例： "2024-01-19T14:30:00.000Z"

二维码验证

PIX 二维码遵循巴西中央银行定义的 EMV (Europay, Mastercard, Visa) 标准。在发送到 API 之前，您可以在本地进行验证：

function isValidPixQrCode(qrCode: string): boolean {
  // Check minimum and maximum length
  if (qrCode.length < 50 || qrCode.length > 500) {
    return false;
  }

  // Check mandatory EMV prefix
  if (!qrCode.startsWith('000201')) {
    return false;
  }

  return true;
}

EMV PIX 二维码结构：

000201 -- 负载格式指示符（必填）
0102XX -- 发起方式（11 = 静态，12 = 动态）
包含收款方数据、金额、城市等字段
6304XXXX -- CRC16（校验和）

完整的二维码验证（EMV 解码、CRC 校验和数据提取）由 API 自动完成。本地验证仅用于过滤明显无效的二维码。

响应状态码

状态码	错误	描述
`201`	--	PIX 二维码付款发起成功
`400`	`INVALID_QR_CODE`	二维码无效或格式错误
`400`	`QR_CODE_VALUE_MISMATCH`	提供的金额与二维码嵌入的金额不匹配
`400`	`INSUFFICIENT_BALANCE`	余额不足以完成交易
`401`	--	未提供令牌、令牌已过期或无效
`409`	`DUPLICATE_EXTERNAL_ID`	`externalId` 已在其他交易中使用