Appearance
WantoPay OpenAPI
商户代付对接文档。左侧栏目跳转至对应章节。
仅服务端调用
API 私钥、商户响应私钥不得出现在浏览器、App、小程序、URL 或公开日志中。
介绍
WantoPay OpenAPI 面向已开通代付产品的商户,通过服务端 HTTPS 调用完成收款人维护、代付下单与结果查询。
| 能力 | 说明 |
|---|---|
| 代付 OpenAPI | 收款人、算费、下单、查单、余额 |
| 安全协议 | JWT 身份 + 业务报文加解密 |
| Webhook | 订单进入成功 / 失败终态时异步通知 |
| 开发者中心 | 商户后台自助管理密钥与回调 |
协议一句话:
text
Authorization: Bearer {JWT} ← API 私钥 HS256 签名
Body: { "livemode": false, "data": "{compactPayload}" }
↑ 业务 JSON 经 RSA-OAEP-256 + AES-256-GCM 加密WantoPay 另有机构侧 OpenAPI(Header HMAC + 明文 JSON)。商户代付请只使用本文 JWT + 加密协议,两套不可混用。
前置条件:
- 商户已完成入驻 / KYC(以运营要求为准)
- 运营已开通产品码
DISBURSEMENT - 开发者中心已创建凭证并配置响应密钥(Webhook 强烈建议配置)
环境
| 环境 | livemode | 用途 |
|---|---|---|
| 沙箱(Sandbox) | false | 联调、验收;资金为测试额度 |
| 生产(Live) | true | 真实代付 |
Base URL 占位
上线前以开发者中心或运营下发地址为准。
| 环境 | Base URL 示例 |
|---|---|
| 沙箱 | https://openapi-sandbox.wantopay.example/openapi-server |
| 生产 | https://openapi.wantopay.example/openapi-server |
text
POST {BaseURL}/openapi/v1/disbursement/order/create- JWT 与 body 中的
livemode必须为 Boolean,且完全一致。 - 沙箱与生产密钥隔离。
| 材料 | 说明 |
|---|---|
merchantId | 商户标识,放入 JWT |
apiPrivateKey | 生成 JWT;创建时仅展示一次 |
platformRequestPublicKey | 加密请求 data |
merchantResponsePrivateKey | 解密响应 / Webhook data |
merchantResponsePublicKey | 上传给平台,加密响应用 |
平台请求私钥仅由 WantoPay 持有。
快速开始
以沙箱算费为例。
1. 准备材料
text
merchantId
livemode = false
apiPrivateKey
platformRequestPublicKey
merchantResponsePrivateKey
baseUrl = 沙箱 Base URL2. 业务明文
json
{
"currency": "USD",
"transferAmount": 100.00
}3. 加密为 compact data
用平台请求公钥加密明文(见下文「报文加解密」),外层:
json
{
"livemode": false,
"data": "{compactPayload}"
}4. 生成 Authorization
http
Authorization: Bearer {jwt}
Content-Type: application/json; charset=UTF-8
X-Request-Id: {uuid}5. 发送请求
http
POST /openapi/v1/disbursement/order/calc HTTP/1.1
Host: {sandbox-host}
Authorization: Bearer {jwt}
Content-Type: application/json; charset=UTF-8
Accept: application/json
X-Request-Id: 83196038-3d30-4b23-93fc-5997fa769455
{
"livemode": false,
"data": "{compactPayload}"
}6. 解密响应
json
{
"code": 0,
"msg": "",
"livemode": false,
"data": "{compactPayload}"
}code = 0 时用商户响应私钥解密 data。
建议联调顺序:算费 → 创建收款人 → 下单 → 查单 → Webhook。
安全总览
| 层 | 算法 | 作用 |
|---|---|---|
| 身份 / 防重放 | Bearer JWT,HS256,密钥 = API 私钥原文 | 身份、jti/exp、livemode |
| 报文 | RSA-OAEP-256 + AES-256-GCM compact | 机密性 + 完整性 |
| 传输 | HTTPS | 信道 |
| 场景 | RSA 加密公钥 | RSA 解密私钥 | 解密方 |
|---|---|---|---|
请求 data | 平台请求公钥 | 平台请求私钥 | 平台 |
响应 / Webhook data | 商户响应公钥 | 商户响应私钥 | 商户 |
text
商户 WantoPay
API 私钥 ──▶ 签 JWT ──────────────────▶ 验签
平台请求公钥 ──▶ 加密请求 data ───────▶ 平台请求私钥解密
商户响应私钥 ◀── 解密响应 data ◀─────── 商户响应公钥加密TIP
不需要传递密钥编号。data 固定为 compact 五段式。
POST 流程:明文 JSON → 平台请求公钥加密 → 组 { livemode, data } → 签 JWT → 发送 → 商户响应私钥解密响应。
Bearer JWT
Header
json
{
"typ": "JWT",
"alg": "HS256"
}只接受 HS256。
Payload
json
{
"iss": "merchant",
"aud": ["gateway"],
"merchantId": "12345678",
"livemode": false,
"jti": "disbursement-550e8400-e29b-41d4-a716-446655440000",
"iat": 1782874330,
"exp": 1782874510
}| 字段 | 必填 | 规则 |
|---|---|---|
| iss | Y | merchant |
| aud | Y | 含 gateway |
| merchantId | Y | 开发者中心商户号 |
| livemode | Y | Boolean;与 body 一致 |
| jti | Y | 有效期内不重复;建议 前缀-UUID |
| iat | Y | Unix 秒 |
| exp | Y | 建议 exp - iat <= 180 |
JWT 不是加密,勿放敏感业务字段。
Signature
text
encodedHeader = base64Url(headerJson)
encodedPayload = base64Url(payloadJson)
signingInput = encodedHeader + "." + encodedPayload
signature = base64Url(HMAC-SHA256(signingInput, apiPrivateKey))
jwt = signingInput + "." + signatureAPI 私钥用原文;Base64URL 无 padding。
http
Authorization: Bearer {jwt}Bearer 与 JWT 之间仅一个空格。X-Request-Id 建议每次唯一,不参与签名与加密。
| 现象 | 可能原因 |
|---|---|
| 签名错误 | API 私钥错误或误 Base64 |
| 已过期 | exp 或时钟偏差 |
| 有效期过长 | exp - iat 超限 |
| 重放 | 重复 jti |
| livemode 不一致 | JWT 与 body 不一致 |
报文加解密
text
RSA-OAEP-256 + A256GCMCompact 结构
text
protectedHeader.encryptedAesKey.iv.cipherText.tag| 段 | 说明 |
|---|---|
| protectedHeader | 加密头 Base64URL,并作 GCM AAD |
| encryptedAesKey | RSA-OAEP-256 加密的 32 字节 AES Key |
| iv | 12 字节随机 IV |
| cipherText | AES-GCM 密文(不含 tag) |
| tag | 16 字节认证标签 |
java
String[] parts = data.split("\\.", -1);protectedHeader 原文固定:
json
{
"typ": "PAYMENT-PAYLOAD",
"alg": "RSA-OAEP-256",
"enc": "A256GCM"
}请求加密
- 明文 JSON
- 随机 AES Key(32)+ IV(12)
- AES-256-GCM,
aad = protectedHeader - 平台请求公钥 RSA-OAEP-256(OAEP/MGF1 均为 SHA-256)加密 AES Key
- 五段拼接为
data
json
{
"livemode": false,
"data": "{compactPayload}"
}响应解密
- 外层
code = 0 - 拆分五段并校验 header
- 商户响应私钥解 AES Key
- GCM 解密得业务 JSON
Webhook 的 data 加密方向与响应相同。每次加密须新 AES Key / IV;任一段篡改应解密失败。
代付概念与状态
首期支付方式:PAY_PAL。路径前缀:/openapi/v1/disbursement。
下文 JSON 均为加密前明文;HTTP 外层始终 { livemode, data }。
text
维护收款人 → 算费 → 下单(outTradeNo 幂等;实扣后送渠)
→ 查单 / Webhook
├─ SUCCESS:终态,不再动账
└─ FAIL:本金+手续费退回可用| 状态 | 含义 | 资金 |
|---|---|---|
PROCESSING | 处理中 | 已实扣 |
SUCCESS | 成功 | 不动账 |
FAIL | 失败 | 已退回 |
本期不提供取消、补发、批量。
| 能力 | Path |
|---|---|
| 创建/更新/查询/分页/启停收款人 | /payee/* |
| 算费 / 下单 / 查单 / 分页 | /order/* |
| 余额 | /wallet/balance/query |
收款人
硬规则:email ≡ paypalEmail(忽略大小写)。仅启用收款人可下单。
创建 POST /payee/create
json
{
"paymentMethod": "PAY_PAL",
"displayName": "John Doe",
"paypalEmail": "john@example.com",
"email": "john@example.com",
"firstname": "John",
"lastname": "Doe",
"phone": "+1xxxxxxxxxx",
"country": "US",
"state": "CA",
"city": "Los Angeles",
"address": "1 Main St",
"zipcode": "90001",
"currency": "USD",
"remark": "optional"
}| 字段 | 必填 | 说明 |
|---|---|---|
| paymentMethod | Y | 固定 PAY_PAL |
| paypalEmail / email | Y | 须一致 |
| firstname / lastname | Y | 姓名 |
| phone / 地址字段 | 建议 | 出站材料 |
| displayName / currency / remark | N | 可选 |
响应示例:{ "payeeId": 10001, "status": 1, ... }。
其它
- 更新
POST /payee/update:传payeeId+ 变更字段 - 查询
POST /payee/get:{ "payeeId": 10001 } - 分页
POST /payee/page:pageNo/pageSize/ 筛选 - 启停
POST /payee/update-status:status1 启用 / 0 禁用
算费 / 下单 / 查单
算费 POST /order/calc
json
{
"currency": "USD",
"transferAmount": 100.00
}json
{
"currency": "USD",
"transferAmount": 100.00,
"fixedFeeAmount": 0.30,
"percentFeeAmount": 1.20,
"feeAmount": 1.50,
"amount": 101.50
}amount = 本金 + 手续费;下单须回传与算费一致的 amount。
下单 POST /order/create
json
{
"outTradeNo": "MCH202604010001",
"payeeId": 10001,
"currency": "USD",
"transferAmount": 100.00,
"amount": 101.50,
"website": "https://merchant.example",
"clientIp": "203.0.113.10",
"remark": "optional"
}| 字段 | 必填 | 说明 |
|---|---|---|
| outTradeNo | Y | 商户单号;幂等键 |
| payeeId | Y | 启用收款人 |
| transferAmount / amount | Y | 本金 / 扣款总额 |
| website | Y | 须 https:// |
| clientIp | Y | 可能受美国公网 IP 策略约束 |
无需 OTP。同 outTradeNo:要素一致返回原单,不一致 409。受理后实扣并送渠;同步多为 PROCESSING。
查单 POST /order/get
orderNo 或 outTradeNo 二选一。不返回渠道品牌与内部账户信息。
分页 POST /order/page
按状态、时间筛选;仅本商户。
资金口径
| 事件 | 资金 |
|---|---|
| 下单受理 | 扣本金+手续费 |
| SUCCESS | 不动账 |
| FAIL | 退回本金+手续费 |
| 重复终态 | 幂等 |
余额查询
POST /wallet/balance/query
json
{
"currency": "USD"
}会员取自 JWT,勿混用机构明文接口。
json
{
"currency": "USD",
"available": 10000.00,
"frozen": 0.00
}代付 Webhook
| 主单变化 | event_type |
|---|---|
→ SUCCESS | disbursement.order.succeeded |
→ FAIL | disbursement.order.failed |
PROCESSING 不推。Body:{ livemode, data },data 用商户响应公钥加密。
解密后示例:
json
{
"eventId": "evt_123",
"eventType": "disbursement.order.succeeded",
"occurredAt": "2026-04-01T08:05:00Z",
"orderNo": "D2026040100001",
"outTradeNo": "MCH202604010001",
"status": "SUCCESS",
"currency": "USD",
"transferAmount": 100.00,
"feeAmount": 1.50,
"amount": 101.50,
"failReason": null
}商户应尽快返回 2xx,按 eventId/orderNo 幂等。重试示例:1m → 5m → 15m → 1h → 6h → 24h。开发者中心可发测试事件。
错误码
json
{
"code": 0,
"msg": "",
"livemode": false,
"data": "{compactPayload}"
}| code | 含义 |
|---|---|
0 | 成功 |
401 | JWT 问题 |
403 | 未开通 / IP / 停用 |
404 | 不存在(含越权统一表现) |
409 | 幂等冲突或状态不允许 |
422 | 参数校验 / livemode / 解密失败 |
429 | 限流 |
500 | 系统错误 |
| 问题 | 排查 |
|---|---|
| 签名错误 | API 私钥原文;勿误 Base64 |
| jti 重放 | 每次新 UUID |
| livemode | JWT 与 body 同为 Boolean 且同值 |
| data 解密失败 | 公钥/私钥是否用对方向 |
| Java 拆分失败 | split("\\.", -1) |
| 下单 422 网站 | 须 https:// |
幂等与限流
- 业务幂等:
outTradeNo;超时重试换新 JWT,保持同一outTradeNo - 防重放:JWT
jti,不能替代业务幂等 - 限流:按
merchantId,遇429退避 - IP 白名单:开发者中心配置;未命中
403
变更日志
0.1.0(文档初稿)
- 单页文档站 + 左侧栏目
- 覆盖环境、快速开始、JWT、compact 加解密、代付 API、Webhook、错误码与幂等
- 协议:Bearer JWT(HS256) + RSA-OAEP-256 / AES-256-GCM