API 概述

Owem Pay API 允许您将 PIX 支付集成到您的系统中。所有操作均通过 API Key + HMAC-SHA512 进行认证，并要求 IP 白名单。

Base URL

环境	URL
生产环境	`https://api.owem.com.br`
测试环境	`https://api-hml.owem.com.br`

认证

三层独立安全保护：

IP 白名单 -- 来源 IP 必须在 API Key 配置的白名单中
API Key -- 所有请求需包含 Authorization: ApiKey {client_id}:{client_secret} 头
HMAC-SHA512 -- 请求体签名（POST 端点必须提供）

详见认证和 HMAC-SHA512。

格式

字段	格式
Content-Type	`application/json`
请求金额（request）	整数，以 centavos（分）为单位（R$ 30.00 = `3000`）
响应金额	整数，以基本单位为单位（R$ 30.00 = `300000`，/ 10,000 转换为雷亚尔）
日期	ISO 8601（`2026-03-09T15:30:00Z`）
IDs	UUID v4 或字母数字字符串
E2E ID	`E{ISPB}{YYYYMMDD}{HHMM}{6位序号}`

金额换算

发送请求时：将雷亚尔乘以 100。R$ 30.00 = 3000。 读取响应时：除以 10,000。300000 / 10,000 = R$ 30.00。 切勿使用浮点数 -- 始终使用整数。

响应格式

成功

json

{
  "worked": true,
  "transaction_id": "PIXOUT20260309abcdef123456",
  "status": "processing"
}

错误

json

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

HTTP 状态码

状态码	含义
200	成功
201	资源已创建（webhook）
400	参数无效
401	API Key 缺失或无效 / HMAC 签名无效
403	IP 未在白名单中授权
404	资源未找到
422	验证失败（余额不足、密钥无效）
429	超出频率限制
500	内部错误

频率限制

类型	限制
每 IP（已认证）	60,000 次请求/分钟
每 IP（未认证）	5 次请求/分钟

响应头：

X-RateLimit-Remaining: 59997
Retry-After: 3  (仅在 429 时)

幂等性

POST 请求接受 Idempotency-Key 头以避免重复处理。结果缓存 24 小时。如果相同密钥被重新发送，API 返回原始响应并附带头 X-Idempotent-Replay: true。

Idempotency-Key: unique-request-id-123

External ID

可选字段 external_id（最大 128 字符，字母数字 + ._:-）可在 cash-in 和 cash-out 中使用。在响应和 webhook 中返回。支持按引用查询：

GET /api/external/transactions/ref/{external_id}

详见核心概念。

端点列表

PIX Cash Out（付款）

方法	端点	描述
POST	`/api/external/pix/cash-out`	通过密钥或复制粘贴码发送 PIX
POST	`/api/external/pix/cash-out/approve`	审批待处理的 cash-out

PIX Cash In（收款）

方法	端点	描述
POST	`/api/external/pix/cash-in`	生成收款 QR Code

查询

方法	端点	描述
GET	`/api/external/transactions`	查询交易列表
GET	`/api/external/transactions/:id`	按 ID 查询交易
GET	`/api/external/transactions/e2e/:e2e_id`	按 E2E ID 查询
GET	`/api/external/transactions/tag/:tag`	按 tag（前缀）查询
GET	`/api/external/transactions/ref/:external_id`	按 external_id 查询
GET	`/api/external/transactions/:id/receipt`	交易凭证

账户

方法	端点	描述
GET	`/api/external/balance`	账户余额
GET	`/api/external/statement`	账户流水

PIX 密钥

方法	端点	描述
GET	`/api/external/pix/keys`	查询账户的 PIX 密钥

退款

方法	端点	描述
POST	`/api/external/pix/refund`	PIX 退款（全额或部分）

MED

方法	端点	描述
GET	`/api/external/med`	MED 列表
GET	`/api/external/med/:id`	MED 详情

验证

方法	端点	描述
POST	`/api/external/cpf/validate`	验证 CPF

Webhooks

方法	端点	描述
GET	`/api/external/webhooks`	Webhook 列表
POST	`/api/external/webhooks`	注册 Webhook
DELETE	`/api/external/webhooks/:id`	删除 Webhook

API 概述 ​

Base URL ​

认证 ​

格式 ​

响应格式 ​

成功 ​

错误 ​

HTTP 状态码 ​

频率限制 ​

幂等性 ​

External ID ​

端点列表 ​

PIX Cash Out（付款） ​

PIX Cash In（收款） ​

查询 ​

账户 ​

PIX 密钥 ​

退款 ​

MED ​

验证 ​

Webhooks ​