API 概述

Owem Pay API 允许您将 PIX 支付集成到您的系统中。所有操作均通过 API Key + HMAC-SHA512 进行身份验证。

基础 URL

环境	URL
生产环境	https://api.owem.com.br

身份验证

所有请求需要：

1. Auth Token -- 通过 POST /api/v2/external/auth-token 获取的 JWT
2. HMAC-SHA512 -- 请求体签名（交易类端点必须提供）

详见 Auth Token 和 HMAC-SHA512。

格式

字段	格式
Content-Type	application/json
货币金额	以分为单位的整数（R$ 100.00 = 10000）
日期	ISO 8601（2026-03-09T15:30:00Z）
IDs	UUID v4 或字母数字字符串
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6位序号}

响应格式

成功

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

错误

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

HTTP 状态码

状态码	含义
200	成功
400	参数无效
401	Token 缺失或已过期
403	HMAC 无效
404	资源未找到
422	验证失败（余额不足、密钥无效）
429	超出请求限制
500	内部错误

请求限制

类型	限制
按 API Key	120 次请求/分钟
按 IP	5 次请求/分钟（未认证）

响应头：

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1709990520

幂等性

写入请求（POST）接受 Idempotency-Key 头以避免重复处理。结果缓存 24 小时。

Idempotency-Key: unique-request-id-123

端点列表

方法	端点	描述
POST	/api/v2/external/auth-token	生成 JWT Token
POST	/api/v2/external/pix/cash-out	发送 PIX
POST	/api/v2/external/pix/cash-out/approve	批准待处理的 cash-out
POST	/api/v2/external/pix/cash-in	生成收款二维码
GET	/api/v2/external/transactions	查询交易列表
GET	/api/v2/external/transactions/:id	按 ID 查询交易
GET	/api/v2/external/transactions/e2e/:e2e_id	按 E2E ID 查询
GET	/api/v2/external/transactions/tag/:tag	按 tag 查询
GET	/api/v2/external/transactions/:id/receipt	交易凭证
GET	/api/v2/external/balance	账户余额
GET	/api/v2/external/statement	账户流水
GET	/api/v2/external/pix/keys	PIX 密钥列表
POST	/api/v2/external/pix/refund	PIX 退款
GET	/api/v2/external/med	MED 列表
GET	/api/v2/external/med/:id	MED 详情
POST	/api/v2/external/cpf/validate	验证 CPF
GET	/api/v2/external/webhooks	Webhook 列表
POST	/api/v2/external/webhooks	注册 Webhook
DELETE	/api/v2/external/webhooks/:id	删除 Webhook