API规范

商户准备

商户通过账号和密码登录商户平台，并完成以下操作。

获取平台公钥/API Key/Secret Key

平台公钥：由UPay提供,用于请求API时参数加密。

API Key：由UPay提供，商户的唯一标识。

Secret Key：秘钥，用于请求API时数据签名

配置商户公钥

商户公钥生成规则可参考 鉴权签名 & 数据加密

设置回调地址

可配置接收UPay主动推送的 Webook 数据。

• 如果不需要WebHook数据，可忽略该配置。
• 如果填写Webhook地址，需提交UPay进行验证。

设置白名单IP

可配置允许访问 API 的 IP 地址。

• 如果不设置，则默认允许所有 IP 访问。
• 支持设置多个 IP 地址
• 多个 IP 之间请使用英文逗号 , 分隔
• 示例：127.0.0.1,127.0.0.2

请求/响应头说明

请求头说明

字段	数据类型	说明	作用
X-UPA-APIKEY	String	请求 API KEY	标识区分出来白标用户
X-UPA-REQUESTID	String	请求唯一码	请求幂等
X-UPA-TIMESTAMP	String	时间戳，毫秒	请求时间，超过 60 秒后，超时，不响应此请求。防止重放攻击。
X-UPA-SIGN	String	签名	签名，验证请求正确性。

X-UPA-APIKEY

APIKEY 是 UPay 分配的唯一请求的 Key，拥有该 Key 后方可拥有调用权限。

X-UPA-REQUESTID

X-UPA-REQUESTID 是每次请求和响应的唯一请求ID， 主要作用如下：

• 确保请求唯一，会将该请求做幂等处理。
• 唯一请求查询。
• 响应与请求一致，利于您的架构调整。

X-UPA-SIGN

签名，验证请求正确性

响应头说明

字段	数据类型	说明
X-UPA-REQUESTID	String	请求唯一码，与请求 ID 相同，确保响应一致性
X-UPA-TIMESTAMP	String	响应时间戳，时间戳，毫秒

请求加密 & 响应解密

• 部分接口需要对请求参数和响应内容通过私钥进行加密，具体接口参见API List
• 加解密参考文档 参数加解密

请求加密

• API参数需要加密时，通过平台公钥将参数进行加密.

  

  请求示例：

  {
  	"payload":"加密后的数据"
  }
  

响应解密

• UPay通过商户公钥对响应数据进行加密

  

  响应示例：

  JSON

  {
      "code": 0,
      "data": {
          "payload": "加密数据"
      },
      "msg": "Success",
      "success": true,
      "ts": 1774589644
  }
  

• 获取到响应数据，商户通过商户私钥进行解密，得到响应的原始数据

其他请求说明

请参考具体接口细节