AllOnePay API 对接文档

Positioning

平台定位

AllOnePay 是支付聚合与接口中继层：商户通过统一 API 提交订单，平台完成商户认证、签名校验、国家/币种/支付方式匹配、交易请求转发、结果通知和查询。资金清结算由商户开通的支付渠道及其结算规则完成，AllOnePay 不沉淀商户或用户资金。

代收聚合

统一入口支持扫码、H5、App、卡、银行转账、代扣等不同支付方式，实际可用值以商户开通配置为准。

代付转发

统一处理银行卡、电子钱包或本地化代付场景，提交后可能自动转发上游，也可能进入人工审核状态。

收银台模式

商户先生成短期收银台链接，由用户在托管收银台选择或确认支付方式，适合低成本、多国家快速接入。

对外文档中的 channelCode、payMethodCode、payTypeCode 均为平台分配或开通后的业务编码。若商户未明确指定渠道，平台会按已开通规则进行匹配。

Quickstart

5 分钟接入路径

1
获取商户凭据
向平台获取 appId、签名密钥、API 白名单和已开通的国家、币种、支付方式编码。
2
生成请求信封
每次请求带上 timestamp、nonce、apiVersion=v1.0 和 sign。时间戳使用 UTC Unix 秒。
3
选择接入模式
托管收银台使用 GenerateCashierToken；自建支付页直接调用 UnifiedPay；提现或商户出款调用 UnifiedPayout。
4
验签并处理结果
同步响应、异步通知都包含 sign。商户必须重新计算签名，验签通过后再更新订单。
5
用查询接口兜底
前端跳转仅用于展示，不可作为成功依据。最终结果以异步通知或 QueryPayOrder / QueryPayoutOrder 为准。

Protocol

协议与安全信封

请求格式

所有开放接口均为 POST，请求体为 application/json; charset=utf-8。示例 Base URL 使用 https://api.your-domain.com，正式域名以平台交付为准。

HTTP POST JSON Body UTC Unix seconds Signed response

金额与时间

所有金额字段均为整数分，例如 10000 表示 100.00。响应时间字段为 UTC 时间。请求 timestamp 允许 5 分钟内时钟偏差。

amount = cents ISO 4217 currency ISO 3166 country

公共请求字段

以下字段适用于代收、代付、查询、余额和收银台令牌等业务接口；签名辅助接口见独立章节。

字段	类型	必填	说明
`appId`	string	是	平台分配的商户应用标识。
`timestamp`	string	是	UTC Unix 秒，例如 `1773542400`。超过 5 分钟偏差会被拒绝。
`nonce`	string	是	随机串，最长 64 字符；同一 `appId` 下 10 分钟内不可重复。
`apiVersion`	string	是	当前固定为 `v1.0`。
`sign`	string	是	MD5 签名。推荐放在 JSON Body，也兼容 HTTP Header `sign` 或查询参数 `?sign=xxx`。
`languageCode`	string	否	响应文案语言，例如 `zh-CN`、`en`、`pt-BR`。未传时按商户默认国家/币种推断。

公共响应字段

以下字段适用于标准业务响应；签名辅助接口返回调试结果，不使用该响应结构。

字段	类型	说明
`appId`	string	商户应用标识，参与响应签名。
`timestamp`	string	平台响应签名时间戳，UTC Unix 秒。
`nonce`	string	平台响应随机串。
`apiVersion`	string	响应协议版本。
`sign`	string	响应签名。商户应按同样规则排除 `sign` 后验签。
`rspCode`	string	业务响应码，成功为 `PAY_000`。
`rspMsg`	string	响应说明，会根据 `languageCode` 或商户默认语言返回。

Security

MD5 签名规则

签名算法与当前开放接口实现一致：排除 sign 字段，递归扁平化对象，字段名统一小写，按 ASCII 升序排序，值进行 URL 编码，最后拼接 &key=商户签名密钥 后计算 MD5。

1
递归展开参数
普通字段直接参与签名；对象字段使用点号，例如 payer.openid；数组使用下标，例如 items[0].id。
2
过滤字段
忽略 sign 和值为 null 的字段。非空字符串、数字、布尔值、时间都参与签名。
3
排序与编码
所有键名转为小写后按 ASCII 排序，值使用 URL 编码，再拼接为 k=v&k2=v2。
4
拼接密钥并 MD5
待签名串末尾追加 &key=YOUR_SIGN_KEY，计算 MD5。请求、响应、异步通知均使用同一规则。

