订单检查接口
此接口区别于订单查询接口,此接口是根据支付宝、微信等支付渠道的订单号进行检查再回调。
使用场景是:当用户输错金额、或用户订单超时付款,此时不会回调。此时在支付页面上,用户可复制提供微信、支付宝等支付软件的订单号,开发者凭借此订单号手动查询支付渠道的实时订单列表,并根据此API接口的返回数据进行处理,处理逻辑可参考:用户实际支付金额 减去 应付商品价格 的绝对值 小于 0.1元,可以判断已支付成功
注意:此接口会优先在云端数据库的 价格未匹配订单列表 中进行查询,若未查到,则会对相应的支付渠道发起一次完整的订单查询流程。所以此接口较慢,一般在3-10s返回数据,注意设置超时timeout为60s。
注意2:为保证微信支付渠道查询结果正常,使用此接口前请取消关注取消关注“微信收款助手”公众号
注意3:此接口请勿由程序循环自动发起,应该由顾客手动发起,发起间隔最好在10s以上,并发会导致云端掉线。为防止掉线,若10s内发起两次以上请求,云端只会从 价格未匹配订单列表 缓存中进行查询,此时可让顾客等待10s后再重试
注意4:只能查询最近3天的订单
此接口只作为订单的辅助回调,严禁使用此接口做订单的轮询回调,否则将自动导致IP进入黑名单!
请求地址(不支持浏览器直接打开):https://open.yunmianqian.com/api/check
调用方法:POST (注意请求头中的 content-type 必须为 application/x-www-form-urlencoded )
请求参数:
字段名称 | 字段类型 | 是否必填 | 说明 |
---|---|---|---|
app_id | int(16) | Y | 应用ID,在后台系统设置页面查看 |
pay_way | string(32) | Y | 支付渠道,可能值有wechat、alipay。若需要查询多个渠道,请以英文逗号,隔开。绝大部分使用场景下应该填单一渠道,以减少此接口的返回时间。注意若mipay处于在线状态,会强制增加查询mipay支付渠道 |
trade_sn | string(32) | Y | 微信、支付宝支付渠道的订单编号 |
order_sn | string(32) | N | (可选)云端唯一订单编号。若有此参数,则云端在查找到相关价格订单后,会自动回调。若没有此参数,则需要开发者自己根据接口返回的数据,进行本地回调。若使用场景允许则建议填写,云端会自动处理回调逻辑 |
out_order_sn | string(32) | N | (可选)商家订单编号,同上。若需要自动回调,一般order_sn和out_order_sn选择其中一个填写即可。若两个参数都有值,会忽略此参数 |
sign | string(32) | Y | 签名, 将参数 app_id + pay_way + trade_sn + order_sn + out_order_sn + app_secret 顺序拼接后md5(32位小写)(纯 value 拼接,不要包含 + 号)。注意最后一个参数是app_secret,可在云端系统后台设置页面查看 |
接口返回(注意需要手动urldecode):
字段名称 | 字段类型 | 是否必填 | 说明 |
---|---|---|---|
code | int(16) | Y | 状态码,200:成功调用,1001:签名错误,1003:缺少参数 |
msg | string(32) | Y | 状态信息,code字段所对应的信息。200:"success",1001:"secret_incorrect",1003:"missing_argument" |
data | string(32) | Y | 包含下面的 cloud_status 和 list 两个成员 |
cloud | string(32) | Y | 根据你需要查询的支付渠道,返回对应的云端监控状态,返回值可能为online/offline,分别为在线/掉线。若处于掉线状态时,下面的list数组中相应支付渠道列表可能为空数组。is_block为是否被10s/每次的并发限制屏蔽,若为true,说明此次请求只查询了缓存,未查询实时订单列表。list若为空,则结果不可信,此时可让顾客等待10s后再重试 |
list | array() | Y | 这是一个数组,每个成员都包括下面的所有参数。若未查到相关数据,则为空数组。若处于掉线状态且相应支付渠道list列表有订单数据,则说明此次查询只是从 价格未匹配订单列表 缓存中进行查询。注意此数组目前最多有一个成员 |
pay_way | string(32) | Y | 支付渠道,可能值有alipay、wechat、mipay。 |
trade_sn | string(32) | Y | 微信、支付宝支付渠道的订单编号 |
pay_price | int(16) | Y | 用户实际支付金额(单位为分) |
paid_at | string(32) | Y | 用户支付的时间 |
is_match | string(32) | Y | 订单价格是否已匹配,可能值有true、false。若为true,开发者一般无需再作后续处理,云端已自动回调。若为false,开发者可根据实际情况进行本地回调,处理逻辑可参考:用户实际支付金额 减去 应付商品价格 的绝对值 小于 0.1元,可以判断已支付成功。注意若你传入此API接口的order_sn被成功匹配,云端此时已自动回调,此值也会为true。注意若此值为false,则下面的order_sn和out_order_sn的值均为空字符串"" |
order_sn | string(32) | Y | 云端唯一订单编号,若为空字符串"",说明此价格订单未成功匹配。则若不为空,说明此价格订单已被成功匹配并回调 |
out_order_sn | string(32) | Y | 商家订单编号,若为空字符串"",说明此价格订单未成功匹配。若不为空,说明此价格订单已被成功匹配并回调 |
query_count | int(16) | Y | 此价格订单的查询次数(包括本次),只有查询次数为1才有后续的处理价值!本参数是为了防止顾客多次本地回调 |
server_time | string(32) | Y | 服务器时间 |
接口返回示例:
{
"code": 200,
"msg": "success",
"data": {
"cloud": {
"wechat": {
"status": "online",
"is_block": false
},
"alipay": {
"status": "online",
"is_block": false
},
"mipay": {
"status": "online",
"is_block": false
}
},
"list": [{
"pay_way": "wechat",
"trade_sn": "cad5076f55834f5fadddcfc018cc4068",
"pay_price": 1000,
"paid_at": "2019-03-23 04:13:02",
"is_match": false,
"order_sn": "",
"out_order_sn": "",
"query_count": 1,
}
],
"server_time": "2019-03-23 04:13:12",
}
}