PIX Cash Out -- 复制粘贴码

使用从 PIX QR Code 中提取的 EMV 代码（复制粘贴码）执行 PIX 转账。

端点

POST /api/external/pix/cash-out

请求头

头	类型	必填	描述
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
emv_code	String	是	PIX QR Code 的 EMV 复制粘贴码
description	String	否	转账描述（最多 140 个字符）
external_id	String	否	您系统中的标识符，用于追踪。最大 128 字符。仅 a-zA-Z0-9._:-。在响应和 webhook 中返回。

复制粘贴码

emv_code 字段接受从 PIX QR Code 复制的完整 EMV 代码。API 自动从 EMV 载荷中提取 PIX 密钥、收款方信息和原始收款金额。

转账金额

即使 QR Code 中已包含金额，仍必须填写 amount 字段。API 会验证填写的金额与 QR Code（静态或动态）兼容。

货币金额

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

示例

curl -X POST https://api.owem.com.br/api/external/pix/cash-out \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d '{
    "amount": 3000,
    "emv_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR5913NOME RECEBEDOR6008BRASILIA62070503***6304ABCD",
    "description": "Pagamento via QR Code",
    "external_id": "invoice-4521"
  }'

成功响应 -- 200

{
  "worked": true,
  "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603091530abcdef01",
  "external_id": "invoice-4521",
  "amount": 300000,
  "fee_amount": 350,
  "net_amount": 300350,
  "status": "processing",
  "detail": "PIX enviado para processamento"
}

字段	类型	描述
worked	Boolean	true 表示请求已被接受
transaction_id	String	交易唯一标识
end_to_end_id	String	SPI/BACEN 中的端到端标识
external_id	String	您的标识符，原样返回。未提供时为 null
amount	Integer	转账金额，以基本单位为单位（/ 10,000 = 雷亚尔）。300000 = R$ 30.00
fee_amount	Integer	手续费，以基本单位为单位（/ 10,000 = 雷亚尔）
net_amount	Integer	净额（amount + fee），以基本单位为单位
status	String	processing（清算中）或 completed（已清算）
detail	String	描述信息

错误响应 -- 400

{
  "worked": false,
  "detail": "Codigo EMV invalido ou nao reconhecido"
}

错误响应 -- 422

{
  "worked": false,
  "detail": "Saldo insuficiente"
}

后续步骤

创建转账后，可通过以下方式查询状态：

• 按 ID 查询
• 按 E2E ID 查询
• 按 Tag 查询
• 按 External ID 查询 -- GET /api/external/transactions/ref/{external_id}

或通过 Webhook 自动接收确认通知。