一、概述

本文章用于指导中兴新云财务共享系统和CBS资金系统进行支付对接

二、接口需求描述

中兴新云财务共享系统和CBS资金系统进行支付对接分为三个部分：

1、支付指令推送：将共享系统的待付款支付指令推送至CBS资金系统

2、支付结果查询：将付款中的支付指令的支付结果从CBS资金系统查询同步至共享系统

3、退票支付结果查询：将退票支付结果从CBS资金系统查询同步至共享系统

三、接口对接流程及说明

1、支付指令推送：该接口CBS为服务端，我方为客户端，接口通过定时任务触发（建议频率：每天7点至19点的0分开始每5分钟执行）；

2、支付结果查询：该接口CBS为服务端，我方为客户端，接口通过定时任务触发（建议频率：每天8点至18点的0分开始每30分钟执行）；

3、退票支付结果查询：该接口CBS为服务端，我方为客户端，接口通过定时任务触发（建议频率：每天8点至18点的0分开始每30分钟执行）；

四、接口字段映射示例

1、支付指令推送：

1.1、如流程图所示，第2步是调产品标准接口-【支付指令查询接口（FSSC-API-000042）】查询待付款支付指令，这一步不涉及到跟CBS接口做字段映射，按照产品标准接口文档调用即可；

1.2、如流程图所示，第4步是调产品标准接口-【支付指令中间状态更新接口（FSSC-API-000153）】更新指令状态为“推送中”，这一步也不涉及到跟CBS接口做字段映射，按照产品标准接口文档调用即可；

1.3、如流程图所示，第6步是调CBS的接口-【支付接收接口】推送支付指令，字段映射如下：

接口请求参数说明
CBS接口字段	参数类型	是否必填	参数名称	描述	共享字段映射
referenceNum	String(50)	Y	业务参考号	为防止重复支付，业务去重字段，由调用方确保唯一	取产品标准接口【支付指令查询接口】返参中的paymentNo
busType	String(3)	Y	业务类型	202-对外支付、204-银行调拨、215-联动支付、401-集中支付，例如：对外支付，传值：202	默认值：202
amount	demical(15,2)	Y	金额	整数部分最长13位，小数部分定长2位	取产品标准接口【支付指令查询接口】返参中的paymentAmount
currency	String(2)	Y	币种	见附录4.1.1币种枚举；示例：人民币传值：10	找到系统管理-外部数据编码中，外部系统编码为“PAY-CBS8”、数据类型为“CURRENCY_SYS”的所有有效数据，按指令报账币种【currencyCode】匹配对应的【外部数据编码】传入
payAccount	String(35)	N	付款账号	集中支付时非必传，其余支付类型必传	取产品标准接口【支付指令查询接口】返参中的payerBankAccountNum
revAccount	String(35)	Y	收款账号		取产品标准接口【支付指令查询接口】返参中的gatherBankAccountNum
revAccountName	String(200)	Y	收款账户名称	204-银行调拨支付类型可不传，其他必传	取产品标准接口【支付指令查询接口】返参中的gatherBankAccountName
revBankType	String(5)	Y	收款银行类型	如招行传CMB，见附录4.1.5	找到系统管理-外部数据编码中，外部系统编码为“PAY-CBS8”、数据类型为“BANK_SYS”的所有有效数据，按指令收款总行编码【gatherBankHeadCode】匹配对应的【外部数据编码】传入
revBankName	String(200)	N	收款开户行名称	各银行长度要求不同；如客户传了联行号，联行号能匹配上到对应开户行就可以由CBS8自动带出收款开户行名称	取产品标准接口【支付指令查询接口】返参中的gatherBankBranchName
revProvince	String(20)	N	收款人省	收款账号所属省份，如客户传了联行号，联行号能匹配上到对应开户行就可以由CBS8自动带出收款省	不传
revCity	String(30)	N	收款人市	收款账号所属市；如客户传了联行号，联行号能匹配上到对应开户行就可以由CBS8自动带出收款账号所属市	不传
cnapsCode	String(30)	N	联行号	同行时，可不传联行号，跨行时必填；取值方式见联行号查询接口	取产品标准接口【支付指令查询接口】返参中的gatherBankUnitedCode
purpose	String(600)	Y	该笔支付用途	用于支付时传给银行，查明细时银行带回（一般情况下银行会带回，少数银行不会带回支付的用途），长度及填写要求	取产品标准接口【支付指令查询接口】返参中的paymentMemo
summary	String(200)	N	该笔支付备注	非必填，可以为空，各银行长度要求不同;按客户所需填写，部分银行可能会接收此字段，最终会在支付申请单详情中返回	取产品标准接口【支付指令查询接口】返参中的paymentMemo
expectTime	DateTime	N	期望支付时间	期望在CBS8系统中发出指令的时间，不填默认为立即发出。格式：yyyy-mm-dd hh:mm:ss	取产品标准接口【支付指令查询接口】返参中的predictDate，注意处理格式
personalFlag	String(1)	Y	公私标志	1-对私，0-对公	取产品标准接口【支付指令查询接口】返参中的pubPriCode，我们的“1”对应CBS的“0”，我们的“2”对应CBS的“1”
urgentTag	String(1)	Y	加急标志	1-加急；0-不加急;2-特急	根据收款银行类型（revBankType），如果收款银行类型是“MSBC”（中国民生银行），则必填，且金额（amount）＜100万，传0；≥100万，传1；收款银行为其余银行，均不传
cityFlag	String(2)	Y	同城标志	0-同城；1-异地；收/付款账号所属同一个市为同城，否则为异地；兴业银行必填	取当前指令的收款银行支行城市和付款银行支行城市比对（参数见本需求的父需求下的第二个子需求，是共享组本次要做的需求），两者一致，则传0；两者不一致则传1；注：空对空、空对有值视为不一致，传1
payChannel	String(1)	N	支付渠道	0-其他渠道，1-直联渠道，默认直联渠道	默认：1
erpExtend2	String(256)	Y	客户备用字段2,建设银行必填	业务匹配规则，必填，101-单笔支付；102-批量支付，传key值即可，例：101	传：101
返回参数
参数	参数类型	是否不为空	说明	备注
code	String(8)	Y	状态码	0:成功 500:内部服务器错误 503:服务不可用 504:超时
msg	String	N	异常消息	状态码不为0时，返回错误消息
data（下方为list）
successed	boolean	Y	是否成功	False:失败
successed	boolean	Y	是否成功	ture:成功
busNum	String(19)	N	申请单编号	如果该笔经办成功，则返回系统生成的单据号,项目级唯一，如果经办失败，单据号为空
referenceNum	String	Y	业务参考号	调用方入参传的，与请求参数中的reference相对应
errorMsg	String(200)	N	错误信息	如果经办失败，会返回该笔错误信息（包含审批错误信息、银行错误信息等）

