PIX Cash In -- 生成二维码

生成 PIX 收款二维码，用于将资金收入与您的 API Key 关联的账户。

端点

POST /api/v2/external/pix/cash-in

请求头

请求头	类型	必填	描述
Authorization	String	是	Bearer {access_token}
Content-Type	String	是	application/json
hmac	String	是	请求体的 HMAC-SHA512 签名（了解详情）

请求体

字段	类型	必填	描述	示例
amount	Integer	是	金额（分）	10000（R$ 100.00）
description	String	否	收款描述（最多 140 个字符）	"订单 #1234"

金额以分为单位

所有货币金额均为分的整数值。R$ 100.00 = 10000。除以 100 即可得到雷亚尔金额。

示例

BODY='{"amount":10000,"description":"订单 #1234"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/v2/external/pix/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

成功响应 (200)

{
  "worked": true,
  "transaction_id": "PIXIN20260307a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603071530000001",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,iVBORw0KGgo...",
  "amount": 10000,
  "status": "pending"
}

字段	类型	描述
worked	Boolean	true 表示操作成功
transaction_id	String	交易唯一标识
end_to_end_id	String	BACEN 端到端 ID (E2E)
qr_code	String	用于支付的 EMV 复制粘贴代码
qr_code_image	String	Base64 编码的二维码图片 (PNG)
amount	Integer	收款金额（分）
status	String	初始状态：pending（等待支付）

错误响应 (400)

{
  "worked": false,
  "detail": "amount 字段为必填"
}

错误响应 (401)

{
  "worked": false,
  "detail": "Token 无效或已过期"
}

错误响应 (422)

{
  "worked": false,
  "detail": "HMAC 无效"
}

推荐流程

1. 使用此端点生成收款请求
2. 向付款方展示二维码（qr_code_image）或复制粘贴代码（qr_code）
3. 通过 Webhook 接收支付成功确认
4. 或查询状态：按 ID 查询、按 E2E 查询、按 Tag 查询

二维码有效期

生成的二维码有效期为 24 小时。过期后收款请求自动失效，状态变为 cancelled。