XPay API

支付宝直连

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

接口地址
下单：POST /v1/api/open/order/submit
查单：POST /v1/api/open/order/query

接入前提

凭据	用途	从哪里获取
XPay AppID / AppSecret	商户身份识别、请求签名、平台回调验签	商户后台 → 后台首页 → 商户设置 → 接口秘钥
支付宝应用 AppID / 应用私钥 / 支付宝公钥	XPay 服务端向支付宝发起 RSA2 签名请求	商户后台 → 法币支付 → 应用凭据；提交后需审核并启用

商户请求中的 appId 必须填写 XPay AppID，签名必须使用 XPay AppSecret。不要把支付宝应用 AppID 或支付宝应用私钥传给下单接口。

创建支付宝订单

字段	类型	必填	说明
appId	string	是	XPay 商户 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":"订单支付",
    "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 返回给自己的前端，由用户浏览器打开。不要由商户服务器请求该地址，也不要把支付宝 Form 表单直接拼到商户接口响应中。支付链接有效期为 30 分钟。

返回的 credentialId 是该订单实际绑定的凭据 ID。首次未传 credentialId 时，平台自动选择当前商户最新可用凭据；相同订单号重试仍沿用原订单绑定的凭据。

payMethod	适用终端	支付宝接口
web	PC 浏览器	alipay.trade.page.pay
wap	手机浏览器 / H5	alipay.trade.wap.pay

签名规则

签名规则与 XPay 其他开放接口一致：删除 signature 和空值字段，按字段名 ASCII 升序排序，拼接查询字符串，在末尾追加 &appsecret=XPay商户密钥，计算 MD5 并转为大写。

所有实际提交的非空字段都参与签名，包括 payType、实际传入的 credentialId、payMethod、amount、redirectUrl 和 attach。未传 credentialId 时，不要在签名原文中补入该字段。字段名区分大小写。

同一订单号重试时，amount 和 payMethod 必须与首次请求一致；首次显式传入 credentialId 时，重试也必须保持相同值。除此之外，notifyUrl、redirectUrl、商品信息和 attach 不参与服务端的幂等比对。

查看统一签名指南

查询订单

请求参数

{
  "appId": "Zu78qwe1",
  "merchantOrderNo": "ALI202608070001",
  "payType": "ALIPAY",
  "signature": "..."
}

返回结果

{
  "code": 0,
  "message": "ok",
  "data": {
    "platformOrderNo": "ALI20260807110917E2BF35",
    "merchantOrderNo": "ALI202608070001",
    "amount": "20.00",
    "status": 2,
    "tradeNo": "2026080722000000000001",
    "payTime": 1786072157
  }
}

status	说明
1	待支付
2	已支付
3	已关闭

支付成功通知

XPay 验证支付宝 RSA2 签名、支付宝 AppID、平台订单号和金额后，将支付结果以 application/x-www-form-urlencoded POST 到下单时的 notifyUrl。

商户收到的表单字段

appId=Zu78qwe1
platformOrderNo=ALI20260807110917E2BF35
merchantOrderNo=ALI202608070001
payType=ALIPAY
amount=20.00
status=PAID
payTime=1786072157
tradeNo=2026080722000000000001
attach=user-10001
signature=...

商户必须使用自己的 XPay AppSecret 对除 signature 外的所有非空字段重新计算签名，并按 merchantOrderNo 做幂等处理。平台在收到 2xx 响应且响应体为 success、ok，或 JSON {"code":0} 时确认通知成功；否则按重试计划再次通知。商户应快速返回确认，并使用查单接口作为补偿。

redirectUrl 只用于用户浏览器同步跳转，不能作为支付成功依据；入账必须以异步通知或查单结果为准。

常见错误

code / message	原因与处理
1001 / invalid callback URL	notifyUrl 或 redirectUrl 不是有效 URL
1001 / credentialId invalid	显式传入的 credentialId 不是正整数
1001 / payMethod must be wap or web	payMethod 只能填写 `wap` 或 `web`
1002 / signature error	检查 XPay AppSecret、字段大小写、空值过滤和签名排序
1004 / order permission disabled	商户下单权限未启用
1005 / merchant not found	appId 必须填写 XPay 商户 AppID，不是支付宝应用 AppID
1006 / order not found	该商户下不存在对应支付宝订单
1009 / Alipay credential not found, not approved, or not enabled	`credentialId` 不属于由 `appId + signature` 认证出的当前商户，或凭据未审核、未启用、已删除；未指定时表示当前商户没有可自动选择的凭据