签名串示例：复杂对象扁平化

amount=10000&apiversion=v1.0&appid=your_app_id&currency=USD&merchantorderno=PAY202605010001&nonce=8d9f0a7c1234&paymethodcode=h5&payer.email=buyer%40example.com&payer.openid=o9xx123&subject=Premium%20Plan&timestamp=1777593600&key=YOUR_SIGN_KEY

文档展示签名规则用于联调说明。生产环境不要在前端、日志、截图或工单中暴露签名密钥。

Endpoint Matrix

接口总览

POST

生成收银台令牌

/api/PayRequest/GenerateCashierToken

生成托管收银台链接、二维码和预订单平台单号。

查看参数

POST

统一代收下单

/api/PayRequest/UnifiedPay

商户自建支付页直接提交代收订单，返回二维码、跳转链接或银行转账指引。

查看参数

POST

查询代收订单

/api/PayRequest/QueryPayOrder

查询代收订单状态、金额、渠道单号和状态说明。

查看参数

POST

统一代付下单

/api/PayRequest/UnifiedPayout

提交出款申请，返回平台代付单号、审核状态和上游处理结果。

查看参数

POST

查询代付订单

/api/PayRequest/QueryPayoutOrder

查询出款状态、手续费、实际到账金额和失败原因。

查看参数

POST

查询商户余额

/api/PayRequest/QueryMerchantBalance

按币种返回可用、冻结、待结算、可提现和分润余额。

查看参数

POST

签名辅助

/api/PayRequest/GenerateSignaturePublic

联调期辅助生成签名、签名串和排序后的签名参数。

查看参数

Hosted Cashier

生成收银台令牌

POST /api/PayRequest/GenerateCashierToken

适用于商户不想自建支付方式选择页的场景。平台生成短码收银台链接与二维码，并在令牌创建阶段返回 platformOrderNo，商户可立即用 QueryPayOrder 查询到收银台待确认状态。

请求参数

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户订单号，与 `appId` 联合幂等。
`currency`	string	是	ISO 4217 币种，例如 `USD`、`CNY`。
`amount`	long	是	订单金额，单位分，必须为正整数。
`subject`	string	是	订单标题，最长 200 字符。
`notifyUrl`	string	否	异步通知地址。未传时使用商户默认通知地址。
`returnUrl`	string	否	用户支付完成后的前端跳转地址。仅用于展示，不作为支付成功依据。
`payMethodCode`	string	否	预指定支付方式编码，例如 `qr`、`h5`、`bank_transfer`。
`country`	string	否	ISO 3166-1 alpha-2 国家代码，例如 `US`、`BR`、`IN`。
`payTypeCode`	string	否	平台开通的本地化支付类型编码。
`expiresIn`	int	否	令牌有效期秒数，默认 `1800`。

响应参数

字段	类型	说明
`platformOrderNo`	string	平台订单号，预订单创建后即分配。
`merchantOrderNo`	string	商户订单号回显。
`shortCode`	string	收银台短码。
`cashierUrl`	string	收银台完整访问地址。
`qrCodeBase64`	string	二维码图片，格式为 `data:image/png;base64,...`。
`expiresAt`	datetime	令牌过期时间，UTC。

请求示例

{
  "appId": "your_app_id",
  "merchantOrderNo": "PAY202605010001",
  "amount": 10000,
  "currency": "USD",
  "subject": "Premium Plan",
  "payMethodCode": "h5",
  "country": "US",
  "notifyUrl": "https://merchant.example.com/payment/notify",
  "returnUrl": "https://merchant.example.com/payment/result",
  "expiresIn": 1800,
  "timestamp": "1777593600",
  "nonce": "8d9f0a7c1234",
  "apiVersion": "v1.0",
  "languageCode": "en",
  "sign": "<computed_sign>"
}

Acquire

统一代收下单

POST /api/PayRequest/UnifiedPay

适用于商户自建支付页或服务端直接下单。响应根据支付方式返回 acquire 或 instruction，商户应展示二维码、跳转链接、客户端唤起参数或银行转账指引。

