Payloco 接入与签名

一、接口概述

此文档用于介绍 Payloco 开发者在配置设置方面的相关内容，涵盖了不同环境的配置信息、签名与验签的配置、回调地址设置等，帮助开发者完成必要的配置以使用 Payloco 的支付服务。
整体图示如下： alt text

二、接口信息

不同环境配置

环境类型	网关地址	备注
生产环境	https://api.payloco.com	正式业务使用
UAT 环境	https://uat-api.payloco.com	测试使用

接口大类

类别	URI	备注
认证	/authorize	使用接入码（X-AccessCode）和接入密钥(X-SecretKey)，获取 JWT Token
业务接口	/api/xxx	根据业务需要所需对接不同接口
文件接口	/file/xxx	文件上传或下载接口，业务接口中使用到的附件类字段，需要先通过文件上传接口获得文件 id，再参与业务接口

三、请求签名

签名说明

加签是开放平台和商户对于交互消息完整性的校验。加签行为主要发生两个部分：

a. 商户对请求 Payloco 发送的请求报文进行加签
b. Payloco 对通知商户的异步消息进行加签

统一约定：

生成的 RSA 密钥对信息：keySize=2048，公钥为 X509 规范，私钥为 PKCS#8 规范
公钥交换：双方均将公钥转为 PEM 编码格式(Base64.getMimeEncoder)，便于文本传输和存储，示例：

使用 RSA 私钥进行加签，使用 RSA 公钥进行验签，签名算法为 SHA256withRSA
注：仅共享公钥即可，私钥请自行妥善保管！
附：在线生成密钥对参考 -> 前往（请选择 RSA-2048-无密）
附：签名/验签源码 Demo -> 下载(Java 版)

签名规则

商户签名，我方验签
- 商户请求 Payloco 时，商户使用自身私钥 request.body 进行签名，代码示例：
```
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
// 计算 SHA256withRSA 签名时，需要以 utf-8 的编码转换 byte 流，否则可能导致含中文参数的签名计算不正确
signature.update(request.body);
byte[] signedHash = signature.sign();
```
- 对签名内容进行 Base64 编码，提高可读性
```
String signature = Base64.getEncoder().encodeToString(signedHash);
```
- 可以使用了。商户请求 Payloco 时，将 signature 签名添加到请求头(X-Signature)。
- 注：仅对 POST 接口加签；对 request.body 进行签名，当某些 request.body 为空时，则无需加签。
我方加签，商户验签
- Payloco 异步请求通知商户时（即 Webhook），使用 Payloco 私钥加签，加签逻辑如上
- 统一使用 POST 请求，Content-Type=application/json
- 约定：商户的回调地址，收到我方异步通知请求时请返回 OK，表示商户成功收到我方该类别通知

四、响应设计

响应状态码

状态码	说明
200	请求已受理
400	请求参数错误
401	未授权，签名验证失败
403	禁止访问
404	未找到相关资源

响应数据格式

响应数据以 JSON 格式返回，包含 code（响应码）、msg（响应描述）和 data（业务数据）。

json

{
  "code": "00000000",
  "msg": "OK",
  "data": {
    "orderId": "20241216000001",
    "paymentStatus": "CREATED",
    "amount": 10000
  }
}

五、通用信息

多语言

Payloco 提供多语言支持，默认语言为英文。

Payloco 接入与签名 ​

一、接口概述 ​

二、接口信息 ​

不同环境配置 ​

接口大类 ​

三、请求签名 ​

签名说明 ​

签名规则 ​

四、响应设计 ​

响应状态码 ​

响应数据格式 ​

五、通用信息 ​

多语言 ​