收付通API

通联核心产品文档中心

2. 报文概述

目录

2. 报文概述

2.1. 选择报文

2.1.1 产品与报文的关系

商户需根据与通联合作的支付产品，选择对应的接入报文接口，以下是收付通四种支付产品：收款、付款、还款通、联贷通，需对接的报文接口建议，若商户有其它特殊要求，请与通联客户经理进一步沟通。( 如有需求在特定时间段发完交易，调用批量接口  )

产品-主交易

必须接入接口

可选接入接口

收款-协议支付

协议支付签约短信触（310001）

协议支付签约（310002）

协议支付解约（310003）

协议支付（310011）

签约结果查询（340009）

交易结果查询(200004)

SFTP对账文件推送，见章节4.1

1.退款(REFUND)(当商户有退款需求时接入)

2.解约通知(310005)(当商户需接收持卡人银行端发起的解约通知，来引导持卡人重新签约时接入)

3. 快捷单笔交易结果通知(对于掉单情况，如果商户希望通过查询+通知方式更快获取结果时接入)

收款-批量协议支付

协议支付签约短信触（310001）

协议支付签约（310002）

协议支付解约（310003）

批量协议支付（310016）

签约结果查询（340009）

交易结果查询(200004)

批量交易完成通知(200003)

SFTP对账文件推送，见章节4.1

1.退款(REFUND)(当商户有退款需求时接入)

2.解约通知(310005)(当商户需接收持卡人银行端发起的解约通知，来引导持卡人重新签约时接入)

 

付款-单笔实时代付

单笔实时代付(100014)

交易结果查询(200004)

SFTP对账文件推送

1.商户主动划款入账通知

2.代收付单笔成功交易结果通知

3.代收付单笔失败交易结果通知

付款-批量代付

批量代付(100002)

交易结果查询(200004)

批量交易完成通知(200003)

SFTP对账文件推送，见章节4.1

1.商户主动划款入账通知

还款通-实时还款

协议支付签约短信触（310001）

协议支付签约（310002）

签约结果查询（340009）

实时还款(100007)

交易结果查询(200004)

SFTP对账文件推送，见章节4.1

1.解约通知(310005)(当商户需接收持卡人银行端发起的解约通知，来引导持卡人重新签约时接入)

联贷通-联合付款

联合付款(100072)

交易结果查询(200004)

SFTP对账文件推送，见章节4.2

 

2.1.1 报文清单

报文组

交易类型

报文名称

报文方向

对账

协议支付报文组

310001

协议支付签约短信触发

商户→通联

×

310002

协议支付签约

商户→通联

×

310003

协议支付解约

商户→通联

×

310011

协议支付

商户→通联

√

310016

批量协议支付

商户→通联

√

340009

快捷协议查询

商户→通联

×

310010

协议支付签约合并支付

商户→通联

√

批量代收付报文组

100001

批量代收（特殊场景使用，请咨询通联客户经理）

商户→通联

√

100002

批量代付

商户→通联

√

单笔实时代收付报文组

100011

单笔实时代收（特殊场景使用，请咨询通联客户经理）

商户→通联

√

100014

单笔实时代付

商户→通联

√

还款报文组

100007

实时还款

商户→通联

×

200008

还款通结果查询

商户→通联

×

联贷通报文组

100072

联合付款

商户→通联

√

账务报文组

300000

账户信息查询

商户→通联

×

300001

历史余额查询

商户→通联

×

300002

汇款充值通知

商户→通联

×

300003

账户提现

商户→通联

×

300006

账户充值

商户→通联

×

100400

内部转账

商户→通联

×

100401

批量内部转账

商户→通联

×

通用报文组

310021

退款

商户→通联

√

200004

交易结果查询

商户→通联

×

 

简单对账文件下载

商户→通联

×

200009

对账文件下载

商户→通联

×

200007

卡bin查询

商户→通联

×

100055

电子回单异步下载接口

商户→通联

×

异步通知接口

 

退票通知

通联→商户

√

 

商户主动划款入账通知

通联→商户

×

 

快捷单笔交易结果通知

通联→商户

×

200003

批量交易完成通知

通联→商户

×

 

代收付单笔成功交易结果通知

通联→商户

×

 

代收付单笔失败交易结果通知

通联→商户

×

310005

解约通

通联→商户

×

110000

余额告警通知

通联→商户

×

商业委托签约报文组

 

340001

签约申请

商户→通联

×

340002

签约确认

商户→通联

×

340003

签约解除

商户→通联

×

340009

签约结果查询

商户→通联

×

 

签约结果通知

通联→商户

×

快捷一键绑卡签约报文组

310006

一键绑卡签约申请

商户→通联

×

 

签约回跳接口

通联→商户

×

310006

签约结果通知

通联→商户

×

2.2 通讯方式

2.2.1 公网通讯方式

HTTPS的POST方式，用TLS1.2方式。

