Android端控件支付产品接口规范文档.md 20 KB

#Android端控件支付产品接口规范文档5.0.0

上海偶可贝网络科技有限公司

  • 版本信息:中文 V5.0.0
  • 更新时间:2018 年12 月

1.概述

AllPay 为基于移动端 APP 支付的客户提供接入插件(下文简称“SDK”),以帮助客户实 现快速、安全、集中式的接入支付渠道。

2.交易流程

image

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 渠道代码:点击查看详情
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 渠道代码:点击这里
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. 接入说明

启动支付控件的接口,接口定义如下:

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文件中添加
repositories {
    flatDir {
        dirs project(':allpaysdk').file('libs')
    }
}
4.3.3. 调用支付控件

接着可以通过以下方式调用支付控件:

/**
 * tn——交易流水号,即 TN,为商户后台从 AllPay 后台获取,获取方式参见 AllPay 网关对接文档
 * false 测试环境
 */
AllPayEngine.Pay(ShopCartActivity.this, tn, false);
4.3.4. 同步结果通知

支付完成后,获取支付控件支付结果,并添加相应处理逻辑,只需实现调用 Activity 中的 onActivityResult()方法即可,实例代码如下:

@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 字符串,格式如下:

{
    "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 渠道代码:点击这里
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 渠道代码:点击这里
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 渠道代码:点击这里
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 渠道代码:点击这里
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。