API 文档 · order/submit

订单创建接口

创建支付订单并返回支付链接、二维码地址及订单状态。

请求地址
/v1/api/open/order/submit

USDT 数量口径 / USDT amount contract

仅适用于 payType=USDT 或未传 payType 的统一 API 请求。使用 pay_usdt 提交 USDT 数量，例如 "10.00"；必须大于 0，最多两位小数，且满足平台单笔限额。chainType=1 为 TRC20。下单不依赖 CNY 或其他法币汇率；需要法币展示时，由接入平台自行换算。

兼容旧接入：未传 pay_usdt 时才读取 payMoney，仍按 USDT 数量解释；同时传入时以 pay_usdt 为准，pay_usdt 无效则拒绝请求，不回退。pay_money 不作为下单金额。签名仍覆盖实际提交的全部非空字段，示例 signature 必须自行计算。

下单与查单响应的 pay_usdt 是最终应付数量；同地址金额冲突可能使金额增加 0.01 USDT，请按收银台最终金额付款。旧人民币折算字段保留兼容，新订单为 0.00（未折算），不得据此入账。支付宝、微信及 YHT 的 amount/payMoney 规则不变。

Use a positive USDT decimal in pay_usdt (up to 2 decimal places). No FX rate is required. payMoney is a legacy USDT alias only when pay_usdt is absent; pay_money is not an amount input. Sign original fields. The returned pay_usdt is the final payable amount and may include an address-collision adjustment. Convert fiat amounts in your own platform; legacy unconverted fiat fields are 0.00. Fiat channels are unchanged.

请求参数

curl -X POST 'https://xpay.plus/v1/api/open/order/submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId":"Zu78qwe1",
    "merchantOrderNo":"Order202409291231",
    "chainType":"1",
    "pay_usdt":"10.00",
    "productName":"USDT Deposit",
    "notifyUrl":"https://callback.example.com/order",
    "redirectUrl":"https://merchant.example.com/success",
    "attach":"user001",
    "signature":"6F3B90783FABE56DBB771D03E0EAADD0"
  }'

请求示例

请求参数

{
  "appId": "Zu78qwe1",
  "merchantOrderNo": "Order202409291231",
  "chainType": "1",
  "pay_usdt": "10.00",
  "productName": "USDT Deposit",
  "notifyUrl": "https://callback.example.com/order",
  "redirectUrl": "https://merchant.example.com/success",
  "attach": "user001",
  "signature": "6F3B90783FABE56DBB771D03E0EAADD0"
}

返回示例

返回结果

{
  "code": 0,
  "message": "success",
  "data": {
    "orderNo": "OR202601010001",
    "merchantOrderNo": "Order202409291231",
    "payUrl": "https://xpay.plus/payment/index/order/id/Order202409291231",
    "pay_usdt": "10.00",
    "status": "0"
  }
}

支付宝直连扩展

设置 payType=ALIPAY，使用商户已审核并启用的支付宝应用凭据创建 PC 或手机网站支付订单。

扩展字段（payType=ALIPAY）
请求地址仍为 POST /v1/api/open/order/submit。商户请求中的 appId 和签名密钥分别是 XPay AppID、XPay AppSecret，不是支付宝应用 AppID 或应用私钥。

接入前提

配置	要求
XPay 接口秘钥	从商户后台“商户设置 → 接口秘钥”获取 AppID / AppSecret，用于请求签名
支付宝应用凭据	在商户后台“应用凭据”提交支付宝 AppID、应用私钥、支付宝公钥，并完成审核和启用

支付宝完整请求参数

字段名	类型	必填	说明
appId	string	是	XPay 商户 AppID，不是支付宝应用 AppID
merchantOrderNo	string	是	当前商户的支付宝订单幂等键。同一订单号重试时，`amount` 和 `payMethod` 必须与首次请求一致；首次显式传入 `credentialId` 时，重试也必须传入同一值。
payType	string	是	固定值 `ALIPAY`
credentialId	integer	否	仅可填写由本次 `appId + signature` 认证出的当前商户的凭据记录 ID。凭据必须已审核、已启用且未删除；跨商户或不可用凭据返回 `1009`。未传时自动选择当前商户 ID 最大的可用凭据。
payMethod	string	是	`web`：PC 网站支付；`wap`：手机网站支付
amount	string	是	人民币金额，必须大于 0，最多两位小数；`payMoney` 可作为兼容别名
productName	string	否	商品名称，默认 Payment
productDesc	string	否	商品描述
notifyUrl	string	是	支付成功后 XPay 通知商户后端的可访问 URL
redirectUrl	string	否	用户支付完成后的商户页面；`returnUrl` 可作为兼容别名
attach	string	否	商户自定义数据，支付成功通知时原样返回
signature	string	是	使用 XPay AppSecret 对本次请求全部非空字段生成的大写 MD5 签名

请求参数（支付宝 WAP）

curl -X POST 'https://xpay.plus/v1/api/open/order/submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId":"Zu78qwe1",
    "merchantOrderNo":"ALI202608070001",
    "payType":"ALIPAY",
    "credentialId":12,
    "payMethod":"wap",
    "amount":"20.00",
    "productName":"订单支付",
    "productDesc":"支付宝订单",
    "notifyUrl":"https://merchant.example.com/payment/alipay/notify",
    "redirectUrl":"https://merchant.example.com/payment/result",
    "attach":"user-10001",
    "signature":"..."
  }'

返回示例（支付宝直连）

返回结果

{
  "code": 0,
  "message": "ok",
  "data": {
    "platformOrderNo": "ALI20260807110917E2BF35",
    "merchantOrderNo": "ALI202608070001",
    "amount": "20.00",
    "credentialId": 12,
    "payUrl": "https://xpay.plus/v1/payment/alipay/redirect/ALI...?token=...",
    "recovered": false
  }
}

