目录
4.统一签约接口
金服宝支持四种签约模式，分别是快捷验证码模式、线下模式、网关模式、静默签约。签约模式由发卡行决定。
（1）快捷验证码模式：指通过接口发起签约申请和签约验证；
（2）线下模式：指通过接口发起签约申请，通过手机短信回复银行验证码进行签约验证；
（3）网关模式：指通过接口发起签约申请，通过网页跳转到银行页面进行签约验证；
（4）静默签约：指通过接口发起签约申请，银行校验持卡人信息无误即签约成功，无需短信验证。
快捷验证码模式如下图：
线下模式如下图
网关模式
4.1 签约申请(310001)
4.1.1接口功能
商户可通过该接口向金服宝系统发起签约请求，提交持卡人的相关账户信息（如账号、账户名、身份证号、手机号码等）以及签约相关配置信息（如协议类型、签约类型等）。
C：字符串
C (x,y)：最小长度 x、最大长度 y 的字符串
N (x)：固定 x 位整数
N (x,y)：最小长度 x、最大长度 y 的整数
限制类型：M - 必填，C - 选填
（2）请求报文模块说明：
- HEAD模块：包含交易代码、版本号、处理级别、商户号、提交时间、用户名、请求流水号等核心标识和基础信息，为必填模块，确保请求的唯一性和准确性。
- BODY/AGRINFO模块：涵盖协议类型、签约类型、银行代码、账号、账户名等与签约相关的具体业务信息，其中部分字段为必填，部分为选填，支撑签约申请的业务逻辑。
（3）响应报文模块说明：
- HEAD模块：包含交易代码、版本号、请求流水号、返回码、返回信息，用于反馈请求的基本处理情况和结果状态，是获取请求是否成功的关键模块。
- BODY/AGRRSP模块：包含签约模式、网关地址、数据、协议号等与签约响应相关的业务信息，不同签约模式下部分字段存在与否不同，为后续签约操作提供指引。
4.1.2请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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.3响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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接口功能
在快捷验证码模式下，持卡人收到银行发送的验证码后，商户通过该接口提交验证码，完成签约验证流程。
C：字符串
C (x,y)：最小长度 x、最大长度 y 的字符串
N (x)：固定 x 位整数
N (x,y)：最小长度 x、最大长度 y 的整数
限制类型：M - 必填，C - 选填
（2）请求报文模块说明：
- HEAD模块：包含交易代码、版本号、处理级别、商户号、提交时间、用户名、请求流水号，是请求的基础标识模块，确保请求的合法性和可追溯性，为必填模块。
- BODY/SIGNCFM_REQ模块：包含商户号、原请求流水、验证码，用于关联之前的签约申请并提交验证信息，所有字段均为必填，保障验证操作的准确性和关联性。
（3）响应报文模块说明：
- HEAD模块：包含交易代码、版本号、请求流水号、返回码、返回信息，用于反馈验证请求的处理结果，告知验证是否成功，是核心的结果反馈模块。
- BODY/SIGNCFM_RSP模块：包含商户协议号，验证成功后会返回该协议号，作为后续业务操作（如扣款、查询等）的重要依据，为必填字段（验证成功时）。
4.2.2请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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.3 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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接口功能
通过指定查询类型为 “查签约结果”，并提供原签约申请的流水号等信息，可查询该次签约申请的最终结果，如签约成功、签约失败及失败原因等。
C：字符串
C (x,y)：最小长度 x、最大长度 y 的字符串
N (x)：固定 x 位整数
N (x,y)：最小长度 x、最大长度 y 的整数
限制类型：M - 必填，C - 选填
（2）请求报文模块说明：
- HEAD模块：包含交易代码、版本号、处理级别、商户号、提交时间、用户名、请求流水号，是请求的基础信息模块，确保请求的唯一性和合法性，为必填模块。
- BODY/QAGRINFO模块：包含查询类型、商户号、原流水号、账号、协议类型，用于指定查询的条件和范围，其中查询类型和商户号为必填，其他字段根据查询需求选填，保障查询的精准性。
（3）响应报文模块说明：
- HEAD模块：包含交易代码、版本号、请求流水号、返回码、返回信息，用于反馈查询请求的处理情况，告知查询是否成功，是结果反馈的核心模块。
- BODY/QAGRRSP模块：包含商户号、银行代码、账户号、返回码、错误信息、协议号、协议类型等查询结果信息，根据查询条件返回对应的签约相关详情，为后续业务判断提供数据支持。
4.3.2请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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接口功能
商户可针对已签约的账户，通过该接口提交协议解除申请，提供相关账户信息和协议信息，申请解除与该账户的签约协议。
C：字符串
C (x,y)：最小长度 x、最大长度 y 的字符串
N (x)：固定 x 位整数
N (x,y)：最小长度 x、最大长度 y 的整数
限制类型：M - 必填，C - 选填
（2）请求报文模块说明：
- HEAD模块：包含交易代码、版本号、处理级别、商户号、提交时间、用户名、请求流水号，是请求的基础标识和合法性保障模块，为必填模块。
- BODY/AGRCNL_REQ模块：包含商户号、账号、账户名、开户证件类型、证件号码、手机号码、银行代码、协议类型、协议号，用于指定要解除的协议相关信息，其中账号、协议类型、协议号为必填，其他字段根据渠道要求选填，确保准确找到并解除目标协议。
（3）响应报文模块说明：
- HEAD模块：包含交易代码、版本号、请求流水号、返回码、返回信息，仅通过该模块反馈协议解除请求的处理结果，告知协议是否成功解除，是结果反馈的唯一模块。
该接口只支持特定的银行：工行、农行、中行、建行、民生支持解约
4.4.2请求报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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.3 响应报文
|
接口 |
字段 |
字段解释 |
必填 |
类型 |
取值 |
备注 |
|
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 签约结果通知
4.5.1接口功能
C：字符串
C (x,y)：最小长度 x、最大长度 y 的字符串
N (x)：固定 x 位整数
N (x,y)：最小长度 x、最大长度 y 的整数
限制类型：M - 必填，C - 选填
（2）请求报文模块说明：
该接口请求报文以URL参数形式传递，包含签约通知类型、商户号、账号、通知时间、签约模式、请求流水号、返回码、错误信息、协议状态、商户协议、商户自定义字段、签名等参数。其中签约通知类型、商户号、账号、通知时间、签名为必填参数，其他参数根据通知类型（目前仅支持签约结果通知）选填，确保通知信息的完整性和安全性。
（3）响应报文模块说明：
商户系统仅需返回一行内容，即“SUCCESS”或“ERROR”，用于告知金服宝系统是否成功接收该签约结果通知，反馈形式简单直接。
报文通讯方式：HTTP/HTTPS+GET方式，商户需提供接收通知的URL。
4.5.2请求报文
|
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.3响应报文
商户系统返回一行内容
SUCCESS或者ERROR