业务和技术接口规范
==================

API 文档简介
------------

- asharp 采用了 HTTP 协议提供各类接口，并且所有接口都是统一请求地址，方便商户简单、快速接入。本 API 包含两类接口，页面浏览器类和系统调用类。

- 页面浏览器类：需要从前端页面以 FORM 表单的形式发起请求，浏览器会自动跳转至汇付的相关页面（一般是快捷短信发送页面），用户在该页面完成相关业务操作后再回跳到商户指定页面，页面方式返回的是标准的表单格式。
- 系统调用类：直接从服务端发起 HTTP 请求，API 会同步返回请求结果，返回的数据格式都是规范 JSON 格式。

接入指南
--------

- 第一步：商户申请

  线下申请，商户开通后，汇付会以邮件方式通知联系人（商户申请页面录入的联系人邮箱），邮件内容包括商户客户号、子账户号、附件（公钥、私钥文件）会在 API 调用时用到。
  
- 第二部：公私钥使用

  商户申请成功后，通知邮件中会包含公钥、私钥文件，私钥文件用于签名API的请求参数，公钥文件用于验证 API 返回参数签名。
  
- 第三步：调用接口

技术接入前请仔细阅读接口文档里的内容：

**接口请求地址**

+-------------+-----------------------------------------------------+
|生产请求 URL | https://finance.chinapnr.com/asharp/merchantRequest |
+-------------+-----------------------------------------------------+
|联调请求 URL | http://mertest.chinapnr.com/asharp/merchantRequest  |
+-------------+-----------------------------------------------------+

以下分别列举常用的交易接口使用流程

**快速接入快捷支付** 

本 API 提供页面版快捷业务接入方式，商户需要对接 前台快捷绑卡接口_ 、充值支付接口_ 完成快捷支付流程，交易过程中可以通过 交易状态查询接口_ 获取订单处理状态，交易结束可以通过 充值支付对账接口_ 交易对账。



接口规范
------------

- 当参数为可选项时，FORM 表单应包含该参数，且赋值长度为零。

- 接口的所有参数值不应该包含特殊字符，如：“&”、“-”和“‘”等。

- 参数编码为 UTF-8 字符集，对于中文、 URL 和 JSON 字符串，提交参数时应做 URLEncode 处理，接口接收返回参数时应做 URLDecode 处理。

- 金额单位为元，精确到分，如：1200.00，359.14。

- 日期为定长 8 位的字符串，格式为 YYYYMMDD ，如 20140802。

订单类接口规范
~~~~~~~~~~~~~~

通过商户号、订单号和订单日期来标识订单的唯一性。

重复订单规范
~~~~~~~~~~~~

由于网络的不稳定性等原因，短期内相同订单的交易应答返回给商户订单系统时，有可能会出现以下两种情况：

- 先完成的订单后送达商户

- 对于同一笔订单收到两次交易结果

为此，账管家系统处理原则如下：
  
1.只要商户收到订单交易成功的应答，再次收到订单交易失败的应答，通常情况下，商户的订单系统也不会对此订单做任何处理。即保持该订单成功状态；T+1 取现接口，会以 T+1 日银行端最终返回结果为准返回给商户订单系统，需要商户订单系统根据交易结果更新订单状态。

2.商户的订单系统对于某笔订单已经收到成功应答，有可能后续再次收到该笔订单的成功应答，此时商户只需要回应本平台收到成功即可。

接口调用规范
~~~~~~~~~~~~


- 请求参数规范
 | 数据提交使用 POST 格式

- 接口调用方式

 | 账管家接口有两种调用方式：

 | 1) 页面调用方式
 
 |    商户以构造 FORM 表单的方式，通过用户的浏览器重定向到本平台接口，本平台完成交易后，将交易结果回送给商户订单系统，如企业用户开户采用这种方式。

 | 2) 后台调用方式
 
 |    即后台 HttpPost 请求方式，商户后台构造 HttpPost 请求，调用本平台接口。本平台完成交易后，将交易结果回送给商户订单系统，如个人用户开户采用这种方式。

