快速入门

将您的应用与 Owem Pay API 集成，几分钟内完成您的第一笔 PIX 操作。

1. 获取凭证

向您的 Owem Pay 账户管理员申请：

• Client ID -- 您的 API Key 标识符（前缀 cli_）
• Client Secret -- 用于认证和 HMAC 签名的密钥（前缀 sk_）

安全提示

切勿在前端代码或公共仓库中暴露 client_secret。请在服务器中使用环境变量。

2. 配置认证

所有请求都需要包含 Authorization 头及您的 API Key 凭证：

# 头格式：
Authorization: ApiKey {client_id}:{client_secret}

API Key 是永久的 -- 不会过期。无需生成令牌。

3. 查询余额

通过查询账户余额来测试集成：

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

响应：

{
  "worked": true,
  "balance": 300000,
  "available": 300000,
  "pending": 0,
  "currency": "BRL"
}

货币金额

请求中的金额以 centavos（分） 为单位：R$ 30.00 = 3000。 响应中的金额以基本单位为单位：300000 / 10,000 = R$ 30.00。 切勿使用浮点数 -- 始终使用整数。

4. 生成 PIX 收款（Cash-In）

创建 QR Code 以收取 R$ 30.00：

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"

响应：

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}

请注意，您发送了 3000（centavos）并收到了 300000（基本单位）。两者都表示 R$ 30.00。

将 qr_code_image 或复制粘贴码（qr_code）展示给付款人。

5. 查询状态

通过 transaction_id 跟踪付款状态：

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

当付款确认后，status 将变为 completed。

您也可以通过 external_id 查询：

curl -X GET https://api.owem.com.br/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

6. 接收通知（Webhooks）

要接收实时通知（推荐使用，优于轮询）：

BODY='{"url":"https://seusite.com.br/webhook","events":["pix.received","pix.completed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

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

后续步骤

• 认证 -- API Key + HMAC（3 层安全保护）
• HMAC-SHA512 -- 如何签名交易类请求
• PIX Cash-In -- 生成收款
• PIX Cash-Out -- 通过密钥发送 PIX
• 账单 -- 查询交易记录
• Webhooks -- 实时通知
• 核心概念 -- 金额、状态、external_id、幂等性和 PIX 密钥