商户后端应把 payUrl 返回给自己的前端，由用户浏览器打开。web 会调用支付宝 PC 网站支付，wap 会调用支付宝手机网站支付。支付链接有效期为 30 分钟。

成功响应中的 credentialId 是订单实际绑定的凭据 ID。首次未传时平台自动选择最新可用凭据；相同订单号重试继续沿用原订单凭据。

签名与常见错误

除 signature 外，所有实际提交的非空字段都参与 XPay MD5 签名，包括 payType、显式传入的 credentialId、payMethod、amount、redirectUrl 和 attach。字段名区分大小写；未传 credentialId 时不可将它补入签名原文。同一订单号重试时，amount、payMethod 和首次显式传入的 credentialId 均不得变化。

错误	说明
1002 / signature error	检查 XPay AppSecret、字段大小写和排序
1005 / merchant not found	`appId` 填写了错误值或误填支付宝应用 AppID
1009 / Alipay credential not found, not approved, or not enabled	`credentialId` 不属于由 `appId + signature` 认证出的当前商户，或凭据未审核、未启用、已删除；未指定时表示当前商户没有可自动选择的凭据

微信直连扩展

设置 payType=WECHAT，使用商户已审核并启用的微信支付 API v3 凭据创建 H5 或 PC Native 扫码订单。

字段名	必填	说明
appId	是	XPay 商户 AppID，不是微信 AppID
merchantOrderNo	是	当前商户的微信订单幂等键；同一订单号重试时 `amount`、`payMethod` 不得变化，首次显式传入 `credentialId` 时也必须保持相同值
payType	是	固定值 `WECHAT`
credentialId	否	仅可填写由本次 `appId + signature` 认证出的当前商户的微信凭据记录 ID。凭据必须已审核、已启用且未删除；跨商户或不可用凭据返回 `1009`。未传时自动选择当前商户 ID 最大的可用凭据
payMethod	是	`native`：PC 二维码；`h5`：手机浏览器支付
amount	是	人民币金额，最多两位小数；`payMoney` 为兼容别名
notifyUrl	是	支付成功后 XPay 通知商户的可访问 URL
redirectUrl	否	支付完成后返回商户页面的地址

请求参数（微信 Native）

curl -X POST 'https://xpay.plus/v1/api/open/order/submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId":"Zu78qwe1",
    "merchantOrderNo":"WX202608140001",
    "payType":"WECHAT",
    "credentialId":21,
    "payMethod":"native",
    "amount":"0.01",
    "productName":"订单支付",
    "notifyUrl":"https://merchant.example.com/payment/wechat/notify",
    "redirectUrl":"https://merchant.example.com/payment/result",
    "signature":"..."
  }'

返回示例（微信直连）

返回结果

{
  "code": 0,
  "message": "ok",
  "data": {
    "platformOrderNo": "WXP20260814120000ABCDEF",
    "merchantOrderNo": "WX202608140001",
    "amount": "0.01",
    "credentialId": 21,
    "payUrl": "https://xpay.plus/v1/payment/wechat/native/WXP...",
    "recovered": false
  }
}

Native 返回的 payUrl 是 XPay 二维码页；H5 返回微信支付地址。成功响应中的 credentialId 是订单实际绑定的凭据 ID。显式传入时该字段必须参与签名；未传时不要在签名原文中补入。首次未传时自动选择最新可用凭据，相同订单号重试继续使用原订单凭据，并且 amount、payMethod 不得变化。

当前仅支持 native 和 h5，不包含 JSAPI、小程序和 APP 支付。

微信凭据常见错误

错误	说明
1001 / credentialId invalid	显式传入的 credentialId 不是正整数
1009 / WeChat Pay credential not found, not approved, or not enabled	`credentialId` 不属于由 `appId + signature` 认证出的当前商户，或凭据未审核、未启用、已删除；未指定时表示当前商户没有可自动选择的凭据

法币扩展（云汇腾）

通过 payType=YHT 触发云汇腾法币通道，支持微信支付、支付宝、银联快捷等多种支付方式。

扩展字段（payType=YHT）
在原有参数基础上，增加以下字段即可切换至云汇腾法币通道：

请求参数（法币）

curl -X POST 'https://xpay.plus/v1/api/open/order/submit' \
  -H 'Content-Type: application/json' \
  -d '{
    "appId":"Zu78qwe1",
    "merchantOrderNo":"YHT20260724001",
    "payType":"YHT",
    "channel":"YHT",
    "payMethod":"aliPay",
    "payMoney":"10.00",
    "productName":"法币订单",
    "notifyUrl":"https://callback.example.com/yht",
    "redirectUrl":"https://merchant.example.com/yht/success",
    "attach":"user001",
    "signature":"..."
  }'

扩展字段说明

字段名	类型	必填	说明
payType	string	是	固定值 `YHT`，触发云汇腾法币通道
channel	string	是	渠道编码，固定值 `YHT`
payMethod	string	是	支付方式：wxH5 / wxPub / wxLite / aliPay / unionPay / bankCard / bankFast
payMoney	string	是	订单金额（CNY），单位：元，保留两位小数

返回示例（法币）

返回结果

{
  "code": 0,
  "message": "success",
  "data": {
    "orderNo": "YHT2026072400001",
    "merchantOrderNo": "YHT20260724001",
    "payUrl": "https://cashier.yunhuiteng.com/pay/YHT2026072400001",
    "qrCodeUrl": "https://qr.yunhuiteng.com/YHT2026072400001",
    "payMethod": "aliPay",
    "status": "0"
  }
}