支付 API

商数通开放平台提供统一的支付收银台能力，支持微信支付、支付宝等主流支付方式。

创建收银台会话

创建支付收银台会话，获取可供用户跳转的收银台链接。

请求

POST /open-api/v1/payment/cashier/create

请求体

字段	类型	必填	说明
merchantId	long	是	商户 ID
outTradeNo	string	是	商户订单号（幂等键，全局唯一）
totalAmount	int	是	支付金额（分），必须大于 0
subject	string	是	商品标题，最长 32 个字符
body	string	否	商品描述，最长 128 个字符
notifyUrl	string	是	异步回调通知地址（必须为 HTTPS）
returnUrl	string	否	支付完成后的回跳地址
expireMinutes	int	否	收银台过期时间（分钟），默认 30 分钟
attach	string	否	附加数据（透传至回调通知），最长 512 个字符

请求示例

curl -X POST 'https://openapi.example.com/open-api/v1/payment/cashier/create' \
  -H 'X-App-Key: ak_1234567890abcdef' \
  -H 'X-Timestamp: 1709280000' \
  -H 'X-Nonce: a1b2c3d4' \
  -H 'X-Sign: calculated_signature' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 1001,
    "outTradeNo": "ORDER20260310001",
    "totalAmount": 29900,
    "subject": "深层清洁护理服务",
    "notifyUrl": "https://app.example.com/pay/notify",
    "returnUrl": "https://app.example.com/pay/result",
    "expireMinutes": 30
  }'

响应参数

字段	类型	说明
tradeNo	string	平台交易号（用于后续查询）
cashierUrl	string	收银台页面 URL，引导用户跳转完成支付

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "tradeNo": "10086",
    "cashierUrl": "https://cashier.example.com/pay?token=xxxxx"
  }
}

---

查询支付结果

根据平台交易号查询支付订单的当前状态。

请求

GET /open-api/v1/payment/query

请求参数

参数	类型	必填	说明
tradeNo	long	是	平台交易号（创建收银台时返回的 tradeNo）

请求示例

curl -X GET 'https://openapi.example.com/open-api/v1/payment/query?tradeNo=10086' \
  -H 'X-App-Key: ak_1234567890abcdef' \
  -H 'X-Timestamp: 1709280000' \
  -H 'X-Nonce: a1b2c3d4' \
  -H 'X-Sign: calculated_signature'

响应参数

字段	类型	说明
tradeNo	string	平台交易号
outTradeNo	string	商户订单号
tradeStatus	string	支付状态（见下方说明）
totalAmount	int	支付金额（分）
payTime	string	支付成功时间（状态为 SUCCESS 时有值）
attach	string	创建时传入的附加数据

支付状态说明

状态值	说明
WAIT_BUYER_PAY	等待用户支付
SUCCESS	支付成功
REFUND	已退款
CLOSED	已关闭（超时或主动关闭）
UNKNOWN	未知状态

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "tradeNo": "10086",
    "outTradeNo": "ORDER20260310001",
    "tradeStatus": "SUCCESS",
    "totalAmount": 29900,
    "payTime": "2026-03-10T15:02:00+08:00",
    "attach": null
  }
}

支付回调通知

支付成功后，平台将向您创建收银台时传入的 notifyUrl 发送异步回调通知。建议不要仅依赖轮询查询，应以回调通知为主要通知方式。详见回调通知文档。