业务和技术接口规范

API 文档简介

  • asharp 采用了 HTTP 协议提供各类接口，并且所有接口都是统一请求地址，方便商户简单、快速接入。本 API 包含两类接口，页面浏览器类和系统调用类。
  • 页面浏览器类：需要从前端页面以 FORM 表单的形式发起请求，浏览器会自动跳转至汇付的相关页面（一般是快捷短信发送页面），用户在该页面完成相关业务操作后再回跳到商户指定页面，页面方式返回的是标准的表单格式。
  • 系统调用类：直接从服务端发起 HTTP 请求，API 会同步返回请求结果，返回的数据格式都是规范 JSON 格式。

接入指南

  • 第一步：商户申请

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

  • 第二部：公私钥使用

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

  • 第三步：调用接口

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

接口请求地址

生产请求 URL https://apptrade.cloudpnr.com/api/asharpMerchantRequest
联调请求 URL https://apptrade.testpnr.com/api/asharpMerchantRequest

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

快速接入快捷支付

本 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。
假设获得的签名的值为：
A170E66B00D344F8CEA68C3A84F0ED2207805147793F806CBD3D3E166B57F511ABEB7D5D7A725ECEFDC64
0FDC2F7102CD8D470CB0BE18A3B4ADE870689D7FCBD4CA55DD5C2E1D6BFC3F30514B0813D8E680708B44A1C
1637780CA0D998EF22C10B7E4B8954F304F226BB50F091A60C939F7C4DB513261FC47667757550C7911E
第二步：将请求参数和 check_value 以 POST 方式发送
获得签名后，将参数中包含中文和 URL 的字段 user_name 和 bg_ret_url 使用 UTF-8 字符集 URLEncode 后，将所有数据，以 POST 方式发送给本平台，即完成了一次接口请求。

接口应答接收规范

  1. 验证规范

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

    验证过程如下：
    1.1 将指定的返回参数按顺序拼接成字符串
    2.1调用验证签名函数验证 check_value
  1. 接口应答方式
交易应答通过同步和异步两种方式应答给商户。

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 必须是外网地址

  1. 对异步返回方式的应答规则

    • 为了表示商户订单系统已经收到交易应答，商户必须在对异步返回应答时输出一段特殊的字符串，组成规则为：固定字符串 RECV_ORD_ID_ 加上交易应答中某一指定字段，一般为该交易的订单号 order_id。

    • 有些接口没有商户订单号，请查看具体的接口说明，说明中会指定，如：个人用户开户接口的指定字段为 order_id。

      例如：商户收到一笔订单号为 990000034 的异步返回的交易应答，则应在响应时输出 RECV_ORD_ID_990000034 的字符串。本平台将搜索商户交易接收页面的前 1024 字节，只有搜索到该字符串，才能确认商户已经收到该笔订单的交易返回应答，否则，本平台认为商户未收到该笔订单的交易应答。


  2. 举例说明（以余额查询接口返回的数据为例）：

  • 第一步：将指定的返回参数按顺序拼接成字符串
假设返回数据如下：
{"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 传入验证签名函数进行验证。
  1. 重复订单处理
  • 商户收到的应答无论时间先后，还是通过同步或者异步的方式，都应被等同处理。商户有可能收到同一笔订单的多次交易应答，后续的处理步骤列示如下：
商户网站订单状态 从本平台接收到应答的订单状态 商户网站的交易应答接收程序应采取的处理步骤
失败 失败 无需修改商户订单系统数据库；提示持卡人交易失败
成功 成功 无需修改商户订单系统数据库；提示持卡人交易成功
失败 成功 需要修改商户订单系统数据库；提示持卡人交易成功
已受理 成功 需要修改商户订单系统数据库；提示持卡人交易成功
已受理 失败 需要修改商户订单系统数据库；提示持卡人交易失败
成功 失败 T+1 取现特殊场景，需要修改商户订单系统数据库；提示持卡人订单交易失败

接口类型

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

接口类 同步异步应答返回描述
同步接口 同步应答的交易状态为终态，无异步应答
同步+异步接口 同步应答的交易状态为终态，异步应答的交易状态与同步应答一致
异步接口 同步应答的交易状态，正常时为中间态，异常时为终态；异步应答的交易状态皆为终态
_static/images/asharp_quick_pay.png