1.4、如流程图所示，第8步是调产品标准接口-【支付指令中间状态更新接口（FSSC-API-000153）】更新指令状态为“付款中”或“付款异常”，这一步需要根据CBS【支付接收接口】的返回结果进行传值，字段映射如下：

接口请求参数说明
共享接口字段	中文名称	参数类型	是否必填	说明	CBS字段映射
data	请求数据	array	是
paymentNo	支付指令编号	string	是	实付指令表中的付款编号（PAYMENT_NO），校验是否存在	取上一步【支付接收接口】返回的指令编码referenceNum
groupCode	集团编码	string	否	为空则取当前登录人集团信息，不为空则取当前集团数据进行过滤；需校验集团编码数据有效性；同一接口数据中集团编码需要唯一，否则报错“集团编码不唯一，请重新推送”；如果为空时也无法获取到当前登录人信息，则报错“集团编码不存在，请重新确认后推送”
time	回传时间	string	否	yyyy-MM-dd HH:mm:ss
paymentStatus	回传状态	string	是	“16-推送中”、“20-付款中”；如果状态不为该两个，则报错“【支付指令编号】回传状态不为“推送中/付款中”，请重新确认后推送”	根据上一步《支付指令推送接口》返回的code和successed值，更新对应状态值： code为0且successed为true：传20； code为0且successed为false：传22； code非0：传22；推送接口返回429，则表示该请求因为限流被拒绝，此时传：10
rowNum	行号	string	否
rowId	行ID	string	否
返回参数
参数名	中文名称	参数类型	是否必填	说明
msg	信息	string	否	返回消息-整体
code	编码	string	是	0-全部成功;1-全部失败;2-部分成功
failNum	失败条数	string	否	失败条数
data	数据	array	否	返回数据
rowNum	行号	string	是	行号
errMsg	错误信息	string	是	每行错误消息
rowId	行ID	string	否	接口平台数据同步标识
successNum	成功条数	string	否	成功条数

2、支付结果查询：

2.1、如流程图所示，第2步是调产品标准接口-【支付指令查询接口（FSSC-API-000042）】查询付款中的支付指令，这一步不涉及到跟CBS接口做字段映射，按照产品标准接口文档调用即可；

2.2、如流程图所示，第4步是调CBS的接口-【支付列表查询接口】查询支付结果，字段映射如下：