2.2.2 专线通讯方式

HTTP的POST方式。

对应的测试环境出口ip和端口 192.168.91.18:8000，同时要提网络申请给数据中心。
 

2.2.3 生产环境接口地址

目标环境

接口地址

说明

接口生产环境URL

https://tlt.allinpay.com/aipg/ProcessServlet?MERCHANT_ID=?&REQ_SN=?

MERCHANT_ID与REQ_SN分别对应报文头中的商户号，请求流水号

2.2.3 对外出口IP

当对于来自通联端的请求，比如SFTP/FTP对账文件推送，或通知类报文，商户需要设置通联端服务器白名单，参考收付通如下生产出口IP。

生产环境 140.206.57.166 、117.184.121.6 、222.72.143.68 、222.72.143.69、140.206.57.164 、101.95.129.116、 117.184.121.4  、210.22.100.126 、220.248.8.94

2.3 报文格式说明

2.3.1字段类型

本技术规则在报文的“类型”列中使用的字段类型按如下的说明：

属性

说明

C(n)

业务要素的值可使用字母、中文等，长度固定为n

C(n,m)

业务要素的值可使用字母、中文等，最小长度为n、最大长度为m

N(n)

业务要素的值只能使用数字，长度固定为n

2.3.2 字段限制

本技术规则在报文的“限制”列中使用M、C的形式描述业务要素的传递条件：

属性

说明

M

必填

C

选填

2.3.3请求报文格式

AIPG(根节点)

INFO(报文头,报文头包含了签名标签SIGNED_MSG)

XXX(报文体，每种报文体都不一样,XXX的具体标签值需参考具体请求报文定义。)

请求报文头格式为：“<INFO>报文头内容 </INFO>”，内容如下所示。

接口

字段ID

字段解释

类型

取值

限制

备注

INFO

TRX_CODE

交易代码

C(6,10)

 

M

用于区分交易接口

VERSION

版本号

C(2)

05

M

 

DATA_TYPE

数据格式

C(1)

2

M

 

LEVEL

处理级别

N(1)

5

M

 

MERCHANT_ID

商户号

C(10,20)

 

M

 

USER_NAME

用户名

C(1,20)

 

M

 

REQ_SN

请求流水号

C(0,60)

 

M

全局唯一不能重复

2.3.4响应报文格式

AIPG(根节点)

INFO(报文头,报文头包含了签名标签SIGNED_MSG)

XXX(报文体，每种报文体都不一样,XXX的具体标签值需参考响应报文定义。)

响应报文头格式为：“<INFO>报文头内容</ INFO>”，内容如下所示。

接口

字段ID

字段解释

类型

取值

限制

备注

INFO

TRX_CODE

交易代码

C(6,10)

 

M

与 请求报文的交易类型一致

VERSION

版本号

C(2)

05

M

 

DATA_TYPE

数据格式

C(1)

2

M

 

REQ_SN

请求流水号

C(36,60)

 

M

 

RET_CODE

返回码

C(4)

 

M

 

RET_MSG

返回信息

C(1,128)

 

M

 

由于网络等不可预知原因，可能会出现响应报文的串改，对响应报文的解析处理，必须校验返回的请求流水号与请求报文的请求流水号一致。

2.3.5 编码格式

默认编码格式是GBK，如果需要UTF-8的，原接口地址要加上带参数encoding=UTF-8，签名和和发送都要改成UTF-8编码。

2.4 数字签名域

商户用私密钥对请求报文进行签名，用公钥对响应报文进行验签。

2.4.1 请求报文加签

签名算法支持：SHA1withRSA 、SM3withSM2(SM3withSM2算法方式，需设置http请求头字段 SIGN-ALG 为 1)，SHA1withRSA只考虑对存量商户的支持，新商户请务必用SM3withSM2。

签名内容产生规则为：用SHA1（或SM3）计算整个未签名报文哈希值，并将该哈希值用RSA（或SM2）用商户的私钥进行签名，将签名信息置于<SIGNED_MSG>节点中，最后将该节点附在报文头INFO。

如以下为未签名原报文，注意</REQ_SN>与</INFO>之间有一空行

<?xml version="1.0" encoding="GBK"?><AIPG>
<INFO>
<TRX_CODE>xxxxxx</TRX_CODE>
<VERSION>03</VERSION>
<DATA_TYPE>2</DATA_TYPE>
    <LEVEL>5</LEVEL>
<USER_NAME>xxxxxxxxxxxxxxxx</USER_NAME>
<USER_PASS>xxxxxx</USER_PASS>
<REQ_SN>xxxxxxxxxxxxxxxxxx</REQ_SN>
 
