DB14 T 2543-2022 政府非税网上支付平台第三方接入接口规范.pdf

1、ICS35.080CCS L 7714山西省地方标准DB 14/T 25432022政府非税网上支付平台第三方接入接口规范2022-09-02 发布2022-12-01 实施山西省市场监督管理局发 布DB 14/T 25432022I目次前言.II1范围.12规范性引用文件.13术语和定义.14缩略语.15基本要求.26接口组成.3参考文献.12DB 14/T 25432022II前言本文件按照GB/T 1.12020标准化工作导则第1部分：标准化文件的结构和起草规则的规定起草。本文件由山西省财政厅提出、组织实施和监督检查。本文件由山西省市场监督管理局对标准的组织实施情况进行监督检查。本文件由

2、山西省财政标准化技术委员会(SXS/TC48)归口。本文件起草单位：山西省财政科学研究院、山西宝佳质量基础研究院。本文件主要起草人：韩慧彦、李林骏、张宝林、任巍英、王永、魏笑甜。DB 14/T 254320221政府非税网上支付平台第三方接入接口规范1范围本文件规定了政府非税网上支付平台第三方接入接口的术语和定义、缩略语、基本要求和接口组成。本文件适用于政府非税网上支付平台第三方接入接口的设计、开发和应用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用

3、于本文件。IETF RFC 3629UTF-8,ISO 10646 转换格式（UTF-8,a transformation format of ISO 10646）3术语和定义下列术语和定义适用于本文件。3.1Base64Base64 是一种基于 64 个可打印 ASCII 字符对任意字节数据进行编码的算法。3.2siteCode政府非税收入网上支付平台分配给第三方的接入编码。3.33DES三重数据加密算法，对每个数据块应用三次加密算法。3.4注册中心存储第三方 IP 地址和认证信息的服务。4缩略语下列缩略语适用于本文件。HTTP:超文本传输协议（Hyper Text Transfer Pro

4、tocol）URL:统一资源定位符（Uniform Resource Locator）DB 14/T 2543202225基本要求5.1接口协议接口协议统一采用 HTTP 协议。5.2数据结构5.2.1基本数据类型接口基本数据类型见表 1。表 1基本数据类型类型名类型描述类型约束String文本字符串内容为所有的有效字符List列表类型每一项均为一个子数据项，子数据项编码方式与父数据项编码方式相同Date日期类型日期表示为：yyyy-MM-ddFloat浮点数类型内容为浮点数类型字符Int整数类型内容为整型字符File文件流类型内容为对文件的操作定义Boolean布尔类型内容为 True 或

5、FalseTime时间类型时间表示为：yyyy-MM-dd HH:mm:ss5.2.2数据编码方式应符合 IETF RFC 3629 的规定。5.2.3数据交换格式应采用 JSON 传输数据。5.3接口调用地址应向政府非税网上支付平台获取接口调用地址及端口号。5.4安全策略5.4.1在政府非税网上支付平台与第三方互联过程中，应采取必要的通信安全措施，采用 TLS.IP 验证、数字签名、用户身份验证等方法。5.4.2应采用 Base64 加密解密保证数据在传输过程中的机密性。5.4.3宜使用 3DES、MD5 及以上算法，保证数据在传输过程中的完整性。5.4.4验证和授权通过以下两种方式进行：确

6、保相互访问的地址是可信任的，相关证书通过数字签名进行验证；DB 14/T 254320223IP 验证仅为初步验证请求来源的合法性方法。应将第三方的 IP 及相关认证信息存储至注册中心，政府非税网上支付平台在收到请求时，将请求的 IP 和系统认证信息及注册中心进行对比，确认请求源的合法性。5.4.5政府非税网上支付平台应通过请求频率和请求配额对单一请求方进行限制。5.4.6应通过数字签名校验保证数据不被篡改。6接口组成6.1接口列表政府非税网上支付平台第三方接入应支持的接口见表 2。表 2接口列表接口名称接口描述缴款书开具接口本接口用于生成非税收入缴款书，同时生成统一缴款识别码和项目识别码缴款

