接入文档

原点支付支持两种接口模式,标准模式和自定义模式。标准模式下,用户发起付款请求后,会跳转至官方的支付页面,付款完成后,会自动跳转至商户指定的页面。自定义模式下,原点支付会返回订单相关的收款码信息,商户可自定义支付页面,并通过收款结果查询接口,查询用户是否支付成功。

接口约定

1. 数据编码统一为 utf-8。

2. 该文档中提到的 token,都是指商户 token。可在原点支付网站后台查看。

3. 请求返回的接口,格式为 json,结构如下:

                      
    {
        success: xxx,     // true 为成功,false为失败
        msg: xxx    // 当success返回非true时,msg字段将返回失败原因告知,反之则为请求发起支付成功
    }
                      
                  

4. 对于有数据提交的接口,统一用 post 的方式(查询接口除外)。数据格式为:

1. 发起付款接口

跳转支付页接口URL:

http://pay.goukm.com/index

获取支付JSON数据接口URL:

http://pay.goukm.com/index?format=json

请求方式:

post

请求参数:

参数名 含义 验证 类型 说明
order_number 商户自定义订单号 必填 string 我们会据此判别是同一笔订单还是新订单。我们回调时,会带上这个参数。例:order_201710192541,不同的订单订单号不能重复
partner 商户uid 必填 string 商户唯一标识,注册后可在网站后台,接口信息栏查看。
pay_type 支付方式 必填 int 1:微信;
2:支付宝。
pay_money 订单价格 必填 float 单位:元。精确小数点后2位。
notify_url 异步回调网址 必填 string 用户支付成功后,原点支付会主动发送一个 post 消息到这个网址。该参数不要 urlencode。例如:https://商户的域名/pay_notify。
href_backurl 同步跳转网址 请求的接口路径为/index?format=json不用填。 请求的接口路径为/index必填 string 如果使用的是我们官方的支付页面那么。用户支付成功后,我们会让用户浏览器自动跳转到这个网址。由您自定义。不要urlencode。例:https://www.abc.com/return.php
account_name 指定收款账户名称 选填 string 默认为系统随机,如需指定收款账号就填您的后台收款码管理的账号名称
good_name 商品名称 选填 string 商品名称,原点支付后台的订单列表会显示该字段,方便订单归类。
sign 秘钥 必填 string 把使用到的所有参数,连Token一起,按照下面指定的顺序。把参数值拼接在一起。做md5-32位加密,取结果字符串大写。得到key。网址类型的参数值不要urlencode。
key的拼接顺序:如用到了所有参数,就按这个顺序拼接:partner + pay_type + order_number + pay_money + notify_url + good_name + href_backurl + account_name + token
注意:使用/index?format=json请求,是不需要传入href_backurl,那么无需吧href_backurl加入加密串
加密串示范:
partner=82326&pay_type=1&order_number=20190830559958307475980993&pay_money=20&&notify_url=https://www.yuanduan_custompay.com/index/index/test_notify_url&good_name=话费充值50元&href_backurl=https://www.yuanduan_custompay.com/test.html&account_name=有何不可1&key=您的Token

将以上字符串通过MD5加密方式得到32位加密串后再将字符串转为大写。 结果为:325FAC96B4FD122EAECACD3F02E1F019,将结果通过sign参数传入即可

反之如果href_backurl没有被指定,则加密字符串为:partner=82326&pay_type=1&order_number=20190830559958307475980993&pay_money=20&notify_url=https://www.yuanduan_custompay.com/index/index/test_notify_url&good_name=话费充值50元&account_name=有何不可1&key=您的Token

再比如account_name与href_backurl参数没有被指定,则加密字符串为:partner=82326&pay_type=1&order_number=test_order93361b3bd35efac3&pay_money=1.00&notify_url=https://www.yuanduan_custompay.com/index/index/test_notify_url&good_name=原点支付测试&key=您的Token

为空的参数不加入签名串,且一定要按照以上的签名顺序!
1:出于安全原因,原点支付后台会将接收到的参数进行加密,与 key 完全匹配,防止支付信息被第三方篡改。
2:商户 token 非常重要,一定不要显示在任何网页代码、网址参数中。只可以放在服务端,以免发生意外的安全风险。
3:当请求路径为/index,成功发起支付时,会返回pay_url支付地址。服务端获取到该地址后直接进行跳转即可呈现我们的默认的支付页面。当 /index?format=json,即会返回支付参数及收款码的相关信息。

通过/index路径请求接口时,会返回pay_url字段,服务端只需直接跳转该地址让用户支付即可。

通过/index?format=json 请求上述接口,接口会返回支付信息与相关二维码参数。你可以使用你的页面展示相关支付信息:


以下是通过/index路径请求接口的返回结果
参数名 含义 类型 说明
success 订单状态是否生效 boolean 用于区分订单是否创建成功,true为成功反之false为订单订单创建失败。
error 错误码 int 当error为0时表示成功创建订单,当error不为0时表示订单创建失败,可通过msg提示的错误进行修正
pay_url 原点支付付款链接 string 当请求路径为/api/index时,原点支付会通过该参数提供我们的付款页面地址,开发者只需直接跳转到该地址即可让用户支付
msg 接口返回信息 string 该字段告知开发者订单状态。提示的文字信息,会根据不同场景,展示不同内容

