登录

Transaction API 采用基于 JWT（JSON Web Tokens）的健全身份验证机制，以保障交易的安全与隔离。

获取凭据

前置条件

• 必须已在平台上注册账号。

可用环境

生产环境

https://api.gateway.com.br/core

身份验证流程

端点

• 方法：POST
• 端点：/auth/token

所需凭据

凭据	说明	必填
client_id	唯一标识	是
client_secret	认证用的密钥	是

首次接入请通过 App 获取凭据；若已有访问权限，可通过接口获取凭据

请求示例

cURL

curl --request POST \
--url https://api.gateway.com.br/core/auth/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=your-client-id' \
--data-urlencode 'client_secret=your-client-secret' \
--data-urlencode 'grant_type=client_credentials'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    grant_type: 'client_credentials'
  })
});

const { access_token, expires_in } = await response.json();

成功响应

字段	类型	说明
access_token	string	用于认证的 JWT token
expires_in	number	token 过期时刻的 Unix 时间戳
refresh_expires_in	number	refresh token 的过期时长
token_type	string	token 类型（始终为 "Bearer"）
not-before-policy	number	生效时间策略
scope	string	token 的访问权限范围
expires_in_sec	number	token 的有效时长，单位为秒

说明：scope 字段返回以逗号分隔的权限范围。

响应示例

{
  "access_token": "eyJhbGci...",
  "expires_in": 1759845450,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "email,profile",
  "expires_in_sec": 3600
}

在请求中使用 token

向接口发起的每一个请求，都需要在 Authorization 请求头中携带 JWT token。

cURL

curl --request POST \
--url https://api.gateway.com.br/core/transaction \
--header 'Authorization: Bearer your-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
  // 在此填入您的报文
}'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/transaction', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    // 在此填入您的报文
  })
});

Python

response = requests.post(
    "https://api.gateway.com.br/core/transaction",
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        # 在此填入您的报文
    }
)

错误处理

状态码	说明
401	凭据无效
400	凭据格式有误
502	Bad Gateway（连接身份验证服务时出错）

说明： 错误码与错误信息可能随身份验证服务的响应而变化。

安全最佳实践

1. token 管理

   • 安全地保存 token
   • 在过期前及时续期
   • 切勿泄露 client_secret
   • 定期重新校验并轮换密钥，团队或组织结构发生变动时也应轮换

2. 安全相关请求头

   • 生产环境使用 HTTPS
   • 实施限流
   • 对每个请求都校验身份

3. 监控

   • 记录访问尝试
   • 关注可疑模式
   • 配置告警