本文档对果仁支付平台商户接口的使用进行详细说明，帮助商户熟悉了解果仁支付的交易流程，方便商户快捷、安全的接入果仁支付平台。

本文档的阅读对象是使用果付的商户技术人员，要求熟悉JAVA，PHP，JSP，ASP，ASP.net开发等其中一种开发语言。

###1.3 业务术语

商户服务器需要依赖果付提供的SDK包完成，相关安全规范以及接口的开发。

1. 用户在商户APP/WEB商城下单;
   
2. 商户服务器接收到下单请求，向果付支付系统下单;
   
3. 果付支付系统验证数据;
   
4. 验证通过通知商户服务器，下单成功;
   
5. 商户后台通知商户APP唤起果仁宝APP;
   
6. 果仁宝APP验证用户的授权状态;
   
7. 果仁宝APP用户有效则会通过果仁宝向果付系统拉取订单信息;
   
8. 果付系统会检查用户下单信息的有效性;
   
9. 有效订单，则给果仁宝用户展示订单信息;
   10)用户输入支付密码;
   11)果仁宝APP发送支付请求到果付系统，果付系统发送支付请求到银行/第三方;
   12)返回支付结果;
   13)展示支付结果给用户;
   14)银行/第三方发送异步通知给果付系统;
   15)果付系统发送异步通知给商户服务器。
   

为保证数据传输过程中的数据真实性、完整性和不可抵赖，我们需要对数据进行签名，在接收响应数据之后进行签名校验。

具体签名过程为：
1）接口中的请求参数均采用表单形式提交;
2）签名时对于所有以=分隔的参数对(即key，value)以字母顺序进行排序，并以&作为连接符拼接成待签名串;
3）用商户的私钥对待签名串做签名操作，签名时算法选择MD5。具体做法为将商户的秘钥与待签名串拼接在一起（秘钥在前)，并使用相应的charset进行编码，计算编码后的数据MD5摘要作为签名;
4）将签名后的签名串放在表单域里和其他表单域一起通过HTTP Post的方式传输给果付系统平台。

当使用MD5进行签名时，将商户的秘钥与待签名串拼接在一起（秘钥在前），并使用相应的charset进行编码，在进行计算MD5摘要。注意charset同样会作为参数出现在表单中。

以商户标准接口为例
接口中的请求参数将包含merchantId，service，version, requestTime, charset, signType, bizConten，sign字段。

签名串为

bizContent=biz_content&charset=UTF-8&merchantId=21112345678&requestTime=2016-10-14+14%3A01%3A42&service=order.create& signType=MD5&version=1.0

**注意:**字段之间无空格符
计算得到的签名为B3DB73CD8CFC3C6E0671FAAAEE1B049（注意签名串为大写）
当果付系统接收到请求参数时同样会从提交过来的表单中获取所有的参数并进行相同的签名方式, 并将计算得到的签名与表单中签名进行比对。

商户标准接口的响应均为json格式的，并且采用统一的格式：sign字段和response字段，sign字段为response的签名，response为具体的响应数据。签名字段为response后面括号内的所有内容(包括括号)。为了避免json反序列化出现的字段顺序不一致问题，response中的所有字段均按照字母顺序进行排序。

下面是一个响应的例子，reponse中的字段code，data，msg是有序的。

{
  "response": {
    "code": "000000",
    "data": {
      "appId": "GAPP_59F0609B61D0F63E",
      "gopOrderNo": "MN787989390099980289",
    },
    "msg": "成功"
  }
   "sign": "E63D259F3C9B43E972B799997C812EAB"
}

请求方式：HTTPS POST请求
参数类型：application/x-www-form-urlencoded
请求地址：https://pay.goopal.com.cn/gateway

标准接口都采用统一的请求格式，格式如下：

<br>
响应实例：
``` java
{
  "response": {
    "code": "000000",
    "data": {
      "appId": "GAPP_59F0609B61D0F63E",
      "gopOrderNo": "MN787989390099980289",
      "h5Url": "",
      "merchantId": "2111234567890832",
      "notifyUrl": "http://test.com/notify.jsp",
      "orderDate": "2016-10-17 20:11:25",
      "orderNo": "MN201610101049225131",
      "pageRetUrl": "http://test.com/redirect.jsp",
      "remark": "remark",
      "singleNo": "MN201610101049225131",
      "source": 1
    },
    "msg": "成功"
  }
   "sign": "E63D259F3C9B43E972B799997C812EAB"
}

请求

目前主要有两种通知类型：
1）交易成功的通知：用户支付成功时发起该通知;
2）退款成功的通知：退款成功时发起该通知。商户可以通过两种途径发起退款：通过登录商户后台发起或者通过接口发起。当通过登录商户后台发起时，商户退款订单号由商户后台生成，接收到退款通知时商户需要根据通知内容进行落单并进行相应处理。

请求方式：HTTP POST
参数类型：application/x-www-form-urlencoded

签名机制：签名机制与前面接口签名机制相同

交易成功通知
通用接口字段

通用内容字段