目录
4.统一签约报文
金服宝支持四种签约模式，分别是快捷验证码模式、线下模式、网关模式、静默签约。签约模式由发卡行决定。
（1）快捷验证码模式：指通过接口发起签约申请和签约验证；
（2）线下模式：指通过接口发起签约申请，通过手机短信回复银行验证码进行签约验证；
（3）网关模式：指通过接口发起签约申请，通过网页跳转到银行页面进行签约验证；
（4）静默签约：指通过接口发起签约申请，银行校验持卡人信息无误即签约成功，无需短信验证。
快捷验证码模式如下图：
线下模式如下图
网关模式
4.1 签约申请(310001)
4.1.1 请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310001 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
LEVEL |
处理级别 |
是 |
N(1) |
5 |
|
|
|
MERCHANT_ID |
商户号 |
是 |
C(10,20) |
|
|
|
|
SUBMIT_TIME |
提交时间 |
是 |
C(14) |
|
|
|
|
USER_NAME |
用户名 |
是 |
C(1,20) |
|
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
BODY/ AGRINFO |
MERCHANT_ID |
商户号 |
是 |
C(15) |
商户号 |
|
|
SUBMIT_TIME |
提交时间 |
是 |
C(17) |
yyyyMMddHHmmssSSS |
|
|
|
AGR_TYPE |
协议类型 |
是 |
C（1） |
0：快捷 1：商委 2：直连 |
默认使用快捷 |
|
|
SIGN_MODE |
签约类型 |
否 |
C(1) |
0：线下模式 1：快捷模式 2：网关模式 3：静默签约 |
协议类型为快捷时支持快捷模式、网关模式（网关模式仅招行支持，版本号VERSION为06）； 协议类型为商委时支持线下模式、快捷模式和网关模式； 协议类型为直连时根据渠道不同支持快捷模式、线下模式和静默签约中的一种或多种； 如不上送，默认配置银行支持的签约模式。 |
|
|
BANK_CODE |
银行代码 |
否 |
C (8) |
4位或8位数，参见附录A.3银行代码 |
如不填根据卡bin匹配，存折必须填写 |
|
|
ACCOUNT_NO |
账号 |
是 |
N(1,32) |
银行卡或存折号码 |
|
|
|
ACCOUNT_NAME |
账户名 |
是 |
C(1,60) |
银行卡或存折上的所有人姓名 |
。 |
|
|
ACCOUNT_TYPE |
账户类型 |
否 |
C(2) |
00银行卡，01存折，02信用卡。不填默认为银行卡00。存折不填写将失败 |
|
|
|
ACCOUNT_PROP |
账户属性 |
否 |
C(1) |
0私人，1公司。不填时，默认为私人0。 |
|
|
|
ID_TYPE |
开户证件类型 |
否 |
C (1) |
参考证件类型 |
|
|
|
ID |
证件号码 |
是 |
C(1,20) |
|
|
|
|
TEL |
手机号码 |
是 |
C (1,11) |
手机号码 |
|
|
|
PREAGRMNO |
三方协议号 |
否 |
C (60) |
根据签约渠道确定是否必填 |
||
|
CVV2 |
CVV2 |
否 |
C (3) |
|
信用卡必填 |
|
|
VALIDDATE |
有效期 |
否 |
C (4) |
|
信用卡必填，格式MMYY(信用卡上的两位月两位年) |
|
|
MERREM |
商户自定义编号 |
否 |
C(1，128) |
|
|
|
|
NOTIFYURL |
通知地址 |
否 |
C (0,128) |
签约结果通知 |
网关模式必填 |
|
|
BACKURL |
跳转地址 |
否 |
C (0,128) |
触发签约回跳接口 |
网关模式必填 |
|
|
REMARK |
备注 |
否 |
C(60) |
|
||
|
EXPIRED |
协议失效日 |
否 |
C (6) |
yyyyMMdd |
与单笔最大限额、扣款时间单位、单位时间内扣款次数要素组合上送，要么全送，要么全不上送，如不上送，会根据系统配置的默认值，具体咨询业务人员。 |
|
|
SINGLEMAXAMT |
单笔最大限额 |
否 |
C (1,12) |
整数，单位分 |
与协议失效日、扣款时间单位、单位时间内扣款次数要素组合上送，要么全送，要么全不上送，如不上送，会根据系统配置的默认值，具体咨询业务人员。 |
|
|
PERIOD_UNIT |
扣款时间单位 |
否 |
C (2) |
00-年 04-月 07-日 |
与协议失效日、单笔最大限额、单位时间内扣款次数要素组合上送，要么全送，要么全不上送，如不上送，会根据系统配置的默认值，具体咨询业务人员。 |
|
|
MAX_CNT_LIMIT |
单位时间内扣款次数 |
否 |
C (2) |
与协议失效日、单笔最大限额、扣款时间单位要素组合上送，要么全送，要么全不上送，如不上送，会根据系统配置的默认值，具体咨询业务人员。 |
4.1.2 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310001 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
RET_CODE |
返回码 |
是 |
C(4) |
|
|
|
|
RET_MSG |
返回信息 |
是 |
C(120) |
|
|
|
|
BODY/AGRRSP |
SIGN_MODE |
签约模式 |
是 |
C(1) |
0 线下模式 1 快捷模式 2 网关模式 3 静默模式 |
|
|
URL |
网关地址 |
否 |
C(120) |
仅当签约模式为网关签约时存在 |
|
|
|
DATA |
数据 |
否 |
C(256) |
仅当签约模式为网关签约时存在 |
|
|
|
TLAGRMNO |
协议号 |
否 |
C（60） |
签约发起成功且返回信息为”该卡号已签约”时，表示签约成功，直接取该字段作为协议，不需要进行签约验证 |
4.2 签约验证(310002)
4.2.1 请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310002 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
LEVEL |
处理级别 |
是 |
N(1) |
|
|
|
|
MERCHANT_ID |
商户号 |
是 |
C(10,20) |
|
|
|
|
SUBMIT_TIME |
提交时间 |
是 |
C(14) |
|
|
|
|
USER_NAME |
用户名 |
是 |
C(1,20) |
|
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
BODY/ SIGNCFM_REQ |
MERCHANT_ID |
商户号 |
是 |
C(15) |
|
|
|
SRC_REQSN |
原请求流水 |
是 |
C(36,60) |
对应申请 请求报文中的REQ_SN |
|
|
|
VERCODE |
验证码 |
是 |
N (6) |
|
|
4.2.2 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310002 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
RET_CODE |
返回码 |
是 |
C(4) |
|
|
|
|
RET_MSG |
返回信息 |
是 |
C(120) |
|
|
|
|
BODY/SIGNCFM_RSP |
TLAGRMNO |
商户协议 |
是 |
C（32） |
|
|
4.3 签约查询(340009)
4.3.1 请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
340009 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
LEVEL |
处理级别 |
是 |
N(1) |
|
|
|
|
MERCHANT_ID |
商户号 |
是 |
C(10,20) |
|
|
|
|
SUBMIT_TIME |
提交时间 |
是 |
C(14) |
|
|
|
|
USER_NAME |
用户名 |
是 |
C(1,20) |
|
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
BODY/ QAGRINFO |
QUERY_MODE |
查询类型 |
是 |
C(1) |
1:查签约结果 |
|
|
MERCHANT_ID |
商户号 |
是 |
C(15) |
|
|
|
|
QUERY_SN |
原流水号 |
否 |
C(36,60) |
签约申请时的REQ_SN |
查签约结果时必需 |
|
|
ACCOUNT_NO |
账号 |
否 |
C(1,32) |
卡号 |
|
|
|
AGR_TYPE |
协议类型 |
否 |
C（1） |
0：快捷 1：商委 2：直连 |
默认为0 |
4.3.2 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
340009 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
RET_CODE |
返回码 |
是 |
C(4) |
|
|
|
|
RET_MSG |
返回信息 |
是 |
C(120) |
|
|
|
|
BODY/QAGRRSP |
MERCHANT_ID |
商户号 |
是 |
C（15） |
|
|
|
BANK_CODE |
银行代码 |
否 |
C（4,8） |
|
||
|
ACCOUNT_NO |
账户号 |
否 |
C(10,60) |
|
||
|
RET_CODE |
返回码 |
否 |
C(32) |
|
||
|
ERR_MSG |
返回信息 |
否 |
C(128) |
|
||
|
AGRMNO |
协议 |
否 |
C(27) |
|
|
|
|
AGR_TYPE |
协议类型 |
否 |
C（1） |
0：快捷 1：商委 2：直连 |
|
4.4 协议解除(310003)
工行、农行、中行、建行、民生支持解约
4.4.1 请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD
|
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310003 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
|
|
|
LEVEL |
处理级别 |
是 |
N(1) |
|
|
|
|
MERCHANT_ID |
商户号 |
是 |
C(10,20) |
|
|
|
|
SUBMIT_TIME |
提交时间 |
是 |
C(14) |
|
|
|
|
USER_NAME |
用户名 |
是 |
C(1,20) |
|
|
|
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|
|
|
|
BODY/ AGRCNL_REQ
|
MERCHANT_ID |
商户号 |
是 |
C(15) |
|
|
|
ACCOUNT_NO |
账号 |
是 |
N(1,32) |
银行卡或存折号码 |
|
|
|
ACCOUNT_NAME |
账户名 |
否 |
C(1,60) |
银行卡或存折上的所有人姓名 |
根据渠道确定 |
|
|
ID_TYPE |
开户证件类型 |
否 |
C (1) |
参考证件类型 |
根据渠道确定 |
|
|
ID |
证件号码 |
否 |
C(1,20) |
|
根据渠道确定 |
|
|
TEL |
手机号码 |
否 |
C (1,11) |
手机号码 |
根据渠道确定 |
|
|
BANK_CODE |
银行代码 |
否 |
C (8) |
4位或8位数，参见附录A.3银行代码 |
如不填根据卡bin匹配，存折必须填写 |
|
|
AGR_TYPE |
协议类型 |
是 |
C（1） |
0：快捷 1：商委 2：直连 |
|
|
|
AGRMNO |
协议号 |
是 |
C(60) |
|
4.4.2 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
HEAD |
TRX_CODE |
交易代码 |
是 |
C(6,10) |
310003 |
详见报文头说明 |
|
VERSION |
版本号 |
是 |
C(2) |
04 |
||
|
REQ_SN |
请求流水号 |
是 |
C(36,60) |
|||
|
RET_CODE |
返回码 |
是 |
C(4) |
|||
|
RET_MSG |
返回信息 |
是 |
C(120) |
4.5 签约结果通知
报文通讯方式：HTTP/HTTPS+GET方式，商户需提供接收通知的URL。
4.5.1 请求报文
|
URL参数名 |
说明 |
类型 |
取值 |
必填 |
备注 |
|
SIGNTYPE |
签约通知类型 |
C(1) |
0签约结果通知 1协议状态通知 |
是 |
目前只有0签约结果通知 |
|
MERID |
商户号 |
C(15) |
|
是 |
|
|
ACCTNO |
账号 |
C(1,32) |
|
是 |
|
|
NOTIFYTIME |
通知时间 |
N(14) |
格式：yyyyMMddHHmmss |
是 |
|
|
SIGNMODE |
签约模式 |
C(1) |
|
否 |
签约结果通知时有 |
|
REQSN |
请求流水号 |
C(30,60) |
签约申请时的REQ_SN |
否 |
签约结果通知时有 |
|
RETCODE |
返回码 |
C(4) |
|
否 |
签约结果通知时有 |
|
RETMSG |
错误信息 |
C(120) |
|
否 |
签约结果通知时有 |
|
STATUS |
协议状态 |
N(1) |
0：正常 1：失效 |
否 |
协议状态通知时有 |
|
TLAGRMNO |
商户协议 |
C (32) |
|
否 |
|
|
MERREM |
商户自定义字段 |
C(128) |
|
否 |
|
|
SIGN |
签名 |
|
使用SHA256withRSA签名。签名原始内容为 MERID| ACCTNO | NOTIFYTIME |
是 |
|
4.5.2 响应报文
商户系统返回一行内容
SUCCESS或者ERROR