AllPay_Integration_Specification_CH.md 39 KB

AllPay在线支付接入规范文档V5.0.0

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

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

1.概述

AllPay 为客户提供统一的API接入,以帮助客户实 现快速、安全、集中式的接入支付渠道。

2.交易流程

image

3.验签说明

1.对于发送到 AllPay 系统的 POST 请求报文,其中所有传入参数(除 signature 参数外)按照字段名的 ASCII 码从小到大排序后(字典序),使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 String1。

2.在 String1 最后直接拼接(不需要用“&”连接)双方约定的签名密钥 Key(接入 AllPay 时分配),得到 stringSignTemp 字符串,并对 stringSignTemp 进行加密运算,得到 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=VER0000000052f2c77e3718c47cfb47a89a6fbc9d361

4.通用API说明

商户服务器和 AllPay 网关对接的通用接口,每个渠道都具有的功能,包括:消费,消费查询,退款,退款查询。

4.1 通用 API 接入地址

交易名称 测试地址 生产地址
消费 https://testapi.allpayx.com/api/unifiedorder https://api.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://api.allpayx.com/api/refundquery
预授权 https://testapi.allpayx.com/api/unifiedorder https://api.allpayx.com/api/unifiedorder
预授权完成 https://testapi.allpayx.com/api/pauc https://api.allpayx.com/api/pauc
撤销接口 https://testapi.allpayx.com/api/canc https://api.allpayx.com/api/canc

4.2 消费交易接口

1.接口说明

该接口为接入商家提供消费购买的功能。

2.请求报文格式

下面列举的字段为通用字段,每个渠道都需要上送,部分渠道有专属字段,具体请到第5章渠道专属配置处查看。消费接口分为跳转型和参数返回型,默认为跳转型,参数返回型会在第5章(渠道专属配置)里面说明。

参数 类型 属性 描述
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"}],需对该字段进行base-64编码后签名上送。
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
merReserve String(1024) O 商户预留内容,可传任意内容,如购买商品信息、员号等,但不要传特殊符号,如逗号等。
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.跳转型消费接口响应报文

