Skip to content

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 + 加密协议,两套不可混用。

前置条件:

  1. 商户已完成入驻 / KYC(以运营要求为准)
  2. 运营已开通产品码 DISBURSEMENT
  3. 开发者中心已创建凭证并配置响应密钥(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 URL

2. 业务明文 ​

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 ​

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
}
字段必填规则
issYmerchant
audY含 gateway
merchantIdY开发者中心商户号
livemodeYBoolean;与 body 一致
jtiY有效期内不重复;建议 前缀-UUID
iatYUnix 秒
expY建议 exp - iat <= 180

JWT 不是加密,勿放敏感业务字段。

Signature ​

text
encodedHeader  = base64Url(headerJson)
encodedPayload = base64Url(payloadJson)
signingInput   = encodedHeader + "." + encodedPayload
signature      = base64Url(HMAC-SHA256(signingInput, apiPrivateKey))
jwt            = signingInput + "." + signature

API 私钥用原文;Base64URL 无 padding。

http
Authorization: Bearer {jwt}

Bearer 与 JWT 之间仅一个空格。X-Request-Id 建议每次唯一,不参与签名与加密。

现象可能原因
签名错误API 私钥错误或误 Base64
已过期exp 或时钟偏差
有效期过长exp - iat 超限
重放重复 jti
livemode 不一致JWT 与 body 不一致

报文加解密 ​

text
RSA-OAEP-256 + A256GCM

Compact 结构 ​

text
protectedHeader.encryptedAesKey.iv.cipherText.tag
段说明
protectedHeader加密头 Base64URL,并作 GCM AAD
encryptedAesKeyRSA-OAEP-256 加密的 32 字节 AES Key
iv12 字节随机 IV
cipherTextAES-GCM 密文(不含 tag)
tag16 字节认证标签
java
String[] parts = data.split("\\.", -1);

protectedHeader 原文固定:

json
{
  "typ": "PAYMENT-PAYLOAD",
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM"
}

请求加密 ​

  1. 明文 JSON
  2. 随机 AES Key(32)+ IV(12)
  3. AES-256-GCM,aad = protectedHeader
  4. 平台请求公钥 RSA-OAEP-256(OAEP/MGF1 均为 SHA-256)加密 AES Key
  5. 五段拼接为 data
json
{
  "livemode": false,
  "data": "{compactPayload}"
}

响应解密 ​

  1. 外层 code = 0
  2. 拆分五段并校验 header
  3. 商户响应私钥解 AES Key
  4. 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"
}
字段必填说明
paymentMethodY固定 PAY_PAL
paypalEmail / emailY须一致
firstname / lastnameY姓名
phone / 地址字段建议出站材料
displayName / currency / remarkN可选

响应示例:{ "payeeId": 10001, "status": 1, ... }。

其它 ​

  • 更新 POST /payee/update:传 payeeId + 变更字段
  • 查询 POST /payee/get:{ "payeeId": 10001 }
  • 分页 POST /payee/page:pageNo / pageSize / 筛选
  • 启停 POST /payee/update-status:status 1 启用 / 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"
}
字段必填说明
outTradeNoY商户单号;幂等键
payeeIdY启用收款人
transferAmount / amountY本金 / 扣款总额
websiteY须 https://
clientIpY可能受美国公网 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
→ SUCCESSdisbursement.order.succeeded
→ FAILdisbursement.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成功
401JWT 问题
403未开通 / IP / 停用
404不存在(含越权统一表现)
409幂等冲突或状态不允许
422参数校验 / livemode / 解密失败
429限流
500系统错误
问题排查
签名错误API 私钥原文;勿误 Base64
jti 重放每次新 UUID
livemodeJWT 与 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

Last updated:

WantoPay Merchant OpenAPI