法币下单 · YHT

XPay 商户接口 · 2026-11-09 更新 · 金额单位：人民币元

由商户服务器调用 XPay 创建人民币支付订单。浏览器只接收支付链接、二维码或客户端支付参数，APPSECRET 留在商户服务器。

POST https://www.xpay.plus/v1/api/open/order/submit
Content-Type: application/json; charset=utf-8
需完成商户进件审核、开通下单权限，并获得对应渠道和支付方式授权。

先看 H5 / Web 接入指南 · 查单 · 回调

请求字段

字段类型必填说明
appIdstring是XPay 商户 AppID；不是微信 AppID。
signaturestring是使用 XPay APPSECRET 生成的大写 MD5。APPSECRET 不随请求发送。
merchantOrderNostring是商户唯一订单号。重复下单返回 1007；超时先查原单，避免重复支付。
payType / channelstring是两项均填写 YHT。
payMethodstring是使用下表 XPay 编码，且已为当前商户开通和授权。
amountstring / number是人民币元，大于 0，建议使用两位小数字符串，例如 0.01。按实际提交的值签名；payMoney 仅保留旧版兼容。
notifyUrlstring是商户业务服务器接收通知的 HTTPS 地址，必须能从公网访问。详见回调文档。
redirectUrlstring否付款后业务返回页；不是到账证明，不用于替代回调或查单。
productName / productDescstring否商品名称与描述；省略名称默认为 Payment，空描述使用商品名称。
attachstring否商户自定义标记；当前通知不回传 attach，请按订单号关联自己的业务数据。
openidstring条件必填wxPub、wxLite 必填，须来自本次付款所用公众号或小程序；二者不能混用。其他方式不需要。
subAppIdstring小程序接入应传wxLite 对应微信小程序 AppID，格式 wx 加 16 位小写十六进制字符。仅 wxLite 可传；与 openid、运行小程序保持一致。
clientIpstring否 / H5 应传付款用户真实 IP；未传时使用请求来源 IP。服务端转发时不能把服务器 IP 当作付款用户 IP。

支付方式与开通条件

下表区分已验证场景和待开通场景。接口识别某编码，不表示所有商户均可使用；请以商户授权和平台开通结果为准。

payMethod方式使用场景接入条件
aliQr支付宝扫码电脑网页展示二维码，用户用支付宝扫码已完成付款、查单和通知验证；仍需账号授权
wxLite微信小程序在匹配的小程序内调起支付已完成付款、查单和通知验证；需 openid、subAppId
wxPub微信公众号网页微信内网页调用支付需匹配公众号 openid；公众号配置及实付待验收
wxH5XPay 微信收银台（历史编码）平台收银台获取公众号用户身份后支付当前走公众号授权；不是标准 H5，公众号链路待验收
wxMobileH5微信标准 H5微信外的手机浏览器当前渠道未开通；开通后需真实手机浏览器验收
aliPay支付宝手机网站手机浏览器当前渠道未开通；不等同于支付宝扫码
aliPc支付宝电脑网站电脑网页跳转支付宝收银台当前渠道未开通；可另选已开通的 aliQr 扫码场景
wxNative微信扫码电脑网页展示微信付款码当前渠道未开通
wxApp / aliApp原生 APP在对应 APP 中使用支付 SDK当前渠道未开通；不能作为 H5 链接使用

支付宝网页扫码示例

示例身份、订单及链接均为占位值。先计算 signature，再发送完整 JSON。

POST JSON
{
  "appId": "YOUR_XPAY_APP_ID",
  "merchantOrderNo": "WEB-20261109-0001",
  "payType": "YHT",
  "channel": "YHT",
  "payMethod": "aliQr",
  "amount": "0.01",
  "productName": "测试商品",
  "productDesc": "网页订单",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "redirectUrl": "https://merchant.example.com/pay/result",
  "attach": "business-order-0001",
  "signature": "REPLACE_WITH_COMPUTED_SIGNATURE"
}

小程序请求示例

wxLite JSON
{
  "appId": "YOUR_XPAY_APP_ID",
  "merchantOrderNo": "MINI-20261109-0001",
  "payType": "YHT",
  "channel": "YHT",
  "payMethod": "wxLite",
  "amount": "0.01",
  "productName": "测试商品",
  "productDesc": "网页订单",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "redirectUrl": "https://merchant.example.com/pay/result",
  "attach": "business-order-0001",
  "openid": "OPENID_FROM_THIS_MINI_PROGRAM",
  "subAppId": "wx0123456789abcdef",
  "signature": "REPLACE_WITH_COMPUTED_SIGNATURE"
}

签名规则

参数名区分大小写；所有实际提交的非空字段（signature 除外）均参与签名，包括 openid、subAppId。按字段名升序拼接，末尾追加 &appsecret=商户密钥，取大写 MD5。以下 PHP 实现与当前服务端一致。

商户服务器 PHP
function xpaySignature(array $params, string $appsecret): string
{
    foreach ($params as $key => $value) {
        if ($key === 'signature' || $value == '') unset($params[$key]);
    }
    ksort($params);
    return strtoupper(md5(urldecode(http_build_query($params)) . '&appsecret=' . $appsecret));
}
// 对最终发送的原始参数签名；不要先转换金额或修改字段大小写。
$params['signature'] = xpaySignature($params, $appsecret);

成功响应

支付宝扫码返回示例
{
  "code": 0,
  "message": "ok",
  "data": {
    "platformOrderNo": "YHT20261109000000DEMO01",
    "merchantOrderNo": "WEB-20261109-0001",
    "amount": 0.01,
    "payUrl": "",
    "qrCode": "https://qr.alipay.com/EXAMPLE_ONLY",
    "payDataType": "codeurl",
    "payData": "https://qr.alipay.com/EXAMPLE_ONLY"
  }
}

code=0 表示下单受理，不表示已付款。业务响应固定为 code、message、data；不提供上游原始请求、响应或调试开关。同步响应当前没有响应签名。

data 字段说明
platformOrderNoXPay 平台订单号
merchantOrderNo原商户订单号
amount订单人民币金额，单位元
payDataType支付内容类型，按类型使用，不能只判断 payUrl 是否非空
payData支付内容字符串；wxapp 通常为 JSON 字符串，先 JSON.parse，再交给匹配的微信环境
payUrl链接、表单或客户端参数的兼容字段，不保证一定是可打开的 URL
qrCode扫码内容或二维码图片地址；须结合 payDataType 判断

错误处理

code含义
1001参数、金额、开通条件或支付通道受理失败，查看业务提示
1002签名不匹配
1004商户下单权限未开启
1005商户不存在或未启用
1007商户订单号已存在；查询原订单
1008渠道或支付方式未授权
2001系统处理异常；先查原订单，再决定是否重试

进件审核未完成也会阻止下单，以接口业务提示为准。请求超时、响应不明或出现重复订单提示时，请先查单，不能通过不断换单号判断是否成功。