接口请求参数说明
CBS接口字段	参数类型	是否必填	参数名称	描述	共享字段映射
currentPage	int	Y	当前查询页码	从1开始计数	默认：1
pageSize	int	Y	本次查询的记录数	最大1000	默认：1000
queryDateStart	string(date-time)	Y	开始日期2022-11-16 00:00:00	开始和结束日期间隔不能超过半年	取系统当前时间往前6个月的日期（可按180天算，即取系统当前时间往前180天的日期）
queryDateEnd	string(date-time)	Y	2022/11/17 0:00		取系统当前时间，如：2024-03-04 19:10
referenceNum	String	N	业务参考号	调用方入参传的，与请求参数中的referenceNum相对应	取产品标准接口【支付指令查询接口】返参中的paymentNo
接口返回参数
参数	参数类型	是否必填	参数名称	备注
code	String(8)	Y	状态码	0:成功 500:内部服务器错误 503:服务不可用 504:超时
msg	String	N	异常消息	状态码不为0时，返回错误消息
total	long	Y	总记录数
busNum	String	Y	申请单编号	根据此编号查询详细信息
payAccount	String	Y	付款账户
payDate	Date	N	支付时间
payStatus	String	N	支付状态	见附录4.3
errorMsg	String	N	付款单提示信息/银行返回信息

2.3、如流程图所示，第6步是调产品标准接口-【支付结果同步接口（FSSC-API-000043）】同步支付结果，根据上一步接口返参的内容进行不同处理：若返回的数据的payStatus为a待提交直连/b已提交直连/c银行已受理/e可疑/f待人工确认/l待余额返回/n其他/p支付中/q待支付/i部分成功：则这部分数据不执行此步骤，保持对应支付指令状态不变；其余数据，均需执行此步骤，更新支付指令状态；字段映射如下：

接口请求参数说明
共享接口字段	中文名称	参数类型	是否必填	说明	CBS字段映射
data	请求参数	array	Y	请求参数
businessNum	业务流水号	string	N	业务流水号	取CBS【支付列表查询接口】返回的busNum
gatherBankUnitedCode	收款联行号	string	N	收款联行号，支付状态为30-已付款为必填	取第2步查询支付指令对应的收款联行号
groupCode	集团编码	string	Y	集团编码	取第2步查询支付指令所属集团的编码
gatherBankAccountNum	收款账号	string	N	收款账号，支付状态为30-已付款为必填	取CBS【支付列表查询接口】返回的revAccount
onOffLine	线上/线下	string	Y	线上/线下	默认为“0”
payerBankUnitedCode	付款联行号	string	N	付款联行号，支付状态为30-已付款为必填	取第2步查询支付指令对应的付款联行号
paymentModeCode	支付方式	string	N	支付方式，支付状态为30-已付款为必填	取第2步查询支付指令对应的支付方式
paymentStatus	付款状态/指令状态	string	Y	付款状态/指令状态，仅接受状态：25-付款失败，30-已付款，12-支付退票	取CBS【支付列表查询接口】返回的code和payStatus值，映射传值： code非0或payStatus为k取消支付/d银行未受理/h支付失败：传25 payStatus为g支付成功：传30 payStatus为j退票：传12
errorMsg	失败原因	string	N	失败原因，付款状态为25-付款失败时，必填	取CBS【支付列表查询接口】返回的errorMsg
payerBankAccountNum	付款账号	string	N	付款账号，支付状态为30-已付款为必填，	取CBS【支付列表查询接口】返回的payAccount
paymentNo	指令编号	string	Y	指令编号	取第2步查询支付指令的指令编号paymentNo
postalOrderCodes	汇票/支票编号	string	N	汇票/支票编号	不传
paymentDate	支付成功交易时间	string	N	支付成功交易时间，付款状态为30-已付款时，必填	取CBS【支付列表查询接口】返回的payDate（注意需处理格式为YYYY-MM-DD）
returnNumber	退票流水号	string	N	退票流水号，若变更为支付退票状态，需传退票流水号	不传
actualPayCurrency	实付币种	string	N	实付币种	不传
actualPayAmount	实付金额	string	N	实付金额	不传
actualPayStandardCurrencyRate	实付币种兑本币汇率	string	N	实付币种兑本币汇率	不传
actualPayStandardCurrencyAmount	实付本位币金额	string	N	实付本位币金额	不传
返回参数
参数名	中文名称	参数类型	是否必填	说明
msg	信息	string	否	返回消息-整体
code	编码	string	是	0-全部成功;1-全部失败;2-部分成功
failNum	失败条数	string	否	失败条数
data	数据	array	否	返回数据
rowNum	行号	string	是	行号
errMsg	错误信息	string	是	每行错误消息
rowId	行ID	string	否	接口平台数据同步标识
successNum	成功条数	string	否	成功条数

3、退票支付结果查询：

3.1、如流程图所示，第4步是调CBS的接口-【支付列表查询接口】查询退票支付结果，字段映射如下：

