融捷通金融服务平台支付网关用户手册V1.4.2.doc

融捷通金融服务平台支付网关用户手册凯塔长春研发中心1. 文档属性文档属性内容文档名称：融捷通金融服务平台支付网关用户手册文档版本号：1.1文档状态：正式稿文档编写完成日期2013年05月08日 2. 文档变更历史清单文档版本号变更日期修改人变更内容简述V1.02013-05-08于东此版本增加41017财付通跨行入金接口增加70001透支贷接口增加网关demo说明V1.12013-05-28于东此版本41017接口暂停使用V1.22013-07-19于东41017接口修改，增加41012、 70001 、70002、 70003接口V1.32013-08-28于东增加41018接口，修改70002接口V1.42013-12-19于东41017接口修改(中金支付)，客户端ip取得java代码示例V1.4.12013-02-17于东41018返回状态修改V1.4.22013-02-28于东增加41019接口目 录1引言21.1文档概述22接口说明22.1api配置32.2业务实现流程52.3api请求参数名及其内容列表63paysdemo支付例子说明281 引言1.1 文档概述该文档包括合作方通过支付系统网关发起的“子账户开户、子账户资料变更、绑定充值提现账户、支付交易、跨行入金、支付交易（可透支）”等功能，通过URL超链接进行网上通讯，支付网关必须向合作方提供的交易信息及其格式、验证签名程序的接口及调试用的例子。红色部分，为特别需要注意的内容!2 接口说明合作方通过合作方的子系统进行网上订单交易、开户、资料变更、支付交易等，确认后通过合作方子系统提供的“支付网关”超链接，发送报文完成交易。为此合作方子系统调用api类，将数据提交到支付网关指定的网上支付的URL（区分大小写，请联系确认投产环境和测试环境的IP地址及端口）。https:/服务器ip:8080/paysnet/PayInterfaceI2.1api配置api 包名：cata-paysnet-api-3.0.jar1. 初始化配置文件paysclient.ini说明：# 支付网关地址URL配置多银行网关：根据银行编码，发送到不同网关1.华夏银行：默认nt.url=:8080/paysnet/PayInterfaceI2.平安银行：银行编码(A14)nt.url.A14=:9443/paysnet/PayInterfaceI# 支付网关与合作方：平台的签名证书 yes/nouseDGHSignatureFactory=yes# 合作方的签名证书和口令client.keystore.filename=test.pfxclient.keystore.password=1# 服务是否打印日志信息yes/noclient.printLog=yes证书与配置文件paysclient.ini在同一目录，证书使用CFCA证书初始化支付环境，path为系统配置文件paysclient.ini所在目录名PaysEnvironment. Initialize(path);初始化证书if(PaysEnvironment.useDGHSignatureFactory) SignatureTool.getCFCAInstance();合作方主要使用nt包下的Nt*Request设置参数、发送报文，Nt*Response解析报文、得到返回参数“*”代表标识5位交易码，如41001。2.2业务实现流程1根据请求报文，将参数设置到请求对象中Nt*Request2调用报文处理Nt*Request的process()方法3使用Nt*Request的postSend ()调用支付接口进行支付4得到返回数组String strs，strs0:message; strs1:signature5将返回数组设置到响应对象Nt*Response中进行解析（响应报文），得到响应信息。6从Nt*Response得到参数信息“*”代表5位交易码，如41001。详见： paysdemo支付例子2.3api请求参数名及其内容列表为了保证中文信息的正确性，合作方请求的数据字符集要求是UTF-8。合作方子系统提交数据中的空格将被认为是有效字符被接收，请合作方开发时注意对多余空格的控制。在Nt*Request设置报文参数，Nt*Response得到响应报文合作方发起子账户开户（转平台）【41001】合作方按如下规则生成子账户：100+YYYYMM+5位序列（代理商）200+YYYYMM+5位序列（行业商户）300+YYYYMM+5位序列（合作方收益子账户）请求交易数据（报文格式）,使用Nt41001Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2. 2业务流水Serial合作方流水号MarketSerial3. 3资金账户信息FundAcc资金账号 FirmId子账户VaccId合作方系统按规则生成。100+YYYYMM+5位序列客户名称CustName4. 4交易商信息Client法人名称ClientName法人性质ClientKind法人证件类型CertType法人证件号CertID法人证件有效期CertDate性别Gender国籍或地区Nationality法人电话号码TelNo 传真FaxNo法人手机MobiNo邮政编码PostCode客户地址Address企业证件种类CorType企业证件号码CorID企业证件有效期CorDate电子邮件Email5. 6摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41001Response解析，如下：编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode合作方编号2. 2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial3. 6返回信息ReturnInfo返回码RtnCode返回信息RtnInfo4. 7摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起子账户资料变更（转平台）【41002】请求交易数据（报文格式）使用Nt41002Request请求类（备注：报文格式和41001子账户开户一致，除必填字段（不允许变更）外，需要修改的字段上送，不需要修改的为空。）编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2. 2业务流水Serial合作方流水号MarketSerial3. 3资金账户信息FundAcc资金账号 FirmId子账户VaccId客户名称CustName4. 4交易商信息Client法人名称ClientName法人性质ClientKind法人证件类型CertType法人证件号CertID法人证件有效期CertDate性别Gender国籍或地区Nationality法人电话号码TelNo 传真FaxNo法人手机MobiNo邮政编码PostCode客户地址Address企业证件种类CorType企业证件号码CorID企业证件有效期CorDate电子邮件Email5. 6摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41002Response解析如下：编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode合作方编号2. 2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial3. 6返回信息ReturnInfo返回码RtnCode返回信息RtnInfo4. 7摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起绑定充值取现账户（转平台）【41004】请求交易数据（报文格式）使用Nt41004Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2业务流水Serial合作方流水号MarketSerial3银行账户信息BankAcc银行账号BankAcc开户名称CustName开户行BankId开户银行网点号BankCode开户银行网点地址BankAddr卡号账号标示CashFlag是否跨行IsSelf账户类别CashType对公或对私账户4资金账户信息FundAcc资金账号 FirmId虚拟账户VaccId客户名称CustName5币种信息MoneyKind币种MoneyKind6交易商信息Client客户证件号CertID对公企业证件号对私个人证件号7标记信息FlagInfo操作标示Flag11：绑定；2：变更；3：删除8资金信息Transfer转账限额TransferLimit或支付限额9摘要SummaryInfo摘要1Summary1摘要1摘要2Summary2摘要2接口处理成功时，返回XML数据包，由Nt41004Response解析如下：编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode合作方编号2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial 3返回信息ReturnInfo返回码RtnCode返回信息RtnInfo4摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起支付交易（转平台）【41005】请求交易数据（报文格式）使用Nt41005Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2业务流水Serial合作方流水号MarketSerial支付单号3付款方账户信息PFundAcc支付账号VaccId客户名称CustName支付密码FundPwd4收款方账户信息RFundAcc支付账号VaccId客户名称CustName5币种信息MoneyKind币种MoneyKind6资金信息Transfer支付金额TransferAmount手续费TransferCharge7支付标识FlagInfo交易种类Flag101：普通支付02：确认支付03：银联支付04：支付退款（无手续费）05：平台代扣06：划拨手续费（无手续费）07：划拨银联入金 （无手续费）支付类型Flag201：支付请求02：二次确认03：支付回退（当Flag1=02是确认支付，Flag2必填，其他Flag1情况默认填写01）交易摘要Flag301-销售款02-手续费03-退款04-利息8摘要SummaryInfo摘要1Summary1摘要2Summary2备注：支持合作方发起的交易有：01：普通支付02：确认支付（目前暂时没有开通）04：支付退款（无手续费）05：平台代扣如果资金信息节点中的“手续费”不为空，则支付平台手续费按照资金信息节点中的“手续费”收取金额，如果为零，则平台按照手续费设置的参数计算收取手续费。接口处理成功时，返回XML数据包，由Nt41005Response解析如下：编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode机构编号2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial支付单号BillNo支付单号3资金信息Transfer资金余额CurrentBalance冻结金额FreezeMoney4返回信息ReturnInfo返回码RtnCode返回信息RtnInfo5摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起支付交易查询（转平台）【41006】请求报文（报文格式）使用Nt41006Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc市场编号MktCode2. 2业务流水Serial市场流水号MarketSerial3. 3摘要SummaryInfo摘要1Summary1摘要2Summary2响应报文由Nt41006Response解析编号组件描述组件名称字段含义字段名称是否必输说明1.消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 交易发起方TradeSrc交易发起方市场编号MktCode市场编号2. 2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial3. 5标记信息FlagInfo交易状态Flag10：未支付 （失败）1：已支付（成功）2：未明3：转账成功、出金失败4：放款成功、入金失败5：出金成功、还款失败6：出金成功，还息失败7：出金成功，还款超时4. 4返回信息ReturnInfo返回码RtnCode返回信息RtnInfo5. 5摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起同行充值入金（转平台）41010请求交易数据（报文格式）使用Nt41010Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2业务流水Serial合作方流水号MarketSerial3资金账户信息FundAcc资金账号 FirmId客户名称CustName5币种信息MoneyKind币种MoneyKind6资金信息Transfer充值金额TransferAmount手续费TransferCharge无手续费用时，填写08摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41010Response解析如下：编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode机构编号2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial3资金账户信息FundAcc资金账号 FirmId客户名称CustName4资金信息Transfer充值金额TransferAmount本次充值金额资金余额CurrentBalance充值后可用余额(可出余额)5返回信息ReturnInfo返回码RtnCode返回信息RtnInfo6摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起资金信息查询（转平台）41011请求交易数据（报文格式）使用Nt41011Request请求类编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易时间Time银行网点BankId 交易发起方TradeSrc合作方编号MktCode2业务流水Serial合作方流水号MarketSerial3资金账户信息FundAcc资金账号 FirmId客户名称CustName8摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41011Response解析如下：编号组件描述组件名称字段含义字段名称是否必输说明1消息包头Pub交易码TradeCode交易日期Date交易日期交易时间Time交易时间银行网点BankId 银行网点号交易发起方TradeSrc交易发起方合作方编号MktCode机构编号2业务流水Serial合作方流水号MarketSerial平台流水号PlatSerial3资金账户信息FundAcc资金账号 FirmId客户名称CustName4资金信息Transfer资金余额CurrentBalance查询不到时，为0冻结金额FreezeMoney查询不到时，为05授信档案CreditInfo授信文件卷宗号FileId有授信档案时必填,否则为NULL授信余额CreditMoney有授信档案时必填，否则为0银行经办机构代码BankOrgCode有授信档案时必填，否则为NULL授信期限CreditLimit授信期限单位CreditUnit授信起始日期StartDate授信到期日期EndDate6返回信息ReturnInfo返回码RtnCode返回信息RtnInfo7摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起财付通跨行入金（转平台）41017使用Nt41017Request请求类组件名称字段含义字段名称是否必输说明Pub交易码TradeCode交易码，默认：41017交易日期Date当前日期，如20130601交易时间Time当前时间，如115103银行编号BankIdA13华夏银行其他保留交易发起方TradeSrc默认：I -合作方 P-平台合作方编号MktCode融捷通分配给合作方Serial合作方流水号MktSer合作方系统自动生成的业务流水号FundAcc用户资金账号FirmId用户在融捷通注册的账号用户名称CustName账号对应的用户名称MoneyKind币种MoneyKind默认：CNY-人民币汇钞标志CashExCode默认：1Address财付通系统urlIP1客户端IP，指用户浏览器端IP返回returnURLAdd1返回的returnURL前台通知Transfer充值金额TransferAmount放大100倍，例如1元，输入值100FlagInfo入金渠道Flag11财付通 3中金支付其他保留SummaryInfo摘要1Summary1默认：财付通渠道入金摘要2Summary2客户端实际IP1:方法示例 public String getIpAddr(HttpServletRequest request) String ip = request.getHeader(x-forwarded-for);if (ip = null | ip.length() = 0 | unknown.equalsIgnoreCase(ip) ip = request.getHeader(Proxy-Client-IP);if (ip = null | ip.length() = 0 | unknown.equalsIgnoreCase(ip) ip = request.getHeader(WL-Proxy-Client-IP);if (ip = null | ip.length() = 0 | unknown.equalsIgnoreCase(ip) ip = request.getRemoteAddr();return ip;财付通：接口处理成功时，返回XML数据包，由Nt41017Response解析如下：组件名称字段含义字段名称是否必输说明Pub交易码TradeCode原样返回交易日期Date原样返回交易时间Time原样返回银行网点BankId原样返回交易发起方TradeSrc原样返回合作方编号MktCode原样返回Serial市场流水号MktSer原样返回平台流水号PlatSer平台生成Address财付通系统urlAdd2财付通接口URLSummaryInfo摘要1Summary1原样返回摘要2Summary2ReturnInfo返回码RtnCode返回信息RtnInfo中金支付：接口处理成功时，返回XML数据包，由Nt41017Response解析如下：组件名称字段含义字段名称是否必输说明Pub交易码TradeCode原样返回交易日期Date原样返回交易时间Time原样返回银行网点BankId原样返回交易发起方TradeSrc原样返回合作方编号MktCode原样返回Serial市场流水号MktSer原样返回平台流水号PlatSer平台生成Address中金网关Add2中金网关CfcaParamList信息Message使用页面form表单自动post提交到，中金网关Add2签名数据Signature中金交易码TxCode中金交易名称TxNameSummaryInfo摘要1Summary1原样返回摘要2Summary2ReturnInfo返回码RtnCode返回信息RtnInfo合作方发起财付通退款（转平台）41018使用Nt41018Request请求类组件名称字段含义字段名称是否必输说明Pub交易码TradeCode交易码，默认：41018交易日期Date当前日期，如20130601交易时间Time当前时间，如115103银行编号BankIdA13华夏银行其他保留交易发起方TradeSrc默认：I -合作方合作方编号MktCode融捷通分配给合作方Serial合作方流水号MktSer合作方系统自动生成的业务流水号欲退款订单号OTSer订单号FundAcc用户资金账号FirmId用户在融捷通注册的账号用户支付密码FundPwdTransfer充值金额TransferAmount放大100倍，例如1元，输入值100FlagInfo入金渠道Flag11财付通,其他保留订单号类型Flag20合作方订单号，1平台订单号，2财付通订单号3平台退款单号SummaryInfo摘要1Summary1摘要2Summary2默认：财付通退款申请接口处理成功时，返回XML数据包，由Nt41018Response解析如下：组件名称字段含义字段名称是否必输说明Pub交易码TradeCode原样返回交易日期Date原样返回交易时间Time原样返回银行网点BankId原样返回交易发起方TradeSrc原样返回合作方编号MktCode原样返回Serial市场流水号MktSer原样返回平台流水号PlatSer平台生成ParamList商户退款单号out_refund_no商户退款单号FlagInfo入金渠道Flag11财付通 其他保留退款订单状态Flag3-2待重发，-3待查询，8退款成功,7线下处理SummaryInfo摘要1Summary1原样返回摘要2Summary2ReturnInfo返回码RtnCode000000：成功，其余均为失败返回信息RtnInfo合作方发起渠道订单查询（转平台）41019使用Nt41019Request请求类组件名称字段含义字段名称是否必输说明Pub交易码TradeCode交易码，默认：41019交易日期Date当前日期，如20130601交易时间Time当前时间，如115103银行编号BankIdA13华夏银行其他保留交易发起方TradeSrc默认：I -合作方合作方编号MktCode融捷通分配给合作方Serial合作方流水号MktSer合作方系统自动生成的业务流水号欲退款订单号OTSer订单号FlagInfo入金渠道Flag11财付通,其他保留订单号类型Flag2入金：0合作方订单号，1平台订单号，2财付通订单号退款：3平台退款单号，4合作方退款单号SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41019Response解析如下：组件名称字段含义字段名称是否必输说明Pub交易码TradeCode原样返回交易日期Date原样返回交易时间Time原样返回银行网点BankId原样返回交易发起方TradeSrc原样返回合作方编号MktCode原样返回Serial市场流水号MktSer原样返回平台流水号PlatSer平台生成流水号OtSer查询退款时：平台退款单号FlagInfo退款订单状态Flag3入金：0初始化，1财付通交易成功未到账，9已到账，2转入退款退款：-2退款失败待重发，9退款成功SummaryInfo摘要1Summary1原样返回摘要2Summary2ReturnInfo返回码RtnCode000000：成功，其余均为失败返回信息RtnInfo合作方发起同行出金【41012】请求交易数据（报文格式）使用Nt41012Request请求类组件描述组件名称字段含义字段名称是否必输说明消息包头Pub交易码TradeCode默认“41012”交易日期Date报文上送日期交易时间Time报文上送时间银行网点BankId默认“A13”交易发起方TradeSrc默认“I”合作方编号MktCode平台分配业务流水Serial合作方流水号MarketSerial合作方系统唯一业务标识资金账户信息FundAcc资金账号FirmId平台账号客户名称CustName币种信息MoneyKind币种MoneyKind默认“CNY”资金信息Transfer出金金额TransferAmount出金金额（单位：分）摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt41012Response解析如下：组件描述组件名称字段含义字段名称是否必输说明消息包头Pub交易码TradeCode默认“41012”交易日期Date报文上送日期交易时间Time报文上送时间银行网点BankId默认“A13”交易发起方TradeSrc默认“I”合作方编号MktCode平台分配业务流水Serial合作方流水号MarketSerial合作方系统唯一业务标识平台流水号PlatSerial平台唯一业务标识资金账户信息FundAcc资金账号FirmId平台账号客户名称CustName资金信息Transfer出金金额TransferAmount本次出金金额（单位：分）资金余额CurrentBalance出金后可用余额(可出余额)（单位：分）返回信息ReturnInfo返回码RtnCode000000：成功，其余均为失败返回信息RtnInfo摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起支付交易（可透支贷）（转平台）【70001】请求交易数据（报文格式）使用Nt70001Request请求类组件描述组件名称字段含义字段名称是否必输说明消息包头Pub交易码TradeCode默认“70001”交易日期Date报文上送日期交易时间Time报文上送时间银行网点BankId默认“A13”交易发起方TradeSrc默认“I”合作方编号MktCode平台分配业务流水Serial合作方流水号MarketSerial合作方系统唯一业务标识付款方账户信息PFundAcc支付账号VaccId支付系统子账号客户名称CustName支付密码FundPwd支付系统支付密码收款方账户信息RFundAcc支付账号VaccId支付系统子账号客户名称CustName币种信息MoneyKind币种MoneyKind默认“CNY”资金信息Transfer支付金额TransferAmount（单位：分）手续费TransferCharge合作方设置支付手续费自有资金CurrentBalance本次支付自有资金设置支付标识FlagInfo交易种类Flag101：普通支付,02：确认支付,03：银联支付,04：支付退款（无手续费）,05：平台代扣,06：划拨手续费（无手续费）,07：划拨银联入金（无手续费）支付类型Flag201：支付请求,02：二次确认,03：支付回退（当Flag1=02是确认支付，Flag2必填，其他Flag1情况默认填写01）交易摘要Flag301-销售款,02-手续费,03-退款,04-利息摘要SummaryInfo摘要1Summary1摘要2Summary2接口处理成功时，返回XML数据包，由Nt70001Response解析如下：组件描述组件名称字段含义字段名称是否必输说明消息包头Pub交易码TradeCode默认“70001”交易日期Date报文上送日期交易时间Time报文上送时间银行网点BankId默认“A13”交易发起方TradeSrc默认“I”合作方编号MktCode平台分配业务流水Serial合作方流水号MarketSerial合作方系统唯一业务标识平台流水号PlatSerial平台唯一业务标识支付单号BillNo支付单号资金信息Transfer资金余额CurrentBalance冻结金额FreezeMoney贷款信息LoanInfo申请编号ReqBill优惠期天数FavDays优惠期利率FavRate计息周期IntKind1：周，2：双周，3：月，4：季(3个月)，5：半年（6个月），6：一年，7：到期结息，8：半个月贷款到期日期StopDateYYYYMMDD贷款利率LoanRate贷款账号LoanAcc贷款户名称LoanName自有资金BailMoney申请金额ApplyMon返回信息ReturnInfo返回码RtnCode000000：成功，NT9999：失败，NT9994：异常返回信息RtnInfo摘要SummaryInfo摘要1Summary1摘要2Summary2合作方发起结算账户支付交易