7、书状态查询接口本接口用于查询非税收入缴款书信息缴款书作废接口本接口用于对已经开具的缴款书进行作废（缴款书必须是未缴款状态）退付申请接口本接口用于对已缴款的缴款书进行退付申请（缴款书必须是已缴款状态）退付申请终止接口本接口用于对已提交缴款书退付申请进行终止（缴款书必须是已缴款状态并且已提交退付申请）缴款书明细查询接口本接口用于查询本单位缴款书开具明细电子票据信息接口本接口用于自动生成电子票据单位可用收费项目接口本接口用于查询第三方接入单位可用的收费项目信息跳转支付页面接口本接口用于缴款书在线支付生成支付二维码接口本接口用于生成缴款书二维码缴款书支付结果异步通知接口本接口用于缴款书支付成功后通知第

8、三方6.2缴款书开具接口缴款书开具接口见表 3。表 3缴款书开具接口接口名称缴款书开具接口接口URLhttp:/ip:port/api/issuePayment接口请求方式post请求参数DB 14/T 254320224表3缴款书开具接口（续）参数代码参数名称数据类型长度是否必填说明guid业务idString50是唯一识别码billingDate开票日期String10是yyyy-MM-dd 格式expireDate截止有效期String10否yyyy-MM-dd 格式chargeItemCount收费项目个数String10是summary摘要/备注String100否若单一收费项目中含

9、有多项收费标准，需要在此字段详细解释说明，涉及电子发票此项必填totalAmount票据总金额String20是两位小数payerName付款人名称String100是payerType缴款人类型String20是个人/企业payerId缴款人号码String20是企业:统一社会信用代码个人:身份证号contacts联系人名称String50是contactNumber联系电话String20是email邮箱地址String30否entryUser录入人员String30是开具电子发票需要entryTime录入时间String20是yyyy-MM-dd HH:mm:ss 格式auditUser

10、审核人员String30否auditTime审核时间String20否yyyy-MM-dd HH:mm:ss 格式detailData收费项目明细String是响应参数参数代码参数名称数据类型长度是否必填说明guid业务idString50是接入系统单据唯一识别码orderId订单idString50是非税唯一的订单 idpaymentId缴款识别码String20是统一缴款识别码result处理结果String100是status处理状态String10是0-成功其他-失败DB 14/T 2543202256.3缴款书状态查询接口缴款书状态查询接口见表 4。表 4缴款书状态查询接口接口名称缴

11、款书状态查询接口接口URLhttp:/ip:port/api/queryPaymentStatus接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码orderId订单idString50是非税唯一的订单 idaddTime通知书开具时间String20是yyyy-MM-dd HH:mm:ss 格auditTime通知书审核时间String20否yyyy-MM-dd HH:mm:ss 格式payStatus支付状

12、态String10是10-未支付11-支付中20-已支付payTime支付时间String20否yyyy-MM-dd HH:mm:ss 格invalidTime作废时间String20否yyyy-MM-dd HH:mm:ss 格式payAmount支付金额String20是两位小数refundAmount已退款金额String20否两位小数result处理结果String100是status处理状态String10是0-成功其他-失败6.4缴款书作废接口缴款书作废接口见表 5。DB 14/T 254320226表 5缴款书作废接口接口名称缴款书作废接口接口URLhttp:/ip:port/ap

13、i/invalidPayment接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码applyUser申请人员String30是applyTime申请时间String20是yyyy-MM-dd HH:mm:ss 格式reason作废原因String100是响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码invalidTime作废时间String20是yyyy-MM-dd HH:mm:ss 格式result处理结果String100是status处理状态Stri

14、ng10是0-成功其他-失败6.5退付申请接口退付申请接口见表 6。表 6退付申请接口接口名称退付申请接口接口URLhttp:/ip:port/api/applyRefund接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码applyUser申请人员String100是applyTime申请时间String20是yyyy-MM-dd HH:mm:ss 格式refundAmount退款金额String20是两位小数reason退款原因String100是DB 14/T 254320227表6退付申请接口（续）参数代码参

