Payloco 接入与签名
一、集成模式
全量支付方式收银台(integrateMode:"Checkout")
默认集成模式，商户侧只需要提供 checkout 入口，用户点击后跳转进入 Payloco 收银台页面进行支付方式的选择及支付确认。
指定支付方式收银台(integrateMode:"Checkout")
指定支付模式，推荐使用；商户侧提供支付方式选择，用户可在商户收银台确认使用的支付方式后，跳转进入 Payloco 收银台页面不用选择就进入支付流程。
capabilityCode指定 或 paymentMethod、paymentBrand 指定;具体 code 值参考支付方式列表
纯API直连模式(integrateMode:"API")
对于完全自有支付收银台、并包含支付方式选择及支付要素收集的商户，仅通过对接Payloco的收单API接口，即可以完成收单支付流程，可以完全不经过Payloco收银台。
1. 纯API模式是指在创建支付订单同时完成渠道下单并返回渠道的支付链接（如deeplink,QR RawData等），商户根据返回的支付介质完成收银台的渲染或者跳转动作。
2. API模式必须上送必要参数
- integrateMode:"API"模式下传参必须指定能力简码capabilityCode，上送该字段后paymentMethod和paymentBrand可不上送；
- 非本币报价请使用Checkout模式，不要使用纯API模式
- "deviceInfo": 直连模式下，由于不经过Payloco的收银台，设备信息的采集工作需要由商户完成，是为了保证能在渠道测正确完成订单创建。同时准确的设备信息可以有效的避免被渠道或者钱包的风控系统误杀。因此直连模式下强烈建议上送完整且准确的设备信息。
3. 请求报文示例
4. 纯API模式下需自行处理返回报文, 创建订单成功的情况下会返回apiPaymentAuth节点，开发者需要根据apiPaymentAuth.nextFlow 节点的内容判断下一步动作
- 当nextFlow=Redirect时，可直接将用户浏览器重定向到nextFlowValue的url地址
- 当nextFlow=RedirectPost时，开发者需要将nextFlowObject中的参数组装成一个http的请求并以method=post的形式提交到nextFlowValue
- 当nextFlow=QrCode时，开发者需要将nextFlowValue的内容渲染成为二维码图片在商户收银台展示
- 当nextFlow=BarCode时，开发者需要将nextFlowValue的内容渲染成为条形码图片在商户收银台展示
- 当nextFlow=BankAccount时，开发者需要将nextFlowObject中的JSON格式的键值对渲染成为银行账户相关信息在商户收银台展示
- 当nextFlow=Description时，开发者需要将nextFlowObject中的JSON格式的键值对渲染成为提示信息在商户收银台展示
5. 兼容性说明
- 当API模式创建订单失败时，则不会返回apiPaymentAuth节点的信息，这种情况表明由于DeviceInfo节点的数据准确性不足导致的渠道创建订单无法成功，这种情况下仍然可以通过重定向到checkoutUrl的方式降级成为收银台模式，从而保证客户可以通过Payloco收银台完成支付。
- 因此建议开发者将checkoutUrl作为兜底的处理逻辑，Payloco的收银台已经实现了第5点中提到的所有场景。
二、接口信息
注意不同环境配置
| 环境类型 | 网关 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，单位为分。
六、流程图
整体图示如下： 