商户需要提供一个 http/https 协议的接口,包含在参数里传递给AllPay,即 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 时间
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
merReserve String(1024) O 商户预留内容,可传任意内容,如购买商品信息、员号等,但不要传特殊符号,如逗号。
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.3 消费查询交易接口

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(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文格式

参数 类型 属性 描述
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或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.4 退款交易接口

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 分配
paymentSchema String(10) M 渠道代码:点击这里
acqID String(11) M 收单行 ID "99020344"
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
signType String(3) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
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"
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(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.5 退款查询交易接口

1.接口说明

该接口为接入商家提供退款查询的功能。

2.请求报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
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(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
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(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.6 外卡预授权接口

1.接口说明

该接口为接入商家提供预授权功能。

2.请求报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
charSet String(6) M 统一填写为“UTF-8”
transType String(4) M 预授权填写“PAUT”
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 渠道代码:FC
goodsInfo String(60) M 商品信息,在支付页面上显示。
detailInfo String(400) M 商品明细。格式:[{"goods_name":"iPhone X","quantity":"2"},{"goods_name":"iPhone 8","quantity":"4"}],需对该字段进行base-64编码后签名上送。
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
merReserve String(1024) O 商户预留内容,可传任意内容,如购买商品信息、员号等,但不要传特殊符号,如逗号等。
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文

商户需要提供一个 http/https 协议的接口,包含在参数里传递给AllPay,即 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 预授权填写“PAUT”
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 渠道代码:FC
RespCode String(2) M 应答码 00-成功
RespMsg String(20) M 应答消息
transID String(32) M GW 系统生成的交易 ID,每笔交易保持唯一
GWTime String(14) M yyyyMMddHHmmss,为 GW 时间
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
merReserve String(1024) O 商户预留内容,可传任意内容,如购买商品信息、员号等,但不要传特殊符号,如逗号。
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.6 外卡预授权完成接口

1.接口说明

该接口为接入商家提供预授权完成功能。

2.请求报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
charSet String(6) M 统一填写为“UTF-8”
transType String(4) M 预授权填写“PAUC”
orderNum String(60) M 订单号:商户自行定义,需保证同一商户号下订单号不能重复
origOrderNum 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 渠道代码:FC
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
charSet String(6) M 统一填写为“UTF-8”
transType String(4) M 查询填写“PAUC”
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 渠道代码:FC
RespCode String(2) M 应答码 00-成功
RespMsg String(20) M 应答消息
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
GWTime String(14) M YYYYMMDDHHMMSS,为 GW 时间,目前为本地交易时间
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

4.7 撤销接口

1.接口说明

该接口为接入商家提供对外卡 消费、预授权、预授权完成的撤销。

2.请求报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
charSet String(6) M 统一填写为“UTF-8”
transType String(4) M 填写“VOID”
orderNum String(60) M 订单号:商户自行定义,需保证同一商户号下订单号不能重复
origOrderNum String(60) M 订单号:要撤销的订单号, 可以为消费、预授权、预授权完成的orderNum
merID String(15) M 商户 ID,由 AllPay 分配
acqID String(11) M 收单行 ID "99020344"
paymentSchema String(10) M 渠道代码:FC
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

3.响应报文格式

参数 类型 属性 描述
version String(12) M 统一填写为“VER000000005”
charSet String(6) M 统一填写为“UTF-8”
transType String(4) M 查询填写“VOID”
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 渠道代码:FC
RespCode String(2) M 应答码 00-成功
RespMsg String(20) M 应答消息
transTime String(14) M 交易时间,格式:"yyyyMMddHHmmss"
GWTime String(14) M YYYYMMDDHHMMSS,为 GW 时间,目前为本地交易时间
signType String(10) M MD5或SHA256
signature String(32) M 采用 MD5或SHA256 签名

5.渠道专属配置

5.1 WX渠道

5.1.1 二维码无跳转模式

该模式返回生成二维码的字符串,商户需要自己生成二维码。

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "QRCODE"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
code_url String O 二维码字符串。应答码为00返回该字段

5.1.2 二维码跳转模式

该模式会为商户跳转到AllPay生成好的二维码页面,无需商户自己生成。

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "QUICK"

5.1.3 公众号支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "JSAPI"

5.1.4 小程序支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APPLET"
openid String M 微信openid

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
sdk_params String O 小程序支付所需参数(JSON字符串)。应答码为00返回该字段

将上述返回数据放入微信小程序支付接口,即可调起微信小程序支付,具体方法,参考微信小程序api

5.1.5 APP支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APP"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
tn String O 交易流水号,RespCode为“00”时返回,作为调起 sdk 支付的参数

获取到tn后,根据本文档第7节调用SDK进行支付。

5.2 AP渠道

5.2.1 WebSite支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "WEB"

5.2.2 H5支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "JSAPI"

5.2.3 APP支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APP"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
tn String O 交易流水号,RespCode为“00”时返回,作为调起 sdk 支付的参数

获取到tn后,根据本文档第7节调用SDK进行支付。

5.2.4 二维码无跳转模式

该模式返回生成二维码的字符串,商户需要自己生成二维码。

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "QRCODE"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
code_url String O 二维码字符串。应答码为00返回该字段

5.3 UP渠道

5.3.1 H5支付,自适应PC和移动端

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "H5"

5.3.2 APP支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APP"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
tn String O 交易流水号,RespCode为“00”时返回,作为调起 sdk 支付的参数

获取到tn后,根据本文档第7节调用SDK进行支付。

测试卡:

Credit Card: 5200831111111113
Mobile: 13552535506
CVN2: 123
Exp Date: month 11 year 19
SMS Code on PC: 111111
SMS Code on Mobile: 123456

Credit Card: 6226388000000095
Mobile: 18100000000
CVN2: 248
Exp Date: month 12 year 19
SMS Code on PC: 111111
SMS Code on Mobile: 123456

5.4 Apple Pay渠道

5.4.1 APP支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APP"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
tn String O 交易流水号,RespCode为“00”时返回,作为调起 sdk 支付的参数

获取到tn后,根据本文档第7节调用SDK进行支付。

5.5 CA渠道

5.5.1 APP支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "APP"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
tn String O 交易流水号,RespCode为“00”时返回,作为调起 sdk 支付的参数

获取到tn后,根据Android对接文档调用SDK进行支付

5.6 MIPAY渠道

5.6.1 H5支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "H5"
firstname String M This is name of the customer who is doing the transaction.
email String M this is email id of the customer who is doing transaction
phone String M Phone number of the customer
customerId String O Customer ID, when client register on merchant, merchant distribute it to client.
测试环境配置:

修改测试机器hosts,添加如下两条信息
114.80.87.249 account.preview.n.xiaomi.net
114.80.87.249 api.account.preview.n.xiaomi.net

测试卡:

卡号:5123456789012346
有效期:0520
cvv:123

5.7 EB渠道

5.7.1 H5支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "H5"
firstname String M This is name of the customer who is doing the transaction.
email String M this is email id of the customer who is doing transaction
phone String M Phone number of the customer

5.8 PF渠道

5.8.1 H5支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "H5"
email String M 用户email
transport_express String M 快递单号

=======

5.9 APHK渠道

5.9.1 H5支付

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "JSAPI"

5.9.2 二维码无跳转模式

该模式返回生成二维码的字符串,商户需要自己生成二维码。

消费接口专属字段

参数 类型 属性 描述
tradeFrom String M "QRCODE"

应答报文:

参数 类型 属性 描述
RespCode String M 应答码 00-成功
RespMsg String M 应答消息
code_url String O 二维码字符串。应答码为00返回该字段

5.10 FC渠道

5.10.1 消费, 预授权

消费,预授权 ,接口专属字段

参数 类型 属性 描述
tradeFrom String M "H5"

6.应答码

应答码 描 述
00 成功
01 失败
04 处理中
61 超过限额
U1 商户号不存在
U2 签名错误
U3 报文被篡改
U4 缺失参数
U5 无效的参数
U6 重复的订单号
U7 订单不存在
U8 参数为空
U9 系统错误
P1 渠道未配置
P2 币种未配置
P3 余额不足
P4 功能不支持
P5 渠道返回错误

7.APP模式对接文档

Android对接文档:点击这里

iOS对接文档:点击这里

8.技术支持

如果您在调试时遇到问题,请与我们联系:support@allpayx.com