快速入门

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

1. 获取凭证

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

• Client ID -- API Key 标识符
• Client Secret -- 用于身份验证和 HMAC 签名的密钥

安全提示

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

2. 获取访问令牌

所有请求都需要 Bearer Token。使用您的凭证生成 Token：

curl -X POST https://api.owem.com.br/api/v2/external/auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-api-key-id",
    "client_secret": "your-api-key-secret"
  }'

响应：

{
  "worked": true,
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token 在 60 分钟后过期。请在过期前实现自动续期。

3. 查询余额

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

curl -X GET https://api.owem.com.br/api/v2/external/balance \
  -H "Authorization: Bearer $TOKEN"

响应：

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

金额以分为单位

所有货币金额均为分的整数值。150000 = R$ 1,500.00。

4. 生成 PIX 收款请求 (Cash-In)

创建二维码以接收付款：

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"

响应：

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

向付款方展示 qr_code_image 或复制粘贴代码（qr_code）。

5. 查询状态

通过 transaction_id 跟踪付款进度：

curl -X GET https://api.owem.com.br/api/v2/external/transactions/PIXIN20260307a1b2c3d4e5f6 \
  -H "Authorization: Bearer $TOKEN"

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

6. 接收通知 (Webhooks)

要实时接收通知（推荐替代轮询方式）：

BODY='{"url":"https://yoursite.com/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/v2/external/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

后续步骤

• 身份验证 -- Token 流程详解
• HMAC-SHA512 -- 如何为交易请求签名
• PIX Cash-In -- 生成收款请求
• 账户流水 -- 查询交易记录
• Webhooks -- 实时通知
• 核心概念 -- 金额、状态和 PIX 密钥