请求参数

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户订单号，与 `appId` 联合幂等。
`amount`	long	是	订单金额，单位分，必须为正整数。
`currency`	string	是	ISO 4217 币种。
`payMethodCode`	string	是	支付方式编码，例如 `qr`、`jsapi`、`h5`、`app`、`card`、`bank_transfer`、`debit_sign`、`debit_charge`。
`channelCode`	string	否	渠道编码，由平台配置。未传时按商户开通规则匹配。
`subject`	string	否	订单标题或摘要。
`notifyUrl`	string	否	异步通知地址。
`returnUrl`	string	否	前端跳转地址，仅用于展示。
`country`	string	否	ISO 3166-1 alpha-2 国家代码。
`payTypeCode`	string	否	平台开通的本地化支付类型编码。
`payer`	object	否	付款人信息，参与签名时扁平化为 `payer.email` 等。
`instrument`	object	否	支付工具信息，仅传非敏感或令牌化字段。
`ext`	object	否	扩展键值对，值为字符串。

子对象字段

payer

email、phone、openId、buyerId

instrument

cardToken、bankCode、mandateId、holderName、brand、expMonth、expYear、last4、bin6、masked

ext

业务扩展键值对，例如 scene、terminal、campaign。字段会按 ext.scene 参与签名。

响应参数

字段	类型	说明
`platformOrderNo`	string	平台订单号。
`acquire`	object	收单结果。常见字段：`upstreamTxnId`、`status`、`codeUrl`、`clientParams`、`paymentUrl`、`raw`。
`instruction`	object	银行转账指引。常见字段：`accountName`、`accountNo`、`bankName`、`routingNo`、`refCode`、`expireAt`。

H5 支付请求示例

{
  "appId": "your_app_id",
  "merchantOrderNo": "PAY202605010002",
  "amount": 10000,
  "currency": "USD",
  "payMethodCode": "h5",
  "subject": "Premium Plan",
  "country": "US",
  "payer": {
    "email": "buyer@example.com",
    "phone": "+15550001111"
  },
  "ext": {
    "scene": "checkout"
  },
  "timestamp": "1777593600",
  "nonce": "f61d9c9134ee",
  "apiVersion": "v1.0",
  "languageCode": "en",
  "sign": "<computed_sign>"
}

Acquire Query

查询代收订单

POST /api/PayRequest/QueryPayOrder

按 merchantOrderNo 查询代收订单状态。若生成收银台令牌后用户尚未确认支付，可能返回 CASHIER_PENDING。

请求参数

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户代收订单号。

响应参数

字段	类型	说明
`platformOrderNo`	string	平台订单号。
`merchantOrderNo`	string	商户订单号。
`amount`	long	订单金额，单位分。
`currency`	string	ISO 4217 币种。
`actualAmount`	long/null	实际支付金额，单位分。
`status`	string	`CASHIER_PENDING`、`INIT`、`PROCESSING`、`SUCCESS`、`FAILED`、`CLOSED`、`REFUNDED`、`UNKNOWN`。
`statusText`	string	状态说明，按语言返回。
`payMethodCode`	string	支付方式编码。
`subject`	string	订单标题。
`channelOrderNo`	string	渠道侧订单号。
`createdTime`	datetime/null	创建时间，UTC。
`updatedTime`	datetime/null	更新时间，UTC。

Payout

统一代付下单

POST /api/PayRequest/UnifiedPayout

用于商户出款、提现或代付。接口返回平台代付单号和审核状态；自动审核通过时可能直接返回上游处理状态，人工审核场景则等待后续查询或通知。

请求参数

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户代付订单号，最长 64 字符，与 `appId` 联合幂等。
`applyAmount`	long	是	申请出款金额，单位分，必须为正整数。
`currency`	string	否	ISO 4217 币种，默认 `CNY`。
`channelCode`	string	是	渠道编码，由平台开通配置。
`payeeType`	string	是	收款人类型：`BANK`、`ALIPAY`、`WECHAT`。
`payeeAccount`	string	是	收款账号，例如银行卡号、支付宝账号、微信 OpenID。
`balanceType`	string	否	余额类型：`BALANCE` 或 `PROFIT_BALANCE`。
`payeeName`	string	否	收款人姓名。
`payeeBankCode`	string	否	银行代码，银行卡出款时通常需要。
`payeeBankName`	string	否	银行名称。
`payeeBranchName`	string	否	支行名称。
`payeeProvince`	string	否	省份或州。
`payeeCity`	string	否	城市。
`payeeMobile`	string	否	收款人手机号。
`payeeIdCard`	string	否	本地化合规所需身份标识，按渠道要求传递。
`notifyUrl`	string	否	代付结果异步通知地址。
`remark`	string	否	备注。
`subject`	string	否	出款主题。
`merchantUserId`	string	否	商户侧用户标识。
`countryCode`	string	否	ISO 3166-1 alpha-2 国家代码。
`payTypeCode`	string	否	平台开通的本地化代付类型编码。

