支付网关 API

v1.0

POST https://zs.iot.myxx.vip/api.php

统一接口入口，支持 被扫支付（pay） 和 订单查询（query） 两个操作。支持 微信支付、支付宝、银联云闪付 三种支付方式，自动识别付款码并路由到对应通道（工行聚合支付 / 微信支付 / 支付宝）。

快速开始

# 被扫支付（使用 curl 测试）
curl -X POST API_URL \
  -H "Content-Type: application/json" \
  -d '{"action":"pay","mch_id":"TEST001","timestamp":'1710000000,"out_trade_no":"ORDER001","total_fee":1,"auth_code":"1347xxxxxxxxxxxx","subject":"测试商品","sign":"xxxxx"}'

接口列表

POST被扫支付

参数	类型	必填	说明
`action`	string	是	固定值 `pay`
`mch_id`	string	是	商户号
`timestamp`	int	是	当前时间戳（秒），与服务器误差不超过5分钟
`sign`	string	是	MD5签名
`out_trade_no`	string	是	商户订单号，最长64位
`total_fee`	int	是	金额，单位：分
`auth_code`	string	是	用户付款码，10-64位
`subject`	string	是	商品标题
`attach`	string	否	附加信息，最多100个字符，透传到银行账单

POST订单查询

参数	类型	必填	说明
`action`	string	是	固定值 `query`
`mch_id`	string	是	商户号
`timestamp`	int	是	当前时间戳（秒）
`sign`	string	是	MD5签名
`trade_no`	string	否	网关订单号（精准查询）
`out_trade_no`	string	否	商户订单号（返回全部记录）

trade_no 和 out_trade_no 至少传一个

签名算法

1. 所有参数（不含 sign）按 ASCII 码升序排列，空值不参与
2. 拼接为 key1=val1&key2=val2 格式
3. 末尾追加 &key=商户密钥
4. 对整串做 MD5 取小写

响应说明

所有接口返回统一 JSON 格式：{ "code": int, "msg": "string", "data": ... }

pay（被扫支付）返回值：

字段	类型	说明
`code`	int	0=成功受理
`msg`	string	提示信息
`data.trade_no`	string	网关订单号，用于后续查询
`data.out_trade_no`	string	商户订单号
`data.pay_method`	string	支付方式: wechat / alipay / unionpay
`data.channel`	string	支付通道: icbc / wxpay / alipay
`data.status`	int	0=处理中 / 1=支付成功 / 2=扣款失败
`data.total_fee`	int	金额（分）

pay 响应示例：

{
    "code": 0,
    "msg": "请求已受理",
    "data": {
        "trade_no": "MYXX20260114A1B2C3D4",
        "out_trade_no": "ORDER001",
        "pay_method": "wechat",
        "channel": "icbc",
        "status": 0,
        "total_fee": 100
    }
}

query（订单查询）返回值：

字段	类型	说明
`code`	int	0=成功
`msg`	string	提示信息
`data[].trade_no`	string	网关订单号
`data[].out_trade_no`	string	商户订单号
`data[].mch_id`	string	商户号
`data[].status`	int	0=处理中 / 1=支付成功 / 2=扣款失败
`data[].total_fee`	int	金额（分）
`data[].pay_method`	string	支付方式: wechat / alipay / unionpay
`data[].channel`	string	支付通道: icbc / wxpay / alipay
`data[].subject`	string	商品标题
`data[].bank_serial`	string	渠道流水号（支付成功时返回）
`data[].pay_time`	string	支付完成时间 Y-m-d H:i:s
`data[].created_at`	string	订单创建时间
`data[].updated_at`	string	最后更新时间

query 响应示例：

{
    "code": 0,
    "msg": "查询成功",
    "data": [{
        "trade_no": "MYXX20260114A1B2C3D4",
        "mch_id": "TEST001",
        "out_trade_no": "ORDER001",
        "total_fee": 100,
        "subject":     "测试商品",
        "pay_method": "wechat",
        "channel": "icbc",
        "status": 1,
        "bank_serial": "38170461955196440454428",
        "pay_time": "2026-01-14 12:30:00",
        "created_at": "2026-01-14 12:30:05",
        "updated_at": "2026-01-14 12:30:08"
    }]
}

错误响应示例：

{
    "code": 1003,
    "msg": "签名错误"
}

订单状态

状态码	说明
`0`	处理中 — 需通过 query 接口主动查询最终结果
`1`	支付成功
`2`	扣款失败

不提供异步回调，商户需主动轮询 query 获取结果。建议间隔3-5秒，最多持续30分钟。

错误码

