Payloco 接入与签名
一、集成模式
全量支付方式收银台(integrateMode:"Checkout")
默认集成模式，商户侧只需要提供 checkout 入口，用户点击后跳转进入 Payloco 收银台页面进行支付方式的选择及支付确认。
指定支付方式收银台(integrateMode:"Checkout")
直跳模式，推荐使用；商户侧提供支付方式选择，用户可在商户收银台确认使用的支付方式后，跳转进入 Payloco 收银台页面不用选择就进入支付流程。
capabilityCode指定 或 paymentMethod、paymentBrand 指定;具体 code 值参考支付方式列表
纯 API 模式(integrateMode:"API")
对于完全自有支付收银台、并包含支付方式选择及支付要素收集的商户，仅通过对接 Payloco 的收单 API 接口，即可以完成收单支付流程，可以完全不经过 Payloco 收银台。
- 注意：1、传参必须指定 capabilityCode； 2、非本币报价请使用Checkout模式，不要使用纯API模式
- 响应字段直接取 apiPaymentAuth->nextFlow 的类型，然后去渲染 nextFlowValue 的值。
- 目前支持的 API 模式的受理能力列表： WDNA、WGCH、EWBK、EWNGD、WLNP、TWJKP
二、接口信息
注意不同环境配置
| 环境类型 | 网关 API 地址 | 备注 |
|---|---|---|
| 生产环境 | https://api.payloco.com | 正式业务使用 |
| UAT 环境 | https://uat-api.Payloco.com | 测试使用 |
接口列表
| 产品类型 | 接口名称 | 接口地址 | 描述 |
|---|---|---|---|
| 认证 | 获取Token | /authorize | 使用X-AccessCode和X-SecretKey获取 JWT Token(此接口不加签，其他都要加签)；其余接口header 都要加上Authorization: Bearer + token ；返回的 expireIn 字段表示 token 有效期；注意区分UAT环境与正式环境的接入码和接入密钥 |
| Payin | 下单 | /api/payment/create | 下单接口(注意默认收银台模式:Checkout和纯API支付:API区别) |
| Payin | 交易查询 | /api/payment/get/{transactionId} | 交易查询接口 |
| Payin | 退款 | /api/payment/refund | 交易退款接口 |
| Payin | 异步通知 | /webhook/eventName/acquire.payment.result | 商户接收订单异步通知 |
| Payout | 代付 | /api/payout/create | 商户向用户进行付款(提现) |
| Payout | 代付查询 | /api/payout/query{?requestId,transactionId} | 代付查询 |
| Payout | 代付回调 | /webhook/eventName/payout.result.notify | 代付回调 |
| 账户余额 | 查询账户 | /api/balance/list{?currency} | 商户进行余额查询 |
接口类别
| 类别 | URI | 备注 |
|---|---|---|
| 业务接口 | /api/xxx | 根据业务需要所需对接不同接口；header 要传 Authorization、X-AccessCode、X-Signature |
| 文件接口 | /file/xxx | 文件上传或下载接口，业务接口中使用到的附件类字段，需要先通过文件上传接口获得文件 id，再参与业务接口 |
required 参数必传，其他非必传
API 文档 标注 required 必传，未标注非必传 
三、请求签名
签名说明
加签是开放平台和商户对于交互消息完整性的校验。统一约定：
- 生成的 RSA 密钥对信息：keySize=2048，公钥为 X509 规范，私钥为 PKCS#8 规范
- 公钥交换：双方均将公钥转为 PEM 编码格式(Base64.getMimeEncoder)，便于文本传输和存储，示例：
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnafIZaXpIx6azTZkMS7B
20St6qEHdhv3vW/YLl58KRG1Mgsy5ZiPA6w31el5VSYKF4GQju0qHlYc6cmbpN0Q
z1Z0/xNAugKISIVwnVZw4P1DsYcUIvJaUCt8C+MYXxLUf2FEeCQP3oJCTEaQvIBz
mjFVVCSsAyQ7m3W/EXuwBWoqQJarzKYTLOjPNvRjtRznd1X470/ZEnTIDx/7nZvQ
luHy7hpL3r/YsFEAN0ZVigGcuso1zbqLjwTSi5Uo685F9oHiAs5Y+XE0lihWmb0D
nxVXXRznj191b5H21WVPcnrtKjmO+OSLL0JKlrqx0ndqe1pZBcliO28b0wIg1ftZ
pwIDAQAB
-----END PUBLIC KEY------ 使用 RSA 私钥进行加签， 使用 RSA 公钥进行验签，签名算法为
SHA256withRSA - 注：仅共享公钥即可，私钥请自行妥善保管！
- 附：在线生成密钥对参考 -> 前往（请选择
RSA-2048-无密） - 附：签名/验签源码 Demo -> 下载(Java 版)
- 附：问题排查思路
签名规则
商户加签，Payloco验签
- 商户请求 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加签，商户验签
- Payloco 异步请求通知商户时（即 Webhook），会使用Payloco平台私钥加签。商户请用Payloco平台公钥验签。
- 商户验签：在读取到原始的requestBody 的第一时间就做验签, 中间不能有加工处理
- 统一使用
POST请求，Content-Type=application/json - 约定：商户的回调地址，收到我方异步通知请求时请返回
OK，表示商户成功收到我方该类别通知
四、响应设计
响应数据格式
响应数据以 JSON 格式返回，包含 code（响应码）、msg（响应描述）和 data（业务数据）。
业务响应状态码
Payloco 所有接口成功状态是code=00000000，错误状态是code != 00000000
json
{
"code": "00000000",
"msg": "OK",
"data": {
"orderId": "20241216000001",
"paymentStatus": "CREATED",
"amount": 10000
}
}五、通用信息
金额传送规则
orderAmount订单金额需要乘以 100，例如：订单金额为100.00，则需要传10000，单位为分。
六、流程图
整体图示如下： 