返回示例:

                      
      {
          success:true,
          error: 0,
          pay_url:http://pay.goukm.com/pay_view/sys_order_number/20190828535748280195759578
          msg : 发起支付成功
      }
                      
                  

以下是通过/index?format=json路径请求接口的返回结果
参数名 含义 类型 说明
success 订单状态是否生效 boolean 用于区分订单是否创建成功,true为成功反之false为订单订单创建失败。
error 错误码 int 当error为0时表示成功创建订单,当error不为0时表示订单创建失败,可通过msg提示的错误进行修正
expire 订单有效期 int 订单需要在有效期内支付,否则超时二维码将被回收重新试用,该订单会失效。单位为秒
expire_time 订单过期时间 int 订单具体过期时间,格式为时间戳。表示当前订单创建一刻的到期时间。该时间到后订单失效,支付将会无法回调;
real_price 二维码金额 float 表示用户实际支付的金额。一般会和price值一致,如果同时存在多个用户支付同一金额,就会和price存在一定差额,差额一般在1-2分钱上下,越多人同时付款,差额越大。当然你也可以指定自己的差额
pay_money 订单价格 float 是您在发起付款接口传入的订单价格
order_id 您的自定义订单号 string 是您在发起付款接口传入的您的自定义订单号
sys_order_number 系统订单号 string 该订单号在原点支付中存在的唯一单号
pay_type 支付类型 int 您在发起付款类型 1 微信 2 支付宝。
account_name 收款账户 string 系统分配你在平台的收款账号名称
qrcode 收款二维码 string 收款二维码内容,想展示二维码内容,可以qrcode值放到这个网址后面,如: https://www.kuaizhan.com/common/encode-png?large=true&data=wxp://f2f1hIJ0Ez0xnXg6y5UB5fbbLz0PHd0Ixx69
is_custom_qrcode 是否为自定义二维码 int 1为自定义二维码,支付金额由付款者输入 0为固定二维码,用户扫码后直接支付
msg 接口返回信息 string 该字段告知开发者订单状态。提示的文字信息,会根据不同场景,展示不同内容

返回示例:

                  
      {
          success:true,
          error: 0,
          expire:180
          expire_time : 1566964723
          real_price : 100.01
          pay_money : 100
          order_id : "recharge201908281155428403639813"
          sys_order_number : "20190828102988286454376706"
          pay_type : 1
          account_name : "有何不可"
          qrcode : "wxp://f2f1hIJ0Ez0xnXg6y5UB5fbbLz0PHd0IxCqw"
          is_custom_qrcode : 1
          msg : "发起支付成功"
      }
                  
      

2. 付款成功回调通知

用户付款成功后,原点支付会向商户发起付款请求时传入的 notify_url 网址,发送回调通知。

请求方式:

post

参数内容:

参数名 含义 类型 说明
partner 商户uid string 发起支付的对应商户号
order_number 自定义订单号 string 商户在发起付款接口传入的自定义订单号。
pay_money 订单金额 string 商户发起付款接口传入的订单金额。
real_money 实际定价 string 实际支付分配的二维码支付金额。
pay_type 支付方式 int 1:微信;2:支付宝。
sys_order_number 原点支付官方订单号 string 可通过该字段,二次核查支付是否成功。
nonce_str 无重复字符串 string 原点支付回调时都会生成唯一的随机字符串,用于保证sign的安全性
account_name 收款账户 string 成功收款的对应收款账户昵称
sign 秘钥 string 把返回的所有参数除去Sign,连同 token 拼接在一起。做 md5-32 位加密,取字符串大写
key的拼接顺序:partner + order_number + pay_type + sys_order_number + nonce_str + pay_money + real_money + account_name + token
如: "partner=82326&order_number=test_orderd26b24d6fd03ad28&pay_type=1&sys_order_number=20190828535748280195759578&nonce_str={8AB60CB6-9EA0-2ED8-0A16-9538B6437692}&pay_money=1.000&real_money=1.01&account_name=有何不可&key=你的商户Token"

吧当前字符串通过 MD5 32位加密后取字符串大写进行比对
注意:商户可将上述返回参数加密后,与返回的 Sign 进行匹配,匹配成功后,再做订单发货逻辑

3. 付款成功自动跳转(仅 /index)也就是原点支付提供的付款页面

用户付款成功后,原点支付先通过付款成功回调接口,通知商户服务器付款成功,再过1秒左右,将用户跳转至商户在发起付款请求时传入的 href_backurl 地址。

传参方式:

get

参数内容:

参数名 含义 类型 说明
order_number 自定义订单号 string 商户可以通过此 order_number 在自家后台查询用户是否付款成功,给用户一个付款成功的展示。
注意:请不要将此跳转认为是用户付款成功的判断条件,此行为极不安全。请根据原点支付的付款成功回调通知是否送达,来判断用户是否支付成功。

4. 支付结果查询接口

请求地址:

http://pay.goukm.com/index/orderQuery

请求方式:

get | post均可

请求参数:

参数名 含义 验证 类型 说明
sys_order_number 原点支付官方订单号 必填 string 原点支付官方订单号。该参数会在付款接口与回调接口中返回。

请求返回:

参数名 含义 类型 说明
code 状态码 int 当返回结果 code=1 时,则为支付成功。

当返回结果 code=2 时,则为订单已经过期失效。

当返回结果 code=3 时,暂未获取到支付状态,用户可能正在支付。

msg 状态信息 string 根据订单不同状态返回对应文字说明