AllPay在线支付接入规范文档.md 23 KB
AllPay在线支付接入规范文档5.0.0
- 版本信息：中文 V5.0.0
- 更新时间：2019 年1 月
1.概述
AllPay 为客户提供统一的API接入，以帮助客户实 现快速、安全、集中式的接入支付渠道。
2.交易流程
3.验签说明
1.对于发送到 AllPay 系统的 POST 请求报文，其中所有传入参数（除 signature 参数外）按照字段名的 ASCII 码从小到大排序后（字典序），使用 URL 键值对的格式（即 key1=value1&key2=value2...）拼接成字符串 String1。
2.在 String1 最后直接拼接（不需要用“&”连接）双方约定的签名密钥 Key（接入 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=VER0000000052f2c77e3718c47cfb47a89a6fbc9d361
4.通用API说明
商户服务器和 AllPay 网关对接的通用接口，每个渠道都具有的功能，包括：消费，消费查询，退款，退款查询。
4.1.通用API 接入地址
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 签名 |
5.渠道专属配置
5.1 WX渠道
1.二维码无跳转模式
该模式返回生成二维码的字符串，商户需要自己生成二维码。
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "QRCODE" |
应答报文：
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| RespCode | String | M | 应答码 00-成功 |
| RespMsg | String | M | 应答消息 |
| code_url | String | O | 二维码字符串。应答码为00返回该字段 |
2.二维码跳转模式
该模式会为商户跳转到AllPay生成好的二维码页面，无需商户自己生成。
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "QUICK" |
3.公众号支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "JSAPI" |
4.小程序支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "APPLET" |
| openid | String | M | 微信openid |
应答报文：
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| RespCode | String | M | 应答码 00-成功 |
| RespMsg | String | M | 应答消息 |
| sdk_params | String | O | 小程序支付所需参数（JSON字符串）。应答码为00返回该字段 |
将上述返回数据放入微信小程序支付接口,即可调起微信小程序支付,具体方法,参考微信小程序api
5.APP支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "APP" |
应答报文：
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| RespCode | String | M | 应答码 00-成功 |
| RespMsg | String | M | 应答消息 |
| tn | String | O | 交易流水号，RespCode为“00”时返回，作为调起 sdk 支付的参数 |
5.2 AP渠道
1.WebSite支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "WEB" |
5.3 APMP渠道
1.H5支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "JSAPI" |
2.APP支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "APP" |
应答报文：
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| RespCode | String | M | 应答码 00-成功 |
| RespMsg | String | M | 应答消息 |
| tn | String | O | 交易流水号，RespCode为“00”时返回，作为调起 sdk 支付的参数 |
5.4 CA渠道
1.APP支付
消费接口专属字段
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| tradeFrom | String | M | "APP" |
应答报文：
| 参数 | 类型 | 属性 | 描述 |
|---|---|---|---|
| RespCode | String | M | 应答码 00-成功 |
| RespMsg | String | M | 应答消息 |
| tn | String | O | 交易流水号，RespCode为“00”时返回，作为调起 sdk 支付的参数 |
获取到tn后，根据安卓对接文档调用sdk进行支付
6.应答码
| 应答码 | 描 述 |
|---|---|
| 00 | 成功 |
| 01 | 失败 |
| 04 | 处理中 |
| 61 | 超过限额 |
| U1 | 商户号不存在 |
| U2 | 签名错误 |
| U3 | 报文被篡改 |
| U4 | 缺失参数 |
| U5 | 无效的参数 |
| U6 | 重复的订单号 |
| U7 | 订单不存在 |
| U8 | 参数为空 |
| U9 | 系统错误 |
| P1 | 渠道未配置 |
| P2 | 币种未配置 |
| P3 | 余额不足 |
| P4 | 功能不支持 |
| P5 | 渠道返回错误 |
7.SDK下载
安卓SDK对接文档地址：安卓SDK
iOS SDK对接文档地址：iOS SDK
8.技术支持
如果您在调试时遇到问题，请与我们联系：support@allpayx.com