发起付款接口


扫码请求步骤:

  1. 在服务器端构建请求参数,POST参数到请求地址
  2. 根据返回内容在你的支付页面渲染出二维码(注意目前订单二维码过期时间指定为5分钟),并告知用户最终应该支付的金额和二维码过期时间。只支持异步回调,支付页面需由开发者自己编写,并和开发者的系统数据库的订单模块深度集成
  3. 用户支付成功后,开发者的服务器接收云端异步通知,在前端提示用户支付成功

请求地址:https://open.yunmianqian.com/api/pay

调用方法:POST (注意请求头中的 content-type 必须为 application/x-www-form-urlencoded,php可使用http_build_query函数将参数数组 表单化 )

备注:为安全起见,目前只支持在服务器端请求数据接口,不支持在浏览器端请求,否则会出现跨域问题

请求参数:

字段名称 字段类型 必填参数 说明
app_id int(16) Y 应用ID,在后台系统设置页面查看
out_order_sn string(32) Y 商家订单编号,即你自己系统里的订单编号,便于后续对账
name string(32) Y 订单销售商品名称
pay_way string(32) Y 支付方式,可选alipay/wechat(注意单词不是wxchat)
price int(16) Y 订单价格(单位为分)
attach string(255) N 开发者自定义数据(可选填),在支付成功后notify回调的时候会原样返回
notify_url string(32) Y 支付成功后回调地址
sign string(32) Y 签名,将参数按 app_id + out_order_sn + name + pay_way + price + attach + notify_url + app_secret 顺序拼接后md5(32位小写)(纯 value 拼接,不要包含 + 号)。注意最后一个参数是app_secret,可在云端系统后台设置页面查看

针对特殊需求,其他请求参数:

  • 在请求网址后面加参数?order_cache=true :为解决客户端可能重复请求的情况,当客户端请求数据中 out_order_sn 相同的情况下,则返回不过期的已创建的订单,若已创建的订单过期,则返回新的订单数据(这样不会产生很多订单、用户短期内多次点击付款订单金额不会变化)。在请求网址后面加参数?order_cache=false,则云端订单不会缓存 。默认是自动缓存云端订单!!!

PS:目前订单二维码过期时间指定为5分钟,当开启order_cache开关后,为了留给客户足够的支付时间,旧的云端订单将会提前3分钟过期,意思是还有3分钟以内过期的旧的云端订单将不会返回,直接返回新的云端订单数据

  • 在请求网址后面加参数?price_type=floor 只会返回价格小于请求价格的二维码;加参数?price_type=ceil 只会返回价格大于请求价格的二维码。默认是先查找价格小于请求价格的二维码

接口返回(注意需要手动urldecode),一般只需要关注pay_price和expire_at这两个参数即可:

字段名称 字段类型 必填参数 说明
code int(16) Y 状态码。200:成功调用,1001:签名错误,1002:无可用二维码,没有可用于这个订单金额的二维码,你可以多传一些这个价格附近的固定金额或上传一个不固定金额二维码,1003:缺少参数,1004:请求值错误
msg string(32) Y 状态信息,code字段所对应的信息。200:"success",1001:"secret_incorrect",1002:"qr_limit",1003:"missing_argument",1004:请求值错误。不支持本地调试
data string(32) Y 将下面的所有参数括起来
order_sn string(32) Y 云端唯一订单编号,可用于查询订单状态
out_order_sn string(32) Y 你调用接口时填入的商家订单编号
pay_way string(32) Y 支付类型 alipay/wechat/mipay,此值可能和你开始传入的值不同,有时候会使用第三方聚合支付方式
price int(16) Y 订单价格(单位为分)
qr string(32) Y 支付二维码内容链接,开发者在前端页面可以用jquery的qrcode插件将此链接字符串渲染出二维码图片
qr_type string(32) Y 二维码类型。返回值为fixed/business/no_fixed/original,分别为个人版固额二维码/商业版收款码/个人版非固额二维码/原价
qr_price int(16) Y 返回的二维码的金额(单位为分)。如果为0或-1表示使用的是不固定金额二维码,具体金额需要用户输入,需要在付款时让用户自己输入 pay_price 的数值
pay_price int(16) Y 【重要】用户最终应该支付的金额(单位为分),云端将会依靠此金额来区分是哪个用户在支付,这个金额数字必须显示在你的支付页面上!!!
expire_in int(16) Y 支付二维码剩余过期秒数。新订单指定为300s,旧订单则返回剩余秒数
expire_at string(32) Y 【重要】支付二维码过期具体时间。若用户在过期时间外支付,则不会回调!所以需要在你的支付页面显示支付剩余时间,同时必须在过期时,在支付页面提示用户订单已过期并隐藏掉二维码!并提示用户重新下单
cloud_status string(32) Y 云端监控状态,根据订单支付方式返回相应云端监控状态。返回值为online/offline,分别为在线/掉线(处于掉线时不影响此API接口的返回结果,只是无法回调)
server_time string(32) Y 服务器当前时间