响应参数

字段	类型	说明
`platformOrderNo`	string	平台代付订单号。
`auditStatus`	string	审核状态，例如 `AUTO_APPROVED`、`PENDING` 或平台配置返回的审核状态。
`payout`	object/null	自动审核并提交上游时返回。字段：`upstreamTxnId`、`status`、`raw`。
`message`	string/null	处理提示。

银行卡代付请求示例

{
  "appId": "your_app_id",
  "merchantOrderNo": "WD202605010001",
  "balanceType": "BALANCE",
  "applyAmount": 50000,
  "currency": "CNY",
  "channelCode": "your_channel_code",
  "payeeType": "BANK",
  "payeeName": "Zhang San",
  "payeeAccount": "6222021234567890123",
  "payeeBankCode": "ICBC",
  "payeeBankName": "ICBC",
  "notifyUrl": "https://merchant.example.com/payout/notify",
  "countryCode": "CN",
  "payTypeCode": "12001",
  "timestamp": "1777593600",
  "nonce": "7e0c44219c2a",
  "apiVersion": "v1.0",
  "languageCode": "zh-CN",
  "sign": "<computed_sign>"
}

Payout Query

查询代付订单

POST /api/PayRequest/QueryPayoutOrder

按 merchantOrderNo 查询代付状态、手续费、实际金额、失败原因和完成时间。

请求参数

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户代付订单号。

响应参数

字段	类型	说明
`platformOrderNo`	string	平台代付订单号。
`merchantOrderNo`	string	商户订单号。
`applyAmount`	long	申请金额，单位分。
`currency`	string	ISO 4217 币种。
`feeAmount`	long	手续费，单位分。
`actualAmount`	long	实际到账金额，单位分。
`status`	string	`INIT`、`PENDING`、`SUCCESS`、`FAILED`、`CLOSED`、`AUDITING`、`UNKNOWN`。
`statusText`	string	状态说明，按语言返回。
`payMethodCode`	string	代付方式编码。
`payeeType`	string	收款方类型。
`payeeName`	string	收款人姓名。
`payeeAccount`	string	收款账号。
`payeeBankName`	string	收款银行名称。
`createdTime`	datetime/null	创建时间，UTC。
`settledTime`	datetime/null	完成时间，UTC。
`failReason`	string	失败原因。
`remark`	string	备注。

Balance

查询商户余额

POST /api/PayRequest/QueryMerchantBalance

按 appId 返回商户已启用的各币种余额行。该接口只需要公共请求字段。

响应参数

字段	类型	说明
`items`	array	各币种余额明细。
`items[].currency`	string	ISO 4217 币种。
`items[].availableAmount`	long	可用余额，单位分。
`items[].frozenAmount`	long	冻结余额，单位分。
`items[].unsettledAmount`	long	待结算余额，单位分。
`items[].withdrawableAmount`	long	可提现余额，单位分。
`items[].inTransitAmount`	long	在途或处理中余额，单位分。
`items[].profitAvailableAmount`	long	分润可用余额，单位分。
`items[].profitFrozenAmount`	long	分润冻结余额，单位分。

Debug

签名辅助接口

POST /api/PayRequest/GenerateSignaturePublic

联调期可用该接口辅助排查签名结果。生产环境建议商户在自己服务端实现签名，不应把密钥暴露给浏览器或第三方工具。

字段	类型	必填	说明
`parameters`	object	是	待签名请求参数对象。
`key`	string	是	商户签名密钥。仅用于联调辅助。

响应字段	类型	说明
`signature`	string	MD5 签名值。
`signString`	string	脱敏后的签名串，密钥部分会被遮蔽。
`signParams`	object	排序后的签名参数。
`algorithm`	string	当前为 `MD5`。

Webhook

异步通知

订单到达成功或失败终态后，平台会向订单中的 notifyUrl 发起 POST application/json 通知。商户必须先验签，再按 platformOrderNo 或 merchantOrderNo 幂等更新本地订单。

