ICS 35.080 CCS L 77 山 14 西 省 地 方 标 准 DB 14/T 2543—2022 政府非税网上支付平台第三方接入 接口规范 2022 - 09 - 02 发布 2022 - 12 - 01 实施 山西省市场监督管理局  发 布 DB 14/T 2543—2022 目 次 前言 .................................................................................. II 1 范围 ................................................................................ 1 2 规范性引用文件 ...................................................................... 1 3 术语和定义 .......................................................................... 1 4 缩略语 .............................................................................. 1 5 基本要求 ............................................................................ 2 6 接口组成 ............................................................................ 3 参考文献 .............................................................................. 12 I DB 14/T 2543—2022 前 言 本文件按照GB/T 1.1—2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》的规定 起草。 本文件由山西省财政厅提出、组织实施和监督检查。 本文件由山西省市场监督管理局对标准的组织实施情况进行监督检查。 本文件由山西省财政标准化技术委员会(SXS/TC48)归口。 本文件起草单位：山西省财政科学研究院、山西宝佳质量基础研究院。 本文件主要起草人：韩慧彦、李林骏、张宝林、任巍英、王永、魏笑甜。 II DB 14/T 2543—2022 政府非税网上支付平台第三方接入接口规范 1 范围 本文件规定了政府非税网上支付平台第三方接入接口的术语和定义、缩略语、基本要求和接口组成。 本文件适用于政府非税网上支付平台第三方接入接口的设计、开发和应用。 2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本 文件。 IETF RFC 3629 UTF-8,ISO 10646 转换格式（UTF-8,a transformation format of ISO 10646） 3 术语和定义 下列术语和定义适用于本文件。 3.1 Base64 Base64 是一种基于 64 个可打印 ASCII 字符对任意字节数据进行编码的算法。 3.2 siteCode 政府非税收入网上支付平台分配给第三方的接入编码。 3.3 3DES 三重数据加密算法，对每个数据块应用三次加密算法。 3.4 注册中心 存储第三方 IP 地址和认证信息的服务。 4 缩略语 下列缩略语适用于本文件。 HTTP:超文本传输协议（Hyper Text Transfer Protocol ） URL:统一资源定位符（Uniform Resource Locator） 1 DB 14/T 2543—2022 5 基本要求 5.1 接口协议 接口协议统一采用 HTTP 协议。 5.2 数据结构 5.2.1 基本数据类型 接口基本数据类型见表 1。 表1 类型名 基本数据类型 类型描述 类型约束 String 文本字符串 内容为所有的有效字符 List<> 列表类型 每一项均为一个子数据项，子数据项编码方式与父数据项编码方式相同 Date 日期类型 日期表示为： yyyy-MM-dd Float 浮点数类型 内容为浮点数类型字符 Int 整数类型 内容为整型字符 File 文件流类型 内容为对文件的操作定义 Boolean 布尔类型 内容为 True 或 False Time 时间类型 时间表示为：yyyy-MM-dd HH:mm:ss 5.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 验证和授权通过以下两种方式进行： ——确保相互访问的地址是可信任的，相关证书通过数字签名进行验证； 2 DB 14/T 2543—2022 ——IP 验证仅为初步验证请求来源的合法性方法。应将第三方的 IP 及相关认证信息存储至注册中 心，政府非税网上支付平台在收到请求时，将请求的 IP 和系统认证信息及注册中心进行对比， 确认请求源的合法性。 5.4.5 政府非税网上支付平台应通过请求频率和请求配额对单一请求方进行限制。 5.4.6 应通过数字签名校验保证数据不被篡改。 6 接口组成 6.1 接口列表 政府非税网上支付平台第三方接入应支持的接口见表 2。 表2 接口列表 接口名称 接口描述 缴款书开具接口 本接口用于生成非税收入缴款书，同时生成统一缴款识别码和项目识别码 缴款书状态查询接口 本接口用于查询非税收入缴款书信息 缴款书作废接口 本接口用于对已经开具的缴款书进行作废（缴款书必须是未缴款状态） 退付申请接口 本接口用于对已缴款的缴款书进行退付申请（缴款书必须是已缴款状态） 本接口用于对已提交缴款书退付申请进行终止（缴款书必须是已缴款状态并且已提 退付申请终止接口 交退付申请） 缴款书明细查询接口 本接口用于查询本单位缴款书开具明细 电子票据信息接口 本接口用于自动生成电子票据 单位可用收费项目接口 本接口用于查询第三方接入单位可用的收费项目信息 跳转支付页面接口 本接口用于缴款书在线支付 生成支付二维码接口 本接口用于生成缴款书二维码 缴款书支付结果异步通知接口 本接口用于缴款书支付成功后通知第三方 6.2 缴款书开具接口 缴款书开具接口见表 3。 表3 缴款书开具接口 接口名称 缴款书开具接口 接口URL http://ip:port/api/issuePayment 接口请求方式 post 请求参数 3 DB 14/T 2543—2022 表3 参数代码 参数名称 缴款书开具接口（续） 数据类型 长度 是否必填 说明 guid 业务id String 50 是 唯一识别码 billingDate 开票日期 String 10 是 yyyy-MM-dd 格式 expireDate 截止有效期 String 10 否 yyyy-MM-dd 格式 String 10 是 chargeItemCount 收费项目个数 若单一收费项目中含有多项收费标准，需要 summary 摘要/备注 String 100 否 在此字段详细解释说明，涉及电子发票此项 必填 totalAmount 票据总金额 String 20 是 两位小数 payerName 付款人名称 String 100 是 payerType 缴款人类型 String 20 是 payerId 缴款人号码 String 20 是 contacts 联系人名称 String 50 是 contactNumber 联系电话 String 20 是 email 邮箱地址 String 30 否 entryUser 录入人员 String 30 是 开具电子发票需要 entryTime 录入时间 String 20 是 yyyy-MM-dd HH:mm:ss 格式 auditUser 审核人员 String 30 否 auditTime 审核时间 String 20 否 detailData 收费项目明细 String 个人/企业 企业:统一社会信用代码 个人:身份证号 yyyy-MM-dd HH:mm:ss 格式 是 响应参数 参数代码 参数名称 数据类型 长度 是否必填 说明 guid 业务id String 50 是 接入系统单据唯一识别码 orderId 订单id String 50 是 非税唯一的订单 id paymentId 缴款识别码 String 20 是 统一缴款识别码 result 处理结果 String 100 是 status 处理状态 String 10 是 4 0-成功 其他-失败 DB 14/T 2543—2022 6.3 缴款书状态查询接口 缴款书状态查询接口见表 4。 表4 缴款书状态查询接口 接口名称 缴款书状态查询接口 接口URL http://ip:port/api/queryPaymentStatus 接口请求方式 post 请求参数 参数代码 paymentId 参数名称 缴款识别码 数据类型 长度 是否必填 String 20 是 说明 统一缴款识别码 响应参数 参数代码 参数名称 数据类型 长度 是否必填 说明 paymentId 缴款识别码 String 20 是 统一缴款识别码 order