接口请求参数说明
CBS接口字段	参数类型	是否必填	参数名称	描述	共享字段映射
currentPage	int	Y	当前查询页码	从1开始计数	默认：1
pageSize	int	Y	本次查询的记录数	最大1000	默认：1000
queryDateStart	string(date-time)	Y	开始日期2022-11-16 00:00:00	开始和结束日期间隔不能超过半年	取系统当前时间往前2个月的日期（可按60天算，即取系统当前时间往前60天的日期）
queryDateEnd	string(date-time)	Y	2022/11/17 0:00		取系统当前时间，如：2024-03-04 19:10
接口返回参数
参数	参数类型	是否必填	参数名称	备注
code	String(8)	Y	状态码	0:成功 500:内部服务器错误 503:服务不可用 504:超时
msg	String	N	异常消息	状态码不为0时，返回错误消息
total	long	Y	总记录数
busNum	String	Y	申请单编号	根据此编号查询详细信息
payAccount	String	Y	付款账户
payDate	Date	N	支付时间
payStatus	String	N	支付状态	见附录4.3
errorMsg	String	N	付款单提示信息/银行返回信息

3.2、如流程图所示，第4步是调产品标准接口-【支付结果同步接口（FSSC-API-000043）】同步支付结果，根据上一步接口返参的内容进行处理：只处理返参数据中payStatus为j退票的，更新支付指令的付款状态为”支付退票“；字段映射如下：

接口请求参数说明
共享接口字段	中文名称	参数类型	是否必填	说明	CBS字段映射
data	请求参数	array	Y	请求参数
businessNum	业务流水号	string	N	业务流水号	取CBS【支付列表查询接口】返回的busNum
gatherBankUnitedCode	收款联行号	string	N	收款联行号，支付状态为30-已付款为必填	不传
groupCode	集团编码	string	Y	集团编码	取第2步查询支付指令所属集团的编码
gatherBankAccountNum	收款账号	string	N	收款账号，支付状态为30-已付款为必填	不传
onOffLine	线上/线下	string	Y	线上/线下	默认为“0”
payerBankUnitedCode	付款联行号	string	N	付款联行号，支付状态为30-已付款为必填	不传
paymentModeCode	支付方式	string	N	支付方式，支付状态为30-已付款为必填	不传
paymentStatus	付款状态/指令状态	string	Y	付款状态/指令状态，仅接受状态：25-付款失败，30-已付款，12-支付退票	默认为“12”
errorMsg	失败原因	string	N	失败原因，付款状态为25-付款失败时，必填	不传
payerBankAccountNum	付款账号	string	N	付款账号，支付状态为30-已付款为必填，	不传
paymentNo	指令编号	string	Y	指令编号	取CBS【支付列表查询接口】返回的busNum
postalOrderCodes	汇票/支票编号	string	N	汇票/支票编号	不传
paymentDate	支付成功交易时间	string	N	支付成功交易时间，付款状态为30-已付款时，必填	不传
returnNumber	退票流水号	string	N	退票流水号，若变更为支付退票状态，需传退票流水号	不传
actualPayCurrency	实付币种	string	N	实付币种	不传
actualPayAmount	实付金额	string	N	实付金额	不传
actualPayStandardCurrencyRate	实付币种兑本币汇率	string	N	实付币种兑本币汇率	不传
actualPayStandardCurrencyAmount	实付本位币金额	string	N	实付本位币金额	不传
返回参数
参数名	中文名称	参数类型	是否必填	说明
msg	信息	string	否	返回消息-整体
code	编码	string	是	0-全部成功;1-全部失败;2-部分成功
failNum	失败条数	string	否	失败条数
data	数据	array	否	返回数据
rowNum	行号	string	是	行号
errMsg	错误信息	string	是	每行错误消息
rowId	行ID	string	否	接口平台数据同步标识
successNum	成功条数	string	否	成功条数

注：本示例为CBS的8.0版本

五、其他说明

1、做支付对接，最重要的是不能重复支付，因此在给CBS推送支付指令时，一定要记录好指令推送的中间状态（详见【支付指令推送】流程图中的第4步和第8步）以免重复推送；

2、将共享的支付指令推到CBS支付时：有个【报账币种】参数，我方存储的是国际标准代码，对方存储的是货币号，故接口需要做转换处理之后，再传参，映射关系维护到外部数据编码中（映射关系由项目自行维护）；

3、将共享的支付指令推到CBS支付时：有个【收款银行类型】参数，我方存储的银行编码和CBS的不是同一套，故接口需要做转换处理之后，再传参，映射关系维护到外部数据编码中（映射关系由项目自行维护）；

4、CBS8.0已完成产品化对接，如项目对接的刚好是CBS的8.0版本，可直接按这篇文章 http://tmpbbs.ztc.ztccloud.com.cn:6875/wiki/1138544/1296496 配置使用，无需开发，若是其他版本，据我们了解，是有一定差异的，需要项目自行开发；

【CBS-支付对接】方案指导

【CBS-支付对接】方案指导

关于作者

目录