PIX Cash Out -- 按密钥转账

使用收款方的 PIX 密钥执行 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 字符）

认证

详见 认证。HMAC 签名须按照 HMAC-SHA512 中的说明生成。

请求体

字段	类型	必填	描述
amount	Integer	是	金额，以 centavos（分） 为单位。R$ 30.00 = 3000
pix_key	String	是	收款方 PIX 密钥
pix_key_type	String	否	密钥类型：cpf、cnpj、email、phone、evp。如果省略，将根据密钥值自动检测。
description	String	否	转账描述（最多 140 个字符）
external_id	String	否	您系统中的标识符，用于追踪。最大 128 字符。仅 a-zA-Z0-9._:-。在响应和 webhook 中返回。

货币金额

请求金额以 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,
    "pix_key": "12345678901",
    "pix_key_type": "cpf",
    "description": "Pagamento fornecedor",
    "external_id": "order-9876"
  }'

成功响应 -- 200

{
  "worked": true,
  "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603091530abcdef01",
  "external_id": "order-9876",
  "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 中的端到端标识（格式 E{ISPB}...）
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": "Chave PIX invalida"
}

错误响应 -- 422

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

PIX 密钥类型

类型	格式	示例
cpf	11 位数字（无标点）	12345678901
cnpj	14 位数字（无标点）	12345678000199
email	电子邮件地址	nome@empresa.com.br
phone	+55 + 区号 + 号码	+5511999998888
evp	UUID v4	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

后续步骤

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

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

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