跳转到主要内容
Localpayment 使用 OAuth 2.0 Bearer 令牌认证来保护 API 访问。所有 API 请求都需要在 Authorization 请求头中包含有效的访问令牌。本指南概述了认证概念和安全要求。 安全认证是 API 集成的基础。Localpayment 基于令牌的认证机制确保只有授权请求才能访问您的账户数据并处理交易。

OAuth 2.0

行业标准 Bearer 令牌认证

短期令牌

60 分钟访问令牌,增强安全性

安全要求

关键安全要求遵循以下做法,确保API集成安全。

HTTPS加密

所有 API 通信都必须使用 HTTPS 来保护传输中的数据。

仅限服务器端

API 请求必须仅来自安全服务器环境。

IP白名单

在控制面板中配置 IP 白名单以授权 API 调用

安全凭证存储

使用环境变量或密钥管理系统

身份验证 endpoint

使用这些专用 endpoint 管理您的 API 身份验证:

获取访问令牌

使用您的 API 凭据获取新的访问令牌和刷新令牌

刷新访问令牌

使用刷新令牌获取新的访问令牌,无需重新验证身份

快速示例

生成令牌:
curl
使用令牌:
curl

令牌过期

Localpayment 使用短期令牌以增强安全性:

访问令牌

60 分钟
用于 API 请求
生命周期短,更安全

刷新令牌

120 分钟
用于获取新的访问令牌
生命周期长,更方便

令牌生命周期

  1. 获取令牌:通过获取访问令牌申请一对访问令牌和刷新令牌。
  2. 重复使用访问令牌:在访问令牌有效期内,每个请求都发送同一个访问令牌。
  3. 过期后续期:当访问令牌过期或收到 401 未授权响应时,通过获取访问令牌申请新的令牌对。
  4. 替换已存储的令牌对:存储两个新令牌,并丢弃之前的令牌。
使用刷新 endpoint如果您的集成已在使用刷新访问令牌 endpoint,它仍然可用。每次刷新成功都会返回新的令牌对,您发送的刷新令牌随即失效。新的获取访问令牌请求也会使同一用户和集成此前签发的刷新令牌失效。

令牌管理最佳实践

每个集成一对令牌

每个用户和集成只保留一对令牌,并在所有进程和 worker 之间共享。

替换整个令牌对

每次申请或刷新令牌后,同时存储新的访问令牌和新的刷新令牌。

避免并行登录

不要使用同一用户并行申请令牌。每次新的令牌申请都会使之前的刷新令牌失效。

不要重试失败的刷新

如果刷新返回 401,请通过获取访问令牌申请新令牌,而不要重试同一个刷新令牌。

错误处理

401 未授权

令牌无效或已过期
解决方案:通过获取访问令牌申请新令牌。如果刷新返回此错误,请不要重试同一个刷新令牌。

401 未授权

IP 未加入白名单
获取访问令牌会返回 “Invalid IP for user. Please validate that 203.0.113.10 is whitelisted in your account settings.”
解决方案:在控制面板中将您的服务器 IP 添加到白名单。
最后修改于 2026年11月12日