核心概念
与 Owem Pay API 集成的基本概念。
身份验证模型
API 采用两级身份验证：
| 组件 | 描述 | 用途 |
|---|---|---|
| Bearer Token | 通过 /api/v2/external/auth-token 生成的 JWT | 所有请求的 Authorization: Bearer {token} 头 |
| HMAC-SHA512 | 请求体签名 | 交易类请求 (POST) 的 hmac 头 |
身份验证流程
- 将
client_id和client_secret发送到 auth-token 端点 - 获取
access_token（有效期 60 分钟） - 在所有请求中包含 Token：
Authorization: Bearer {access_token} - 对于 POST 请求，计算请求体的 HMAC-SHA512 并通过
hmac头发送
完整详情：身份验证 | HMAC-SHA512
货币金额
所有金额均以分为单位的整数表示。切勿使用浮点数。
| 金额 | 表示 | JSON 字段 |
|---|---|---|
| R$ 1.00 | 100 | "amount": 100 |
| R$ 150.50 | 15050 | "amount": 15050 |
| R$ 1,000.00 | 100000 | "amount": 100000 |
| R$ 10,000.00 | 1000000 | "amount": 1000000 |
换算
分转雷亚尔：除以 100。雷亚尔转分：乘以 100 并四舍五入。
交易状态
| 状态 | 描述 |
|---|---|
pending | 等待支付或批准 |
processing | 交易在 SPI 中处理中 |
completed | 交易成功完成 |
settled | BACEN 确认清算 |
failed | 交易失败 |
refunded | 交易已退款（全额或部分） |
cancelled | 交易已取消或过期 |
端到端 ID (E2E ID)
PIX 交易在央行生态系统中的唯一标识。标准格式：
E{ISPB}{YYYYMMDDHHMM}{序号}示例： E37839059202603071530000001
| 组成部分 | 值 | 描述 |
|---|---|---|
E | 固定前缀 | 标识为 E2E ID |
37839059 | Owem Pay 的 ISPB | 8 位数字 |
202603071530 | UTC 日期和时间 | YYYYMMDDHHMM（12 位） |
000001 | 序号 | 6 位数字 |
E2E ID 由 Owem Pay 自动生成，并在每次 PIX 操作的响应中返回。用于在机构间追踪交易。
PIX 密钥类型
| 类型 | 格式 | 示例 | 个人限额 | 企业限额 |
|---|---|---|---|---|
cpf | 11 位数字 | 12345678901 | 1 | -- |
cnpj | 14 位数字 | 12345678000190 | -- | 1 |
email | 有效邮箱 | contato@empresa.com.br | 5 | 20 |
phone | +55 + 区号 + 号码 | +5511999998888 | 5 | 20 |
evp | UUID v4（随机密钥） | a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d | 5 | 20 |
响应格式
所有 API 响应遵循以下格式：
成功
json
{
"worked": true,
...
}错误
json
{
"worked": false,
"detail": "错误描述"
}worked 字段表示操作是否成功（true）或失败（false）。出错时，detail 字段描述原因。