PIX Cash In -- 生成 QR Code

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

端点

POST /api/external/pix/cash-in

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
Content-Type	String	是	application/json
hmac	String	是	请求体的 HMAC-SHA512 签名（了解详情）
Idempotency-Key	String	否	避免重复处理的唯一密钥（最大 256 字符）

请求体

字段	类型	必填	描述	示例
amount	Integer	是	金额，以 centavos（分） 为单位（R$ 30.00 = 3000）	3000
description	String	否	收款描述（最多 140 个字符）	"Pedido #1234"
external_id	String	否	您系统中的标识符，用于追踪。最大 128 字符。仅 a-zA-Z0-9._:-。在响应和 webhook 中返回。	"order-9876"

货币金额

请求金额以 centavos（分）为单位（R$ 1.00 = 100）。响应金额以基本单位为单位（R$ 1.00 = 10000）。将响应除以 10,000 转换为雷亚尔。切勿使用浮点数。

示例

BODY='{"amount":3000,"description":"Pedido #1234","external_id":"order-9876"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

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

成功响应 (200)

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,iVBORw0KGgo...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active",
  "expires_at": "2026-03-07T16:30:00Z"
}

字段	类型	描述
worked	Boolean	true 表示操作成功
transaction_id	String	收款唯一标识（QR Code 的 tx_id）
qr_code	String	用于支付的 EMV 复制粘贴码
qr_code_image	String	Base64 编码的 QR Code 图片 (PNG)
external_id	String	您的标识符，原样返回。未提供时为 null
amount	Integer	收款金额，以基本单位为单位（/ 10,000 = 雷亚尔）。300000 = R$ 30.00
status	String	初始状态：active（QR Code 已激活，等待付款）
expires_at	String	QR Code 过期时间（ISO 8601）

错误响应 (400)

{
  "worked": false,
  "detail": "O campo amount e obrigatorio"
}

错误响应 (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

错误响应 (422)

{
  "worked": false,
  "detail": "Invalid HMAC signature"
}

推荐流程

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

QR Code 有效期

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