#Android端控件支付产品接口规范文档5.0.0 [上海偶可贝网络科技有限公司](https://www.allpayx.com) * 版本信息：中文 V5.0.0 * 更新时间：2018 年12 月 #### 1.概述 AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”)，以帮助客户实 现快速、安全、集中式的接入支付渠道。 #### 2.交易流程 ![image](https://git.allpayx.com/OpenAPI/b2c/raw/master/images/moble_sdk_flowsheet.png) #### 3. 验签说明 ``` 1.对于发送到 ALLPAY 系统的 POST 请求报文，其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序)，使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。 2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 K1(接入时 ALLPAY 时分配)，得到 stringSignTemp 字符串,并对 stringSignTemp 进行 md5 运算，得到 signature 的值。 3.示例签名串 acqID=99020344&backURL=https://baidu.com&charSet=UTF-8&detailInfo=W3siZ29vZHNfbmFtZSI6IuWNjuS4ulAyMCIsInF1YW50aXR5IjoiMiJ9LHsiZ29vZHNfbmFtZSI6IuWNjuS4ulAyMCBwbHVzIiwicXVhbnRpdHkiOiI0In1d&frontURL=https://mchapi.allpayx.com/demo&goodsInfo=华为P20&merID=000000000000015&merReserve=你好&orderAmount=1&orderCurrency=HKD&orderNum=dKmdb4S9Tv1a9ZpkMjeDawV82MCJ&paymentSchema=AP&signType=MD5&transTime=20181206134515&transType=PURC&version=VER0000000022f2c77e3718c47cfb47a89a6fbc9d361 ``` #### 4.通用API说明 商户服务器和 AllPay 网关对接的通用接口,每个渠道都具有的功能,包括:消费,查询，退款,退款查询接口。 ##### 4.1. 通用API 接入地址 | 交易名称 | 开发调试地址 | 生产交易地址 | | ------------ | -------------------------------------------- | -------------------------------------------- | | 统一下单接口 | https://testapi.allpayx.com/api/unifiedorder | https://testapi.allpayx.com/api/unifiedorder | | 查询接口 | https://testapi.allpayx.com/api/orderquery | https://api.allpayx.com/api/orderquery | | 退款接口 | https://testapi.allpayx.com/api/refund | https://api.allpayx.com/api/refund | | 退款查询 | https://testapi.allpayx.com/api/refundquery | https://testapi.allpayx.com/api/refundquery | ##### 4.2. 消费交易接口 1.接口说明 商户网关将订单信息发送给 ALLPAY 网关，由 ALLPAY 网关进行处理后将交易流水 号，即 tn，返回给商户网关,tn 作为调起手机 app 支付控件的参数。 2.请求报文格式 下面列举的字段为通用字段，每个渠道都需要上送，部分渠道有渠道专属字段，具体字段请到该渠道的专属渠到字段说明处查看 | 参数 | 类型 | 属性 | 描述 | | ------------- | ------------ | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000005” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 消费交易填写“PURC” | | orderNum | String(60) | M | 订单号：商户自行定义，需保证同一商户号下订单号不能重复 | | orderAmount | String(12) | M | 订单金额：如 100 元，表示为 100 或 100.00 | | orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" | | frontURL | String(400) | M | 支付完成后跳转到该地址 | | backURL | String(400) | M | 支付结果异步通知到该地址 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击查看详情](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | goodsInfo | String(60) | M | 商品信息,在支付页面上显示 | | detailInfo | String(400) | M | 商品明细 格式： [{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}]，需对该字段base64后签名上送 | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 | | signType | String(3) | M | MD5或SH256 | | signature | String(32) | M | 采用 MD5或SH256 签名 | 3.响应报文格式 | 参数 | 类型 | 属性 | 描述 | | -------- | ----------- | ---- | -------------------------------------------------------- | | RespCode | String(2) | M | 应答码 00-成功 | | RespMsg | String(100) | M | 应答消息 | | tn | String(32) | O | 交易流水号，RespCode为“00”时返回,作为调起 sdk 支付的参数 | 4.商户需要提供一个 http/https 协议的接口，包含在参数里传递给 SDK，即 backURL。AllPay 服务器在支付完成后，会以 Post 方式调用 backURL，通知支付结果。商户在接收到通知后，需返回“ok”, 如果没有收到商户返回“OK”,AllPay将会过一段时间后重新推送。时间间隔为[15, 15, 30, 180, 1800, 3600, 7200, 14400, 14400]单位为秒。 参数如下表: | 参数 | 类型 | 属性 | 描述 | | ------------- | ------------ | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000005” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 消费交易填写“PURC” | | orderNum | String(60) | M | 订单号 | | orderAmount | String(12) | M | 订单金额：如 100 元，表示为 100 或 100.00 | | orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | RespCode | String(2) | M | 应答码 00-成功 | | RespMsg | String(20) | M | 应答消息，全部为英文字符 | | transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 | | GWTime | String(14) | M | yyyyMMddHHmmss，为 GW 时间 | | merReserve | String(1024) | M | 商户预留内容，可传任意内容，如购买商品信息、员号等，但不要传特殊符号，如逗号。 | | signType | String(3) | M | MD5或SH256 | | signature | String(32) | M | 采用 MD5或SH256 签名 | ##### 4.3. Android 客户端接入步骤 ##### 4.3.1. 接入说明 启动支付控件的接口，接口定义如下: ```java public static void pay(Activity activity,String tn,boolean mode) ``` ::: tip 参数说明 activity —— 用于启动支付控件的活动对象 tn —— 订单信息为交易流水号，即 TN，为商户后台从 AllPay 后台获取 mode —— AllPay 后台环境标识，true 将在 AllPay 正式环境发起交易,false 将在 AllPay 测试环 境发起交易 ::: ##### 4.3.2. 添加 SDK 包 1. 把allpaysdk当做Module导入到自己的工程 2. 在Application Module的build.gradle文件的dependencies下添加compile project(':allpaysdk') 3. 在Application Module的build.gradle文件中添加 ```java repositories { flatDir { dirs project(':allpaysdk').file('libs') } } ``` ##### 4.3.3. 调用支付控件 接着可以通过以下方式调用支付控件: ```java /** * tn——交易流水号，即 TN，为商户后台从 AllPay 后台获取,获取方式参见 AllPay 网关对接文档 * false 测试环境 */ AllPayEngine.Pay(ShopCartActivity.this, tn, false); ``` ##### 4.3.4. 同步结果通知 支付完成后，获取支付控件支付结果，并添加相应处理逻辑，只需实现调用 Activity 中的 onActivityResult()方法即可,实例代码如下: ```java @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (data == null) { return; } if (requestCode == AllPayConst.VTPAY_PAY_REQUESR_CODE&& resultCode == AllPayConst.VTPAY_PAY_RESULT_CODE) { String result = data.getExtras().getString("pay_result"); } } ``` pay_result,为 json 字符串,格式如下: ```text { "state": "cancel", "paymentSchema": "UP", "orderNum": "604337497032", "errorDetail": "user cancel operation " } ``` 报文说明: - state: "success"代表成功, "cancel"代表用户取消操作,"fail"代表失败,"query"代表 app 需要调用查询接口来确认订单状态 - paymentSchema: 支付渠道, "APMP"代表支付宝, "WX"代表微信 - orderNum: 订单号 - errorDetail: 错误详情 ##### 4.4. 查询交易接口 1. 接口说明 该接口为接入商家提供交易查询的功能。 2 .请求报文格式 | 参数 | 类型 | 属性 | 描述 | | ------------- | ---------- | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000005” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 查询填写“INQY” | | orderNum | String(60) | M | 订单号 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | signType | String(3) | M | MD5 | | signature | String(32) | M | 采用 MD5 签名 | 1. 响应报文格式 | 参数 | 类型 | 属性 | 描述 | | ------------- | ---------- | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000005” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 查询填写“INQY” | | orderNum | String(60) | M | 订单号 | | transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | RespCode | String(2) | M | 应答码 00-成功 | | RespMsg | String(20) | M | 应答消息，全部为英文字符 | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 | | signType | String(3) | M | MD5 | | signature | String(32) | M | signature | ##### 4.5 退款交易接口 1.接口功能说明 该接口为接入商家提供交易退款的功能。 2.请求报文格式 | 参数 | 类型 | 属性 | 描述 | | ------------- | ---------- | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000005” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 退款填写“REFD” | | orderNum | String(60) | M | 退款订单号:商户自行定义，需保证同一商户号下退款订单号不能重复 | | origOrderNum | String(60) | M | 原交易订单号 | | returnAmount | String(12) | M | 退款金额：如 100 元，表示为 100 或 100.00 | | orderCurrency | String(3) | M | 订单币种：ISO标准 如：人民币填写“CNY”,美元填写"USD" | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | signType | String(3) | M | MD5 | | signature | String(32) | M | 采用 MD5 签名 | 3.响应报文格式 | 参数 | 类型 | 属性 | 描述 | | --------- | ---------- | ---- | ---------------------------------------------- | | version | String(12) | M | 统一填写为“VER000000002” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 退款填写“REFD” | | orderNum | String(60) | M | 退款订单号 | | transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | RespCode | String(2) | M | 应答码 00-成功 | | RespMsg | String(20) | M | 应答消息，全部为英文字符 | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 | | signType | String(3) | M | MD5 | | signature | String(32) | M | signature | ##### 4.6. 退款查询接口 1.接口说明 该接口为接入商家提供退款查询的功能。 2.请求报文格式 | 参数 | 类型 | 属性 | 描述 | | ------------- | ---------- | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000002” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 查询填写“RFQY” | | orderNum | String(60) | M | 退款订单号 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | signType | String(3) | M | MD5 | | signature | String(32) | M | 采用 MD5 签名 | 1. 响应报文格式 | 参数 | 类型 | 属性 | 描述 | | ------------- | ---------- | ---- | ------------------------------------------------------------ | | version | String(12) | M | 统一填写为“VER000000002” | | charSet | String(6) | M | 统一填写为“UTF-8” | | transType | String(4) | M | 查询填写“RFQY” | | orderNum | String(60) | M | 退款订单号 | | transID | String(32) | M | GW 系统生成的交易 ID，每笔交易保持唯一 | | merID | String(15) | M | 商户 ID，由AllPay 分配 | | acqID | String(11) | M | 收单行 ID "99020344" | | paymentSchema | String(10) | M | 渠道代码：[点击这里](https://git.allpayx.com/OpenAPI/b2c_pc_payment/src/master/paymentSchema.md) | | RespCode | String(2) | M | 应答码 00-成功 | | RespMsg | String(20) | M | 应答消息，全部为英文字符 | | transTime | String(14) | M | 交易时间,格式:"yyyyMMddHHmmss" | | GWTime | String(14) | M | YYYYMMDDHHMMSS，为 GW 时间，目前为本地交易时间 | | signType | String(3) | M | MD5 | | signature | String(32) | M | signature | #### 5.渠道专属配置 ##### 5.1 CA渠道 消费接口专属字段 | 字段名 | 变量名 | 必填 | 类型 | 描述 | | -------- | --------- | ---- | ---------- | --------- | | 交易场景 | tradeFrom | M | String(12) | "android" | #### 6.应答码 | 应答码 | 描 述 | | ------ | ------------ | | 00 | 成功 | | 01 | 失败 | | 04 | 处理中 | | 61 | 超过限额 | | U1 | 商户号不存在 | | U2 | 签名错误 | | U3 | 报文被篡改 | | U4 | 缺失参数 | | U5 | 无效的参数 | | U6 | 重复的订单号 | | U7 | 订单不存在 | | U8 | 参数不能为空 | | U9 | 系统错误 | | P1 | 渠道未配置 | | P2 | 币种未配置 | | P3 | 余额不足 | | P4 | 功能不支持 | ### #### 7.技术支持 如果您在调试时遇到问题，请我们联系:support@allpayx.com。