错误码	说明
`0`	成功
`1001`	参数缺失或非法
`1002`	商户不存在或已禁用
`1003`	签名错误
`1004`	请求已过期
`1005`	接口限流
`1006`	订单不存在
`2002`	商户未开通此支付方式的通道
`9999`	系统内部错误

支付方式与通道

系统自动识别用户付款码前缀，确定支付方式后选择合适的通道：

付款码前缀	支付方式	可用通道	说明
`10~15`	`wechat` 微信支付	icbc / wxpay	支持工行聚合支付或微信直连
`25~30`	`alipay` 支付宝	icbc / alipay	支持工行聚合支付或支付宝直连
`62`	`unionpay` 银联云闪付	icbc	仅工行聚合支付通道

商户在后台可配置微信/支付宝的优先通道偏好，留空则使用默认通道（微信→wxpay，支付宝→alipay）

支付宝IoT碰一碰（如意Lite）SPI

POST https://zs.iot.myxx.vip/alipay_iot_spi.php

支付宝 IoT 设备（碰一碰/如意Lite）标准 SPI 接口。支付宝开放平台调用 ISV 服务端，ISV 处理后返回 JSON 格式的响应。

所有 6 个接口在支付宝开放平台配置 同一个 URL，由 method 参数自动路由到对应处理函数。请求格式为 x-www-form-urlencoded，签名算法为 RSA-SHA256（RSA2）。

接口列表（共 6 个）

序号	接口	method	功能
1	IoT标准支付	`spi.alipay.merchant.order.commonisv.pay`	付款码支付（需幂等）
2	IoT标准查询	`spi.alipay.merchant.order.commonisv.query`	订单状态查询
3	收银员签到	`spi.alipay.commerce.fmcgsaascashier.sign`	收银员在设备签到
4	收银员签退	`spi.alipay.commerce.fmcgsaascashier.unsign`	收银员签退
5	查询收银员列表	`spi.alipay.commerce.fmcgsaascashier.batchquery`	门店收银员列表
6	查询收银员状态	`spi.alipay.commerce.fmcgsaascashier.query`	单个收银员签到状态

IoT SPI 签名机制

请求验签（ISV 验支付宝签名）：

取出所有参数，排除 sign 自身
按参数名 ASCII 升序排列，空值跳过
拼接为 k1=v1&k2=v2&... 格式
使用 支付宝公钥 对拼接串进行 RSA-SHA256 验签
校验 utc_timestamp，误差超过 5 分钟拒绝

响应签名（ISV 签名，支付宝验）：

对 response 内所有字段按 key 升序排列，空值跳过
拼接为 k1=v1&k2=v2&...
使用 ISV 应用私钥 RSA-SHA256 签名，Base64 编码
填入外层 sign 字段

响应格式：

{
    "response": {
        "code": "10000",
        "msg": "Success",
        ...业务字段...
    },
    "sign": "Base64签名串"
}

code	含义
`10000`	业务处理成功
`40004`	业务处理失败

IoT SPI 配置要点

config.php 密钥配置：

// 支付宝 SPI 验签公钥（支付宝用它对应的私钥签名请求）
const ALIPAY_SPI_PUB_KEY = '-----BEGIN PUBLIC KEY-----...';

// ISV SPI 响应签名私钥（需在开放平台上传对应公钥）
const ALIPAY_SPI_PRI_KEY = '-----BEGIN PRIVATE KEY-----...';

配置项	说明	获取方式
`ALIPAY_SPI_PUB_KEY`	支付宝公钥	开放平台 → 应用详情 → 接口加签方式 → 查看支付宝公钥
`ALIPAY_SPI_PRI_KEY`	ISV 应用私钥	本地生成 RSA2 密钥对，上传公钥到开放平台，保留私钥

数据库扩展表

表名	说明	关键字段
`alipay_iot_device`	设备与商户门店绑定	terminal_id, mch_id, shop_id, store_id, bind_info, status
`cashier`	收银员及签到状态	mch_id, store_id, cashier_id, cashier_name, terminal_id, status

IoT SPI 快速测试

# 模拟支付宝调用 IoT 支付接口（本地测试）
curl -X POST SPI_URL \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'method=spi.alipay.merchant.order.commonisv.pay' \
  -d 'charset=utf-8' \
  -d 'version=1.0' \
  -d 'utc_timestamp=1710000000' \
  -d 'sign_type=RSA2' \
  -d 'sign=test_signature' \
  -d 'merchant_order_no=TEST001' \
  -d 'terminal_id=FZHAMXTJ3002909' \
  -d 'total_amount=0.01' \
  -d 'auth_code=1347123456789012345' \
  -d 'subject=测试商品'

生产环境签名验签强制开启。详细文档见 alipay_iot_spi.md。