- 调用接口过程
    
 | 说明：为保证接口的安全性，各接口所列有的请求参数和返回参数如无个别说明，以下数据体都需要参与签名：

 | 1) 按照接口的参数列表

 | 2) 按参数的值（非参数名）

 | 3) 按从上到下的顺序进行字符串相加所得

 | 4) 如参数为可选项并且为空，则该参数值不参与签名

- 举例说明
 | 将请求参数按顺序拼接成字符串
 | 假设有如下一组数据：
 | version = 10
 | cmd\_id = 101
 | mer\_cust\_id = 6000123456
 | user\_name = 张三
 | bg\_ret\_url = \ http://mertest.chinapnr.com/asharp
 |
 | 按 version+cmd\_id+mer\_cust\_id+bg\_ret\_url 的顺序拼接后的字符串结果为：
 | ``101016000123456http://mertest.chinapnr.com/asharp``
 |
 | 第一步：将调用签名函数生成check\_value 使用第一步拼接的字符串 ``101016000123456http://mertest.chinapnr.com/asharp`` 进行 MD5 加密后，与加密服务器通信，生成check\_value。
 | 假设获得的签名的值为：

.. code:: java

  A170E66B00D344F8CEA68C3A84F0ED2207805147793F806CBD3D3E166B57F511ABEB7D5D7A725ECEFDC64
  0FDC2F7102CD8D470CB0BE18A3B4ADE870689D7FCBD4CA55DD5C2E1D6BFC3F30514B0813D8E680708B44A1C
  1637780CA0D998EF22C10B7E4B8954F304F226BB50F091A60C939F7C4DB513261FC47667757550C7911E
..

 | 第二步：将请求参数和 check\_value 以 POST 方式发送
 | 获得签名后，将参数中包含中文和 URL 的字段 user\_name 和 bg\_ret\_url 使用 UTF-8 字符集 URLEncode 后，将所有数据，以 POST 方式发送给本平台，即完成了一次接口请求。

接口应答接收规范
~~~~~~~~~~~~~~~~

1. 验证规范

- 商户收到接口应答后，要进行验证签名的处理，以验证数据的合法性。

  | 验证过程如下：
  | 1.1 将指定的返回参数按顺序拼接成字符串
  | 2.1调用验证签名函数验证 check\_value

2. 接口应答方式

  | 交易应答通过同步和异步两种方式应答给商户。
  |
  | 1.1 同步应答：

    | 对应不同的两种调用方式，同步应答有两种形式：
	
    | 1.1.1同步页面应答方式
    
      | 需要商户提供页面应答地址，本平台的交易应答数据以表单形式 POST 方式提交至商户页面应答地址；
      | 
      | 商户如未提供页面返回地址，本平台会将交易结果以 HTML 页面格式应答至用户浏览器。如企业用户开户采用这种方式。
	  
    | 1.2.1 同步后台应答方式
	
      | 不需要商户提供应答地址，本平台会将交易应答参数以 JSON 格式通过 HttpResponse 方式应答商户请求。如个人用户开户采用这种方式。
	  
  | 2.1 异步应答：
  
    | 必须商户提供后台应答地址，本平台的交易应答数据以表单形式 POST 方式提交至商户后台应答地址。
	
    | 2.1.1 URL 应使用 UTF-8 字符集 URLEncode 编码后传入
	
    | 2.2.2 URL 中请不要包含特殊字符
	
    | 2.3.3 必须是外网地址

3. 对异步返回方式的应答规则
    
   - 为了表示商户订单系统已经收到交易应答，商户必须在对异步返回应答时输出一段特殊的字符串，组成规则为：固定字符串 RECV\_ORD\_ID\_ 加上交易应答中某一指定字段，一般为该交易的订单号 order\_id。
    
   - 有些接口没有商户订单号，请查看具体的接口说明，说明中会指定，如：个人用户开户接口的指定字段为 order\_id。
    
     例如：商户收到一笔订单号为 990000034 的异步返回的交易应答，则应在响应时输出 RECV\_ORD\_ID\_990000034 的字符串。本平台将搜索商户交易接收页面的前 1024 字节，只有搜索到该字符串，才能确认商户已经收到该笔订单的交易返回应答，否则，本平台认为商户未收到该笔订单的交易应答。
   |
