境内外币支付系统直联接口API使用手册.doc

境内外币支付系统直联接口API使用手册 附件一：境内外币支付系统直联接口API使用手册境内外币支付系统直联接口API使用手册V1.4中国人民银行科技司二八年四月- 1 -境内外币支付系统直联接口API使用手册 目录1编写目的42适用对象43支持平台及中间件44使用说明44.1外币业务流程说明44.2直联行往帐发起流程说明54.3往账发送处理流程图64.4直联行来帐接收流程说明64.5来账接收（普通报文）流程图74.6来账接收（实时报文）流程84.7限定和约束85直联接口API函数说明（C语言版本）85.1API函数清单85.2API函数说明95.2.1发送报文函数95.2.2接收报文函数95.2.3提交事务函数105.2.4回滚事务函数105.2.5获得错误代码及描述函数116安装过程136.1安装准备136.2安装步骤136.3安装验证147开发环境说明157.1头文件157.2编译方法157.3makefile文件示例167.3.1AIX平台的makefile167.3.2SUSE Linux平台makefile178运行环境说明198.1目录结构198.2配置文件218.3环境变量218.4AIX平台动态库文件228.4.1库文件清单228.4.2操作步骤228.5SUSE Linux平台228.5.1库文件清单228.5.2操作步骤228.6签名串文件*.dat生成过程23版本修改记录：版本号完成日期简单描述1.02007-12-25C正式发布版。1.12008-1-9无修改。1.22008-1-29M6.3节安装验证内容更新。M8.1节目录结构内容更新。A增加8.6节签名串文件生成过程。1.32008-3-31M5.2.5获取错误代码及描述函数的表格中增加错误码及描述：0243优先级子块错误 和0242打开PKIBANK文件错误1.42008-4-18未修改说明：C-创建；M-修改；A-增加；D-删除；1 编写目的本文档是境内外币支付系统与结算银行账户处理系统接口规范和境内外币支付系统与商业银行行内系统接口规范的附件，主要描述了直联接口API的使用方法。目的是指导结算银行和商业银行的开发人员依据此手册完成接入境内外币支付系统行内部分的系统改造工作。本接口规范的期望读者包括：结算银行和商业银行的技术开发人员及其他相关人员。2 适用对象本接口API只适用于所有Q-Q直联方式接入境内外币支付系统的直接（特许）参与者使用。3 支持平台及中间件目前直联接口API支持操作系统平台为：1、64或32 bit AIX5.3。2、32 bit SUSE Linux9.0支持的中间件产品为：1、 MQ6.02、 TongLink/Q6.3说明：AIX平台的接口API 连接32 bit 中间件MQ库。4 使用说明为了方便Q-Q直联方式接入的直接（特许）参与者发起和接收外币支付系统业务报文，并为了提高系统安全性，特提供直联接口API函数完成报文的发送和接收功能。该API完成了对操作消息中间件的封装，并对报文进行了初步的合法性检查，且增加了报文的身份验证码，由境内外币支付系统业务处理中心（FXCC）验证身份码的合法性，对非通过接口API发送的往帐报文予以拒绝。直联行通过消息中间件接入外币支付系统的FXCC，直联行通过调用API发起和接收外币业务报文。4.1 外币业务流程说明假如直联行A向直联行B发起一笔境内跨行贷记业务（FMT100）报文。如下图所示：1、 A行发起：A行组织好业务报文，先调用加签名函数生成签名串附加在报文中的第六块，再调用接口API发送报文函数对报文进行合法性检查、加身份验证码并放入发送队列，更加详细的报文格式请参照境内外币支付系统报文格式标准。2、 FXCC验证：FXCC从队列中得到A行发起的报文FMT100，进行身份验证（校验第7块：身份验证码），验证失败，直接丢弃报文，验证通过进行后续业务处理并转发该报文到报文接收行B行的接收队列。3、 B行接收：B行调用API接收函数，从接收队列得到报文串，并进行身份验证（校验第7块：身份验证码），并返回行内系统应用验证结果，验证失败则丢弃报文，验证成功的继续调用核签函数进行核签，根据核签结果做后续处理。说明：图中黄色标识模块为接口API需要完成的工作。4.2 直联行往帐发起流程说明1、 发起方（发起行行内系统）根据要求组织相应报文串并加数字签名后得到待发送的报文串（报文串包括：1:基本头2:应用头3:用户头4:正文5:附加正文6:签名）。2、 发起方调用API：发送报文函数 CFXPS_SENDMSG(const char *pSendMsg);完成将待发送的报文进行合法性检查、加身份验证码（添加身份验证码后的报文串包括：1:基本头2:应用头3:用户头4:正文5:附加正文6:签名7:身份验证串）和放入发送队列，根据返回码做相应处理：发送报文失败转4，并调用5获取错误码，成功则转3继续处理。3、 发起方调用API：提交事务函数 int CFXPS_COMMIT()提交交易；4、 发起方调用API：回滚事务函数 int CFXPS_ROLLBACK()回滚交易。5、 发送方调用API：获取错误码及错误描述 char* STDCALL CFXPS_GETERRDESC();如果发送方在发送报文返回值不等于0（即发送失败），调用该函数获取错误码及错误描述，以便分析失败的原因。4.3 往账发送处理流程图4.4 直联行来帐接收流程说明1、 接收方（接收行行内系统）需要接收实时来帐报文时调用API：接收报文函数 long CFXPS_RECVMSG(int nMsgType, char *ppRecvMsg)从中间件顺序取得一笔待接收的实时来账报文（入参nMsgType=0时表示接收实时来账），取报文成功并对报文进行合法性检查和身份验证通过，则返回接收报文实际长度（返回值）和接收报文串的地址（ppRecvMsg）（返回报文结构为1:基本头2:应用头3:用户头4:正文5:附加正文6:签名）并转4，否则继续。2、 接收方（接收行行内系统）需要接收普通来帐报文时调用API：接收报文函数 long CFXPS_RECVMSG(int nMsgType, char *ppRecvMsg)从中间件顺序取得一笔待接收的普通来账报文（入参nMsgType=1时表示接收普通来账），取报文成功并对报文进行合法性检查和身份验证通过，则返回接收报文实际长度和接收报文串（ppRecvMsg）（1:基本头2:应用头3:用户头4:正文5:附加正文6:签名）并转4，否则继续。3、 如果接收报文失败（返回值小于0），则转5，并调用6获取错误码，依据错误码描述分析原因。再次调用API：接收报文函数 CFXPS_RECVMSG(int nMsgType, char *ppRecvMsg)从中间件重新取得该报文，成功则转3继续。4、 接收方调用API：提交事务函数 int CFXPS_COMMIT()提交交易；5、 接收方调用API：回滚事务函数 int CFXPS_ROLLBACK ()回滚交易。6、 接收方调用API：获取错误码 char* CFXPS_GETERRDESC();如果接收方在接收报文时返回值不等0，调用该函数获取错误码详细说明，以便检查失败的原因。4.5 来账接收（普通报文）流程图4.6 来账接收（实时报文）流程4.7 限定和约束1、 本API已经封装了中间件产品MQ和TLQ的操作函数，无需商业银行直接操作MQ和TLQ。2、 发送或接收API报文大小有条件约束，报文的大小最大不能超过50M。对1M以下的报文系统直接处理，对于1M以上，50M以下的报文，采用了MQ/TLQ的系统分片功能自动分片，默认配置的分片大小为1M。可以调用API直接进行发送，由MQ/TLQ系统自身判断超长并自动分片；接收方可以直接调用API进行大报文的接收，API会返回拼装好的大报文给行内系统应用。接收API函数内部申请存储区获取到报文后，将存储区的地址（char *ppRecvMsg）返回给商业银行，商业银行应用可以直接读取该存储区的报文信息，但注意不能破坏此存储区内容。3、 目前支持的API为C语言编写的静态库(AIX)/和动态库(SUSE LINUX)。4、 本API支持多进程调用，暂不支持多线程调用。5 直联接口API函数说明（C语言版本）5.1 API函数清单类别函数名称业务功能触发方式备注FXAPICFXPS_SENDMSG此函数完成商业银行向FXCC发送往账报文。直联行调用CFXPS_RECVMSG此函数完成商业银行从FXCC接收来账报文。直联行调用CFXPS_COMMIT此函数完成发送报文函数和接收报文函数的提交。直联行调用CFXPS_ROLLBACK此函数完成发送报文函数和接收报文函数的回滚。直联行调用CFXPS_GETERRDESC此函数获取发送和接收报文错误码及原因。直联行调用说明：5.2 API函数说明5.2.1 发送报文函数【函数原型】 int CFXPS_SENDMSG(const char *pSendMsg);【函数功能】此函数完成商业银行向FXCC发送往账报文。【函数参数】参数1：pSendMsg （输入）-待发送的报文串。【返回值说明】返回代码描述0发送成功-1初始化API环境失败-2创建日志文件失败-3获取报文输入输出标识失败-4报文合法性检查失败-5加编身份认证码失败-6获取报文的ID失败-7写队列操作失败-8发送报文异常【返回码表】 无，详细错误码和错误描述请立即调用CFXPS_GETERRDESC()函数获取。【调用说明】商业银行应用需要发送往帐报文时使用，对需要加数字签名的报文应该加好数字签名后才调用此函数进行发送。5.2.2 接收报文函数【函数原型】long CFXPS_RECVMSG(int nMsgType, char *ppRecvMsg);【函数功能】此函数完成商业银行从FXCC接收来账报文。【函数参数】： 参数1：nMsgType（输入）- 0-实时报文，1-普通报文。参数2：ppRecvMsg（输出）-输出报文存放的存储区的地址，定义为指针的指针。【返回值说明】返回代码描述0接收成功,返回接收到的报文长度0无待接收报文-1初始化API环境失败-2创建日志文件失败-3读队列操作失败-4接收异常【返回码表】无，详细错误码和错误描述请立即调用CFXPS_GETERRDESC()函数获取。【调用说明】1、 商业银行需要接收实时和普通来账报文时使用该函数。2、 对实时报文和普通报文要分别调用此函数获得。3、 此函数内部申请存储区并将获取到的报文存入此存储区，并将存储区的地址（char *ppRecvMsg）返回给商业银行，商业银行应用程序可以直接读取该存储区的报文信息，但注意不能破坏此存储区内容。5.2.3 提交事务函数【函数原型】int CFXPS_COMMIT();【函数功能】此函数完成发送报文函数和接收报文函数的提交。【函数参数】参数：无【返回值说明】返回代码描述0事务提交成功-1事务提交失败【返回码表】无【调用说明】正常情况下应返回成功，如果返回失败，则是队列管理器出现异常，请检查MQ6.0/TLQ6.3运行情况。5.2.4 回滚事务函数【函数原型】int CFXPS_ROLLBACK();【函数功能】此函数完成发送报文函数和接收报文函数的提交。【函数参数】 无【返回值说明】返回代码描述0事务回滚成功-1事务回滚失败【返回码表】无【调用说明】正常情况下应返回成功，如果返回失败，则是队列管理器出现异常，请检查MQ6.0/TLQ运行情况。5.2.5 获得错误代码及描述函数【函数原型】char* CFXPS_GETERRDESC();【函数功能】此函数完成发送报文函数和接收报文函数的返回值小于0时，调用该函数获取错误代码及描述，根据错误码及描述分析原因。【函数参数】 无【返回值说明】返回字符串的指针。【返回码表】错误代码错误描述0000成功0999失败0101读系统配置文件错误0102参数队列管理器名错误0103参数队列名错误0104参数日志路径名错误0105参数日志级别错误0106加载TAG文件错误0107加载ITEM文件错误0108加载VAL文件错误0109创建日志目录失败0110无效报文0111发送报文超长0112队列管理器已断开或队列已关闭0113打开或关闭队列错误0114开始事务错误0115参数CFCA路径名错误0116核数字签名错误0117初始化环境抛出错误0118发送报文抛出错误0119接收报文抛出错误0120业务检查报文抛出错误0201缺少报文第1块0202缺少报文第2块0203缺少报文第3块0212缺少报文第6块0210缺少报文第7块0204SWIF报文字符集检查错误0205发起行没有权限发起该报文0206发送报文加编身份认证错误0207报文没有包含认证信息被自动拒绝0208身份认证核报文第七块不一致0209接收报文输入参数错误0211节点号码与证书DN号码不同0243优先级子块错误0213转汇业务子块集错误0214退汇业务子块集错误0215数字签名证书非法0216报文的第三块FMTCode与配置文件报文列表不一致0217报文的第二块MTCode与配置文件报文列表不一致0218报文的第二块输入输出标识错误0219计算发起行行号+任务号+消息序号错误0220第五块(附加正文块)支付业务及结算业务子块集错误0221检查FMT011报文明细清单错误0222检查FMT012报文明细清单错误0223检查FMT041报文明细清单错误0224检查FMT073报文明细清单错误0225检查FMT082报文明细清单错误0226检查FMT083报文明细清单错误0227检查FMT084报文明细清单错0228检查FMT085报文明细清单错误0229检查FMT016报文明细清单错误0230检查FMT026报文明细清单错误0231检查FMT027报文明细清单错误0232检查FMT021报文明细清单错误0233检查FMT032报文明细清单错误0234检查FMT061报文明细清单错误0235检查FMT062报文明细清单错误0236检查FMT070报文明细清单错误0237检查FMT072报文明细清单错误0238检查FMT080报文明细清单错误0239检查FMT081报文明细清单错误0240检查FMT086报文明细清单错误0241检查FMT089报文明细清单错误0242打开PKIBANK文件错误【调用说明】此函数用于获取详细的操作错误码和错误描述，应该在调用以上四个函数的任何一个后，如出现错误，应立即调用此函数获取详细错误码和错误描述。6 安装过程6.1 安装准备提供安装程序包，安装文件如下：平台文件名称说明AIXinstallSle.shSuSe平台安装执行文件setupSle.tar SuSe平台文件包SUSE LinuxinstallAIX.shAIX平台安装执行文件setupAIX.tarAIX平台文件包6.2 安装步骤AIX平台操作方法：1. 用普通用户登录系统2. 把安装包中两个文件：installAIX.sh（通过ASCII方式）和setupAIX.tar（通过BIN方式），通过FTP上传到需要安装的目录，例如/fxapi目录下。3. 增加文件installAIX.sh的执行权限：$chmod +x installAIX.sh4. 执行installSle.sh程序进行开始安装. 具体操作如下：$./installAIX.shSUSE平台操作方法：1. 用普通用户登录系统2. 把安装包中两个文件：installSle.sh（通过ASCII方式）和setupSle.tar（通过BIN方式），通过FTP上传到需要安装的目录，例如/fxapi目录下。3. 增加文件installSle.sh的执行权限：$chmod +x installSle.sh4. 执行installSle.sh程序进行开始安装. 具体操作如下：$./installSle.sh6.3 安装验证安装完成后请检查安装目录下的文件是否与如下列表中的文件清单相符：所属节点名一级目录文件清单说明FXAPIfxapi.ini配置文件etcSWF.struSwif报文定义文件，二进制格式，AIX5.3及SUSE Linux9.0平台文件名字一致，但有平台之分。TAG.struTAG码定义文件，二进制格式，AIX5.3及SUSE Linux9.0平台文件名字一致，但有平台之分。common.err错误码及描述文件，文本格式，AIX5.3及SUSE Linux9.0平台通用。tagval.dat特定变量定义检查文件，文本格式，AIX5.3及SUSE Linux9.0平台通用。BJCNCNBJXXX.pfx证书文件cfca.p7b证书链文件cfca.crl证书注销列表apiabout.txtAPI关于文件apiaboutAPI版本信息更新程序liblibcapi.soCFCA证书使用（AIX平台）libcfcatoolkit.soCFCA证书使用（AIX平台）libmqfxapi.aAPI基于MQ（AIX平台）libtlqfxapi.aAPI 基于TLQ（AIX平台）libcnccFXCCsle9.so报文处理（SuSE平台）libmqFXCCsle9.soMQ使用（SuSE平台）libtlqFXCCsle9.soTLQ使用（SuSE平台）libcfcaFXCCsle9.soCFCA证书使用（SuSE平台）libcfcatoolkit.soCFCA证书使用（SuSE平台）libcapi.soCFCA证书使用（SuSE平台）libmqfxapi.soAPI基于MQ（SuSE平台）libtlqfxapi.soAPI 基于TLQ（SuSE平台）includecfxpsapi.hpp头文件7 开发环境说明7.1 头文件cfxpsapi.hpp说明：在开发环境下，把这个头文件拷贝到所在的开发环境。7.2 编译方法1 在使用静态或动态库时，在用户的工程中包含cfxpsapi.hpp的头文件。2 在AIX平台中，makefile 文件中要包含链接的静态库libmqfxapi.a（MQ使用）或libtlqfxapi.a（TLQ使用），以及动态库libcapi.so、libcfcatoolkit.so，同时要链接中间件(MQ或TLQ)库；3 在SUSE Linux平台中，makefile 文件中要包含链接的动态库（见下表格）同时要链接中间件(MQ或TLQ)库。序号库文件描述1libcnccFXCCsle9.so报文处理2libmqFXCCsle9.soMQ使用3libtlqFXCCsle9.soTLQ使用4libcfcaFXCCsle9.soCFCA证书使用5libcfcatoolkit.soCFCA证书使用6libcapi.soCFCA证书使用7.libmqfxapi.soAPI基于MQ8libtlqfxapi.soAPI 基于TLQ 7.3 makefile文件示例7.3.1 AIX平台的makefilemakefile文件仅供参考。# Makefile for Common Library. Version 1.0 build 2007-09-10# # Copyright 2006-2007, CNCC/DC# 外币清算系统公共库编译单元# # Custom defines#FXAPI_NAME = fxapiFXCC_HOME = /home/FXAPI/exampleFXCCPUB_HOME = $(FXCC_HOME)/libFXCC_INCS = -I$(FXCC_HOME)/include -I.FXCC_LIBMQS = -L$(FXCCPUB_HOME) -lmq$(FXAPI_NAME) -ldlFXCC_LIBTLQS = -L$(FXCCPUB_HOME) -ltlq$(FXAPI_NAME) -ldlCFCA_LIBS = /usr/lib/libcfcatoolkit.so# Compiler and Linker#CC = xlC_rCCS = /usr/vacpp/bin/makeC+SharedLib# IBM MQ#MQ_HOME =MQ_OPTS =MQ_INCS =MQ_LIBS = -lmqm_r# TongLink/Q#TLQ_HOME = /usr/tlq/TLQ63TLQ_OPTS =TLQ_INCS = -I$(TLQ_HOME)/inclTLQ_LIBS = /usr/lib/libtlqapi.so# PUBLIC rule for build all file#.SUFFIXES: .pc .sqC .ccs .cpp .C .o .ibmcpp .so.cpp.o:$(CC) $(FXCC_INCS) -c $# Where to find the sourceVPATH = .all: clean apitestclean:-rm *.oapitest: $(FXCC_HOME)/simain/apitest.o-rm $(FXCC_HOME)/simain/apitest$(CC) -o $(FXCC_HOME)/simain/$ apitest.o $(MQ_LIBS) $(FXCC_LIBMQS) $(CFCA_LIBS)#$(CC) -o $(FXCC_HOME)/simain/$ apitest.o $(TLQ_LIBS) $(FXCC_LIBTLQS) $(CFCA_LIBS) 7.3.2 SUSE Linux平台makefilemakefile文件仅供参考。# Makefile for Common Library. Version 1.0 build 2007-09-10# # Copyright 2006-2007, CNCC/DC# 外币清算系统公共库编译单元# # Custom defines#FXAPI_NAME = fxapiFXCC_HOME = /home/fxapi/exampleFXCCPUB_HOME = $(FXCC_HOME)/libFXCC_INCS = -I$(FXCC_HOME)/includeFXCC_LIBMQS = -L$(FXCCPUB_HOME) -lmq$(FXAPI_NAME) -lmqFXCCsle9 -lcfcaFXCCsle9 -lcnccFXCCsle9FXCC_LIBTLQS = -L$(FXCCPUB_HOME) -ltlq$(FXAPI_NAME) -ltlqFXCCsle9 -lcfcaFXCCsle9 -lcnccFXCCsle9CFCA_LIBS = /usr/lib/libcfcatoolkit.so# Compiler and Linker#CC = g+ -fPIC -Wall CCS = g+ -shared -Wall #CFCA_LIBS = /usr/lib/libcfcatoolkit.so /usr/lib/libcfca$(PUBLIB_APPNAME)$(PUBLIB_SYSNAME).so# IBM MQ#MQ_HOME =MQ_OPTS =MQ_INCS =MQ_LIBS = -lmqm_r# TongLink/Q#TLQ_HOME = /usr/tlq/TLQ63TLQ_OPTS =TLQ_INCS = -I$(TLQ_HOME)/inclTLQ_LIBS = /usr/lib/libtlqapi.so# PUBLIC rule for build all file#.SUFFIXES: .pc .sqC .ccs .cpp .C .o .ibmcpp .so.cpp.o:$(CC) $(FXCC_INCS) -c $# Where to find the sourceVPATH = .all: clean apitestclean:-rm *.oapitest: $(FXCC_HOME)/apitest/apitest.o-rm $(FXCC_HOME)/apitest/apitest$(CC) -o $(FXCC_HOME)/apitest/$ apitest.o $(MQ_LIBS) $(FXCC_LIBMQS) $(CFCA_LIBS)8 运行环境说明8.1 目录结构AIX与SUSE Linux平台运行目录结构相同。所属节点名一级目录文件清单说明FXAPIfxapi.ini配置文件etcSWF.struSwif报文定义文件，二进制格式，AIX5.3及SUSE Linux9.0平台文件名字一致，但有平台之分。TAG.struTAG码定义文件，二进制格式，AIX5.3及SUSE Linux9.0平台文件名字一致，但有平台之分。common.err错误码及描述文件，文本格式，AIX5.3及SUSE Linux9.0平台通用。tagval.dat特定变量定义检查文件，文本格式，AIX5.3及SUSE Linux9.0平台通用。cfca.p7b证书链文件cfca.crl证书注销列表apiabout.txtAPI关于文件apiaboutAPI版本信息更新程序8.2 配置文件配置文件为：fxapi.ini，其配置内容如下：SystemMqServer = QMABC /*MQ管理器名字*/TLQProgramNo = 100/*TLQ程序号码，根据TLQ安装目录配置文件TongUser.Conf修改*/SendRealQueue = TOFXCC_2/*发送实时队列名字*/SendCommQueue = TOFXCC_1/*发送普通队列名字*/RecvRealQueue = FROMFXCC_2/*接收实时队列名字*/RecvCommQueue = FROMFXCC_1/*接收普通队列名字*/PkiFmtList = 100&101&102&103&104&200&201&202&203&204&011&012&014&041&045&046&047&048&088&089LogLevel = 8NodeCode = BNKBCNBJXXX;/*本节点代码，可根据自己代码修改*/LogPath = $(FXAPIHOME)/logcommon.err = $(FXAPIHOME)/etc/common.errswfdef.dat = $(FXAPIHOME)/etc/SWF.strutagdef.dat = $(FXAPIHOME)/etc/TAG.strutagval.dat = $(FXAPIHOME)/etc/tagval.datpkibank.dat = $(FXAPIHOME)/etc/CFCAP7BFile = $(FXAPIHOME)/etc/cfca.p7bCFCACRLFile = $(FXAPIHOME)/etc/cfca.crlFMTandMTFMT=100;103|101;103|102;103|103;103|104;103|191;192|193;192|195;195|196;196|192;196|194;196|010;198|011;198|012;198|013;198|014;198|015;198|016;198|020;198|021;198|023;198|024;198|025;198|026;198|027;198|031;198|032;198|033;198|034;198|040;198|041;198|042;198|043;198|044;198|045;198|046;198|047;198|048;198|049;198|060;198|061;198|062;198|063;198|064;198|065;198|066;198|067;198|068;198|070;198|071;198|072;198|073;198|074;198|080;198|081;198|082;198|083;198|084;198|085;198|086;198|087;198|088;198|089;198|199;199|200;202|201;202|202;202|204;202|203;203|920;92