</INFO>
<VALIDR>
<MERCHANT_ID>xxxxxxxxxxxxxxx</MERCHANT_ID>
<SUBMIT_TIME>xxxxxxxxxxxxxx</SUBMIT_TIME>
<BANK_CODE>xxxx</BANK_CODE>
<ACCOUNT_NO>xxxxxxxxxxxxxxxx</ACCOUNT_NO>
<ACCOUNT_NAME>xx</ACCOUNT_NAME>
<ID_TYPE>x</ID_TYPE>
<ID>xxxxxxxxxxxxxxxxxx</ID>
<TEL>xxxxxxxxxxx</TEL>
<REMARK></REMARK>
</VALIDR>
</AIPG>



签名后的报文

<?xml version="1.0" encoding="GBK"?><AIPG>
<INFO>
<TRX_CODE>xxxxxx</TRX_CODE>
<VERSION>03</VERSION>
<DATA_TYPE>2</DATA_TYPE>
<LEVEL>5</LEVEL> SIGNED_MSG
<USER_NAME>xxxxxxxxxxxxxxxx</USER_NAME>
<USER_PASS>xxxxxx</USER_PASS>
<REQ_SN>xxxxxxxxxxxxxxxxxx</REQ_SN>
<SIGNED_MSG>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</SIGNED_MSG>
</INFO>
<VALIDR>
<MERCHANT_ID>xxxxxxxxxxxxxxx</MERCHANT_ID>
<SUBMIT_TIME>xxxxxxxxxxxxxx</SUBMIT_TIME>
<BANK_CODE>xxxx</BANK_CODE>
<ACCOUNT_NO>xxxxxxxxxxxxxxxx</ACCOUNT_NO>
<ACCOUNT_NAME>xx</ACCOUNT_NAME>
<ID_TYPE>x</ID_TYPE>
<ID>xxxxxxxxxxxxxxxxxx</ID>
<TEL>xxxxxxxxxxx</TEL>
<REMARK></REMARK>
</VALIDR>
</AIPG>

 

2.4.2 响应报文验签

验签算法为：SHA1withRSA/SM3withSM2。

验签约规则为：商户端获取响应报文SIGNED_MSG的值，用RSA/SM算法使用通联通分配的公钥（测试环境公钥找通联客户经理要）进行解密获得验签值。再将响应报文去掉SIGNED_MSG域值换成空行用SHA1（或SM3） 算哈希值，将该哈希值与上一步获得的验签值进行比较，一致则验证通过。

2.5 全报文加密

全报文密文脱敏为可选项，加密和解密的流程主要涉及发送报文时的加密、接收报文时的解密以及在报文头或请求地址中添加加密标志和密钥编号，改造方法如下：

2.5.1 加密规则

加密基础：在已生成签名字段值的原始报文基础上进行加密。

加密方式：

AES：采用 AES/ECB/PKCS5Padding 模式。

国密：采用 SM4/ECB/PKCS5Padding 模式

2.5.2 改造要点

  1. 发送报文加密：对全报文进行加密处理。
  2. 接收报文解密：对接收到的报文进行解密操作。
  3. 获取加密密钥: 在商户平台获取加密密钥，菜单位置：系统-运行参数-加密参数

4.添加加密标志：

    • 报文头方式：在报文头中添加加密标志 KEY - NUMBER。
    • 请求地址参数方式：支持在请求地址后面添加参数 KEY - NUMBER=${keyid}。

2.5.3 代码片段示例

HttpUtil post conn.setRequestProperty("KEY-NUMBER", "1000000000"); //http头部添加加密标志

AES算法:

加密 signedXml=AESUtil.encrptWithBase64(signedXml, "密钥");

解密 respText=AESUtil.decryptWithBase64(respText, "密钥");

国密SM4算法:

signedXml=SM4Util.encrptWithBase64(signedXml,"密钥","GBK"); signedXml=SM4Util.decryptWithBase64(signedXml, "密钥"，,"GBK");

2.6 主要字段说明

2.6.1 商户号

报文中的商户号（MERCHANT_ID）新商户默认为15位：数字+字母格式，入网时由通联分配。

2.6.2 交易代码

交易代码（TRX_CODE）区分了对应的 报文功能。

2.6.3 业务代码

业务代码（BUSINESS_CODE）在商户入网时由通联分配，商户报文只能上送指定的业务代码。

2.6.4 银行代码

报文体中的银行代码（BANK_CODE）一般为可选字段，通联的处理逻辑为：验证类的接口若填写了银行代码，通联会根据卡号匹配对应的卡BIN，若匹配出来的银行代码与商户上送的不一致，则返回银行代码不一致的错误，交易类的接口通联已商户上送银行代码为准。如果商户不上送银行代码，通联会根据卡bin匹配银行代码。对公和存折的统一上送银行代码。为了提高交易的成功率，建议该字段尽量上传。

2.6.5 交易类接口提交时间

 提交时间（SUBMITTIME），校验时间会与收付通系统时间（北京时间）在5分钟之内，假如超过就会被拦截。

huangwg 2025年1月24日 12:07 1662 0 条评论 收藏文档