接口返回示例:

 {
     "code":200,
     "msg":"success",
     "data":{
          "order_sn": "201907098484845164151",
          "out_order_sn": "201905015",
          "pay_way": "wechat",
          "price": 3500,
          "qr": "wxp://f2f0-vFHHDCw3LjsdiigJzXyQ0nO0QKpQK2e",
          "qr_type": "fixed",
          "qr_price": 1000,
          "pay_price": 1000,
          "expire_in": 300,
          "expire_at": "2019-03-23 04:13:12",
          "cloud_status": "online",
          "server_time": "2019-03-23 04:13:12",
     }
 }

当订单支付成功后,云端会立即向你的服务器发起回调通知。

当你的服务器收到云端的回调请求后,只要返回"success"小写单词字符串(不包括引号),那么云端会认为通知成功,否则还会最多通知 6 次,分别间隔 0s/30s/1分钟/3分钟/5分钟/10分钟/15分钟,注意做好通知去重逻辑,你也可以在后台手动补单。历史回调日志可在后台查看,方便调试。

接口地址:你传入的 notify_url 参数

调用方法:POST

调用参数(注意需要手动urldecode):

字段名称 字段类型 必填参数 说明
app_id int(16) Y 应用ID。在后台系统设置页面查看
order_sn string(32) Y 云端唯一订单编号
out_order_sn string(32) Y 你调用接口时填入的商家订单编号
notify_count int(16) Y 通知的次数(包括本次)
pay_way string(32) Y 支付方式,alipay/wechat/mipay,此值可能和你开始传入的值不同,有时候会使用第三方聚合支付方式
price int(16) Y 订单价格(单位为分)
qr_type string(32) Y 二维码类型。返回值为fixed/business/no_fixed/original,分别为个人版固额二维码/商业版收款码/个人版非固额二维码/原价
qr_price int(16) Y 返回的二维码的金额(单位为分)。如果为0或-1表示使用的是不固定金额二维码,具体金额需要用户输入,需要在付款时让用户自己输入 pay_price 的数值
pay_price int(16) Y 用户最终应该支付的金额(单位为分),云端将会依靠此金额来区分是哪个用户在支付
created_at string(32) Y 订单创建的时间
paid_at string(32) Y 用户支付的时间
attach string(255) Y 开发者自定义数据,原样返回
server_time string(32) Y 服务器时间
sign string(32) Y 签名, 将参数 app_id + order_sn + out_order_sn + notify_count + pay_way + price + qr_type + qr_price + pay_price + created_at + paid_at + attach + server_time + app_secret 顺序拼接后md5(32位小写)(纯 value 拼接,不包含 + 号)。注意最后一个参数是app_secret,可在云端系统后台设置页面查看

md5签名算法php示例:

function sign($app_id, $out_order_sn, $name, $pay_way, $price, $attach, $notify_url, $app_secret ) {
    return md5($app_id.$out_order_sn.$name.$pay_way.$price.$attach.$notify_url.$app_secret);
}

results matching ""

    No results matching ""