15、数名称数据类型长度是否必填说明refundType退回方式String10是退回指定账户原支付渠道退回payeeName收款人名称String100否refundType=0 时，必填payeeAccount收款人账号String50否payeeBankName收款开户行String100否payeeBankNo收款开户行行号String50否detailData退款项目明细String响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码refundId退付IDString50是result处理结果String100是status处理状态

16、String10是0-成功其他-失败6.6退付申请终止接口退付申请终止接口见表 7。表 7退付申请终止接口接口名称退付申请终止接口接口URLhttp:/ip:port/api/stopRefound接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码refundId退付IDString50是applyUser申请人员String30是applyTime申请时间String20是yyyy-MM-dd HH:mm:ss 格式reason终止原因String100是DB 14/T 254320228表7退付申请终止接口（续）

17、响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码refundId退付IDString50是result处理结果String100是status处理状态String10是0-成功其他-失败6.7缴款书明细查询接口缴款书明细查询接口见表 8。表 8缴款书明细查询接口接口名称缴款书明细查询接口接口URLhttp:/ip:port/api/queryPaymentList接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明startDate开始日期String10是endDate结束日期String10是响应参数参数代码参数名

18、称数据类型长度是否必填说明paymentId缴款识别码String20是billingDate开票日期String10是yyyy-MM-dd 格式payAmount应缴金额String20是两位小数payerName付款人名称String100是payerId缴款人号码String20是payStatus支付状态String10是10-未支付11-支付中20-已支付payTime支付时间String20否yyyy-MM-dd HH:mm:ss 格式payOrgan支付机构String100否refundAmount已退款金额String20否两位小数DB 14/T 2543202296.8电子

19、票据信息接口电子票据信息接口见表 9。表 9电子票据信息接口接口名称电子票据信息接口接口URLhttp:/ip:port/api/getElectronicBill接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码url电子票据地址String150否result处理结果String100是status处理状态String10是0-成功其他-失败6.9单位可用收费项目接口单位可用收费项目接口见表 10。表 10

20、单位可用收费项目接口接口名称单位可用收费项目接口接口URLhttp:/ip:port/api/queryChargeItems接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明siteCode接入节点代码String50是响应参数参数代码参数名称数据类型长度是否必填说明chargeItem收费项目名称String100是chargeCode收费代码String20是standardType标准类型String20否定额/开放minAmout最小金额String20否maxAmout最大金额String20否DB 14/T 25432022106.10跳转支付页面接口跳转支付页

21、面接口见表 11。表 11跳转支付页面接口接口名称跳转支付页面接口接口URLhttp:/ip:port/api/goToPay接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码deviceType终端设备类型String10是1-PC 个人电脑 2-手机终端redirectUrl回调地址String200否支付成功后的跳转地址响应参数参数代码参数名称数据类型长度是否必填说明payUrl支付页面地址String200是result处理结果String100是status处理状态String10是0-成功其他-失败6.1

22、1生成支付二维码接口生成支付二维码接口见表 12。表 12生成支付二维码接口接口名称生成支付二维码接口接口URLhttp:/ip:port/api/getPayQrCode接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码qrimage二维码图片地址String200是qrcode支付地址String200是DB 14/T 2543202211表12生成支付二维码接口（续）参数代码参数名称数据类型长度是否必填说

23、明result处理结果String100是status处理状态String10是0-成功其他-失败6.12缴款书支付结果异步通知接口缴款书支付结果异步通知接口见表 13。表 13缴款书支付结果异步通知接口接口名称缴款书支付结果异步通知接口接口URL本 URL 向政府非税网上支付平台第三方系统获取接口请求方式post请求参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码transacNo支付确认流水号String50是收单机构确认交易流水号payTime支付时间String20否yyyy-MM-dd HH:mm:ss 格式payAmount支付金额String20是两位小数响应参数参数代码参数名称数据类型长度是否必填说明paymentId缴款识别码String20是统一缴款识别码result处理结果String100是status处理状态String10是0-成功其他-失败DB 14/T 2543202212参考文献1 GB/T 2260中华人民共和国行政区划代码2 GB/T 22239信息安全技术 网络安全等级保护基本要求3 GB/T 35273信息安全技术 个人信息安全规范