商户返回 HTTP 200 且 Body 为 success，或返回 JSON 且 code 为 10000，平台视为通知成功。请求超时时间为 10 秒。

代收通知字段

字段	说明
`platformOrderNo`	平台代收订单号。
`merchantOrderNo`	商户订单号。
`amount` / `actualAmount`	订单金额 / 实付金额，单位分。
`status`	`SUCCESS` 或 `FAILED`。
`payMethodCode`	支付方式编码。
`channelOrderNo`	渠道订单号。
`paymentUrl`	支付链接，可为空。

代付通知字段

字段	说明
`platformOrderNo`	平台代付订单号。
`merchantOrderNo`	商户订单号。
`applyAmount` / `actualAmount`	申请金额 / 实际金额，单位分。
`feeAmount`	手续费，单位分。
`status`	`SUCCESS` 或 `FAILED`。
`method`	代付方式编码。
`failReason`	失败原因。

代收通知示例

{
  "appId": "your_app_id",
  "rspCode": "PAY_000",
  "rspMsg": "Success",
  "platformOrderNo": "PLT20260501000001",
  "merchantOrderNo": "PAY202605010002",
  "amount": 10000,
  "currency": "USD",
  "actualAmount": 10000,
  "status": "SUCCESS",
  "statusText": "Success",
  "payMethodCode": "h5",
  "subject": "Premium Plan",
  "channelOrderNo": "UP202605010001",
  "createdTime": "2026-05-01T09:00:00Z",
  "updatedTime": "2026-05-01T09:02:00Z",
  "timestamp": "1777593720",
  "nonce": "9aa0ed0195a2",
  "apiVersion": "v1.0",
  "sign": "<platform_sign>"
}

Codes

状态与错误码

业务响应码

代码	含义	处理建议
`PAY_000`	成功	验签后读取业务字段。
`PAY_MCH_001`	商户不存在	检查 `appId` 是否正确或是否已开通。
`PAY_SIGN_001`	签名验证失败	核对字段大小写、空值处理、URL 编码、密钥和排序规则。
`PAY_SIGN_002`	缺少签名	在 JSON Body 的 `sign` 字段中传入签名。
`PAY_SIGN_003`	签名类型不支持	当前开放接口使用 MD5。
`PAY_SIGN_004`	请求时间超过允许偏差	检查服务器时间，确保 `timestamp` 使用 UTC Unix 秒。
`PAY_SIGN_005`	nonce 重复	为每次请求生成新的随机串。
`PAY_SEC_001`	IP 不在白名单	确认服务器出口 IP 已在平台配置。
`PAY_ORDER_001`	订单不存在	检查商户订单号，或确认下单/收银台令牌是否已成功创建。
`PAY_ORDER_005`	订单已存在或重复提交	使用查询接口确认当前订单状态。

状态值

代收查询 status

CASHIER_PENDING、INIT、PROCESSING、SUCCESS、FAILED、CLOSED、REFUNDED、UNKNOWN

代付查询 status

INIT、PENDING、SUCCESS、FAILED、CLOSED、AUDITING、UNKNOWN

查询接口的多状态枚举与异步通知不同。异步通知只表示终态，status 为 SUCCESS 或 FAILED。

多语言响应

当前响应文案资源覆盖 zh-CN、en、es、id、ja、ko、pt-BR、th、vi。商户可通过 languageCode 指定响应语言。

Local Tool

本地签名工具

该工具完全在浏览器本地计算，不请求任何服务器。可用于对照平台签名规则检查请求参数。

请求参数 JSON

签名密钥

计算结果

等待计算...

AllOnePay 开放 API

平台定位

代收聚合

代付转发

收银台模式

5 分钟接入路径

协议与安全信封

请求格式

金额与时间

公共请求字段

公共响应字段

MD5 签名规则

接口总览

生成收银台令牌

统一代收下单

查询代收订单

统一代付下单

查询代付订单

查询商户余额

签名辅助

生成收银台令牌

请求参数

响应参数

统一代收下单

请求参数

子对象字段

payer

instrument

ext

响应参数

查询代收订单

请求参数

响应参数

统一代付下单

请求参数

响应参数

查询代付订单

请求参数

响应参数

查询商户余额

响应参数

签名辅助接口

异步通知

代收通知字段

代付通知字段

状态与错误码

业务响应码

状态值

代收查询 status

代付查询 status

多语言响应

本地签名工具

计算结果