4. 举例说明（以余额查询接口返回的数据为例）：

- 第一步：将指定的返回参数按顺序拼接成字符串

 | 假设返回数据如下：
   
.. code:: json

     {"cmd_id":"302"，"resp_code":"302000"，"resp_desc":""交易成功"，"mer_cust_id":"6000123456","user_cust_id":"6000123455","balance":"5.00","cash_balance":"5.00","acct_balance":"10.00","freeze_balance":"5.00"，"bg_ret_url"："http%3A%2F%2Fmertest.chinapnr.com%2Fasharp","check_value":"B170E66B00D344F8CEA68C3A84F0ED2207805147793F806CBD3D3E166B57F511ABEB7D5D7A725ECEFDC640FDC2F7102CD8D470CB0BE18A3B4ADE870689D7FCBD4CA55DD5C2E1D6BFC3F30514B0813D8E680708B44A1C1637780CA0D998EF22C10B7E4B8954F304F226BB50F091A60C939F7C4DB513261FC47667757550C7911E"}

..

 | 首先将参数中的中文和URL解码：
 | bg_ret_url= http://mertest.chinapnr.com/asharp
 | 按 cmd_id+resp_code+mer_cust_id+user_cust_id+balance+cash_balance+acct_balance+freeze_balance
 +bg_ret_url 的顺序拼接后的结果为：302302000600012345660001234555.005.0010.005.00http://mertest.chinapnr.com/asharp

- 第二步：调用验证签名函数验证 check\_value

 | 将第一步拼接的字符串：
 | 302302000600012345660001234555.005.0010.005.00http://mertest.chinapnr.com/asharp
 | 进行MD5加密后，和接口返回的 check\_value 传入验证签名函数进行验证。

5. 重复订单处理

- 商户收到的应答无论时间先后，还是通过同步或者异步的方式，都应被等同处理。商户有可能收到同一笔订单的多次交易应答，后续的处理步骤列示如下：

+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 商户网站订单状态   | 从本平台接收到应答的订单状态   | 商户网站的交易应答接收程序应采取的处理步骤                            |
+====================+================================+=======================================================================+
| 失败               | 失败                           | 无需修改商户订单系统数据库；提示持卡人交易失败                        |
+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 成功               | 成功                           | 无需修改商户订单系统数据库；提示持卡人交易成功                        |
+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 失败               | 成功                           | 需要修改商户订单系统数据库；提示持卡人交易成功                        |
+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 已受理             | 成功                           | 需要修改商户订单系统数据库；提示持卡人交易成功                        |
+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 已受理             | 失败                           | 需要修改商户订单系统数据库；提示持卡人交易失败                        |
+--------------------+--------------------------------+-----------------------------------------------------------------------+
| 成功               | 失败                           | T+1 取现特殊场景，需要修改商户订单系统数据库；提示持卡人订单交易失败  |
+--------------------+--------------------------------+-----------------------------------------------------------------------+

接口类型
~~~~~~~~

根据接口应答时交易状态的不同，将接口归类为以下类型：

+-------------------+----------------------------------------------------------------------------------+
| 接口类            | 同步异步应答返回描述                                                             |
+===================+==================================================================================+
| 同步接口          | 同步应答的交易状态为终态，无异步应答                                             |
+-------------------+----------------------------------------------------------------------------------+
| 同步+异步接口     | 同步应答的交易状态为终态，异步应答的交易状态与同步应答一致                       |
+-------------------+----------------------------------------------------------------------------------+
| 异步接口          | 同步应答的交易状态，正常时为中间态，异常时为终态；异步应答的交易状态皆为终态     |
+-------------------+----------------------------------------------------------------------------------+

.. _前台快捷绑卡接口: user.html#id16

.. _充值支付接口: business.html#id2

.. _交易状态查询接口: query.html#id8

.. _充值支付对账接口: query.html#id14

.. image:: _static/images/asharp_quick_pay.png