API 概览

Owem Pay API 让您将 PIX 支付集成到自己的系统中。所有操作都需要 API Key 和 IP 白名单；POST 端点还需要对 body 添加 HMAC-SHA512 签名。

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）-- 对请求体进行签名；在 POST /pix/cash-in、POST /pix/cash-out、POST /cpf/validate、POST /webhooks、POST /pix/refund 中必须。GET 和 DELETE 请求不携带 HMAC（没有 body 需要签名）。

HMAC body 必须按字母顺序

要求 HMAC 的 POST 请求必须对 body 按键的字母顺序签名。后端对 body 执行 Jason.decode + Jason.encode! 进行验证,这会重新排序键。如果您的客户端在签名前未按字母顺序排列,本地计算的 HMAC 不会与服务器的匹配 → HTTP 401。

完整详情请参阅：HMAC-SHA512。

参见身份验证和 HMAC-SHA512 了解详情。

格式

字段	格式
Content-Type	`application/json`
请求（输入）值	以分（centavos）为单位的整数（R$ 1,00 = `100`）
响应值	以子分（subcentavos,基础单位）为单位的整数（R$ 1,00 = `10000`,÷ 10.000 得到雷亚尔）
日期	UTC 的 ISO 8601,以 `Z` 结尾（`2026-03-09T15:30:00Z`）
ID	UUID v4 或字母数字字符串
E2E ID	`^E\d{8}[a-zA-Z0-9]{22,26}$`（BACEN 标准,31-35 字符,后缀可能含字母）

术语

在本文档中,subcentavos（子分） 和 基础单位 指同一单位（10.000 = R$ 1,00）。"基础单位"一词在一些遗留示例中出现；请将其视为 subcentavos 的同义词。始终将响应值除以 10.000 得到雷亚尔。

E2E 可能包含字母

E + ISPB + timestamp 之后的后缀是 9 到 13 个字母数字字符（不仅是数字）。Nubank 等银行会发出末尾带字母的 E2E。始终使用完整正则校验。详见 PIX 入款（按 E2E ID）。

金额转换

发送时：将雷亚尔乘以 100。R$ 1,00 = 100。 读取响应时：除以 10.000。10000 ÷ 10.000 = R$ 1,00。 绝不要使用浮点数 -- 始终使用整数。

键的大小写（可选 camelCase）

响应 JSON 默认使用 snake_case（例：transaction_id、end_to_end_id）。如果您的客户端更喜欢 camelCase,请发送头：

X-Key-Case: camelCase

后端会自动转换响应 JSON 的所有键（包括嵌套对象）。示例：transaction_id → transactionId,pix_key_type → pixKeyType。该头不影响输入 body — POST 时始终以 snake_case 发送。

响应格式

成功

json

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

错误

错误格式因拒绝请求的层级而不同：

json

// HMAC 插件（401 签名无效）
{ "worked": false, "detail": "Invalid HMAC signature" }

// ApiKeyAuth（401 / 403）
{ "error": { "status": 401, "message": "Invalid API key" } }

// FallbackController（404 / 400 / 409 / 422 / 500 — 业务场景）
{ "errors": { "not_found": "transaction not found" } }

参见完整表格：身份验证 -- 错误响应。

HTTP 状态码

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

速率限制

类型	限制
每 IP（已认证）	90.000 请求/分钟（1.500 req/s）
每 IP（身份验证 / 登录）	5 请求/分钟
`GET /balance`	无速率限制（允许高频轮询）

响应头：

X-RateLimit-Remaining: 59997
Retry-After: 3  （仅 429 时）

幂等性

POST 请求接受头 Idempotency-Key（最多 256 字符）以避免重复处理。只有 **2xx（成功）**响应会被缓存 24 小时。如果同一键被用于同一方法和端点重新发送,API 返回原始响应并附带头 X-Idempotent-Replay: true。

Idempotency-Key: unique-request-id-123

键的作用范围

键与 method + path + Idempotency-Key 绑定。同一键可在不同端点复用而不冲突。错误响应（4xx/5xx）不会被缓存 — 客户端可在修复故障后重试。

GET/DELETE 与 Idempotency-Key

GET 和 DELETE 请求会静默忽略 Idempotency-Key 头 — 插件仅在 POST 时起作用。在这些方法中发送键不会报错,但也不会产生缓存或重放。

重试与隔离策略

隔离（stage=5）：卡在 status: "processing" 超过 30 分钟的 PIX Cash-Out 会被移至隔离区,由 Owem 团队手动处理。从客户端视角看,状态在完成前仍为 "processing"。流程详见：PIX Lifecycle。
Webhook 自动重试：失败的投递（超时、5xx、连接关闭）会在最多 7 次重试中重新调度（间隔 [0, 30s, 2min, 10min, 30min, 1h, 2h, 4h]）。参见 Webhooks。
客户端重试：收到 429 时,请遵守 Retry-After。收到 500 或超时时,使用指数退避 + Idempotency-Key 避免重复。详见身份验证。
Webhook 反重放窗口：头 X-Owem-Timestamp 是 Unix 时间（秒）。服务器不会拒绝旧的 webhook；您的端点有责任丢弃 |now - timestamp| > 300s（±5 分钟）的投递,作为防御深度层反重放机制。参见 Webhooks -- 验证签名。

External ID

在 cash-in 和 cash-out 中接受可选字段 external_id（最多 128 字符,字母数字 + ._:-）。在响应和 webhook 中返回。允许按引用查询：

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

详见概念。

端点

PIX Cash Out（出款）

方法	端点	说明
POST	`/api/external/pix/cash-out`	通过 PIX 密钥或复制粘贴发送 PIX

PIX Cash In（入款）

方法	端点	说明
POST	`/api/external/pix/cash-in`	生成收款二维码

查询

方法	端点	说明
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 ​

身份验证 ​

格式 ​

键的大小写（可选 camelCase） ​

响应格式 ​

成功 ​

错误 ​

HTTP 状态码 ​

速率限制 ​

幂等性 ​

重试与隔离策略 ​

External ID ​

端点 ​

PIX Cash Out（出款） ​

PIX Cash In（入款） ​

查询 ​

账户 ​

PIX 密钥 ​

退款 ​

MED ​

验证 ​

Webhooks ​