DB14-T2543-2022政府非稅網(wǎng)上支付平臺第三方接入接口規(guī)范

DB14/T2543—2022

政府非稅網(wǎng)上支付平臺第三方接入接口規(guī)范

1范圍

本文件規(guī)定了政府非稅網(wǎng)上支付平臺第三方接入接口的術(shù)語和定義、縮略語、基本要求和接口組成。

本文件適用于政府非稅網(wǎng)上支付平臺第三方接入接口的設(shè)計(jì)、開發(fā)和應(yīng)用。

2規(guī)范性引用文件

下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，

僅該日期對應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本

文件。

IETFRFC3629UTF-8,ISO10646轉(zhuǎn)換格式（UTF-8,atransformationformatofISO10646）

3術(shù)語和定義

下列術(shù)語和定義適用于本文件。

3.1

Base64

Base64是一種基于64個(gè)可打印ASCII字符對任意字節(jié)數(shù)據(jù)進(jìn)行編碼的算法。

3.2

siteCode

政府非稅收入網(wǎng)上支付平臺分配給第三方的接入編碼。

3.3

3DES

三重?cái)?shù)據(jù)加密算法，對每個(gè)數(shù)據(jù)塊應(yīng)用三次加密算法。

3.4

注冊中心

存儲第三方IP地址和認(rèn)證信息的服務(wù)。

4縮略語

下列縮略語適用于本文件。

HTTP:超文本傳輸協(xié)議（HyperTextTransferProtocol）

URL:統(tǒng)一資源定位符（UniformResourceLocator）

1

DB14/T2543—2022

5基本要求

5.1接口協(xié)議

接口協(xié)議統(tǒng)一采用HTTP協(xié)議。

5.2數(shù)據(jù)結(jié)構(gòu)

5.2.1基本數(shù)據(jù)類型

接口基本數(shù)據(jù)類型見表1。

表1基本數(shù)據(jù)類型

類型名類型描述類型約束

String文本字符串內(nèi)容為所有的有效字符

List<>列表類型每一項(xiàng)均為一個(gè)子數(shù)據(jù)項(xiàng)，子數(shù)據(jù)項(xiàng)編碼方式與父數(shù)據(jù)項(xiàng)編碼方式相同

Date日期類型日期表示為：yyyy-MM-dd

Float浮點(diǎn)數(shù)類型內(nèi)容為浮點(diǎn)數(shù)類型字符

Int整數(shù)類型內(nèi)容為整型字符

File文件流類型內(nèi)容為對文件的操作定義

Boolean布爾類型內(nèi)容為True或False

Time時(shí)間類型時(shí)間表示為：yyyy-MM-ddHH:mm:ss

5.2.2數(shù)據(jù)編碼方式

應(yīng)符合IETFRFC3629的規(guī)定。

5.2.3數(shù)據(jù)交換格式

應(yīng)采用JSON傳輸數(shù)據(jù)。

5.3接口調(diào)用地址

應(yīng)向政府非稅網(wǎng)上支付平臺獲取接口調(diào)用地址及端口號。

5.4安全策略

5.4.1在政府非稅網(wǎng)上支付平臺與第三方互聯(lián)過程中，應(yīng)采取必要的通信安全措施，采用TLS.IP驗(yàn)證、

數(shù)字簽名、用戶身份驗(yàn)證等方法。

5.4.2應(yīng)采用Base64加密解密保證數(shù)據(jù)在傳輸過程中的機(jī)密性。

5.4.3宜使用3DES、MD5及以上算法，保證數(shù)據(jù)在傳輸過程中的完整性。

5.4.4驗(yàn)證和授權(quán)通過以下兩種方式進(jìn)行：

——確保相互訪問的地址是可信任的，相關(guān)證書通過數(shù)字簽名進(jìn)行驗(yàn)證；

2

DB14/T2543—2022

——IP驗(yàn)證僅為初步驗(yàn)證請求來源的合法性方法。應(yīng)將第三方的IP及相關(guān)認(rèn)證信息存儲至注冊中

心，政府非稅網(wǎng)上支付平臺在收到請求時(shí)，將請求的IP和系統(tǒng)認(rèn)證信息及注冊中心進(jìn)行對比，

確認(rèn)請求源的合法性。

5.4.5政府非稅網(wǎng)上支付平臺應(yīng)通過請求頻率和請求配額對單一請求方進(jìn)行限制。

5.4.6應(yīng)通過數(shù)字簽名校驗(yàn)保證數(shù)據(jù)不被篡改。

6接口組成

6.1接口列表

政府非稅網(wǎng)上支付平臺第三方接入應(yīng)支持的接口見表2。

表2接口列表

接口名稱接口描述

繳款書開具接口本接口用于生成非稅收入繳款書，同時(shí)生成統(tǒng)一繳款識別碼和項(xiàng)目識別碼

繳款書狀態(tài)查詢接口本接口用于查詢非稅收入繳款書信息

繳款書作廢接口本接口用于對已經(jīng)開具的繳款書進(jìn)行作廢（繳款書必須是未繳款狀態(tài)）

退付申請接口本接口用于對已繳款的繳款書進(jìn)行退付申請（繳款書必須是已繳款狀態(tài)）

本接口用于對已提交繳款書退付申請進(jìn)行終止（繳款書必須是已繳款狀態(tài)并且已提

退付申請終止接口

交退付申請）

繳款書明細(xì)查詢接口本接口用于查詢本單位繳款書開具明細(xì)

電子票據(jù)信息接口本接口用于自動(dòng)生成電子票據(jù)

單位可用收費(fèi)項(xiàng)目接口本接口用于查詢第三方接入單位可用的收費(fèi)項(xiàng)目信息

跳轉(zhuǎn)支付頁面接口本接口用于繳款書在線支付

生成支付二維碼接口本接口用于生成繳款書二維碼

繳款書支付結(jié)果異步通知接口本接口用于繳款書支付成功后通知第三方

6.2繳款書開具接口

繳款書開具接口見表3。

表3繳款書開具接口

接口名稱繳款書開具接口

接口URLhttp://ip:port/api/issuePayment接口請求方式post

請求參數(shù)

3

DB14/T2543—2022

表3繳款書開具接口（續(xù)）

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

guid業(yè)務(wù)idString50是唯一識別碼

billingDate開票日期String10是yyyy-MM-dd格式

expireDate截止有效期String10否yyyy-MM-dd格式

chargeItemCount收費(fèi)項(xiàng)目個(gè)數(shù)String10是

若單一收費(fèi)項(xiàng)目中含有多項(xiàng)收費(fèi)標(biāo)準(zhǔn)，需要

summary摘要/備注String100否在此字段詳細(xì)解釋說明，涉及電子發(fā)票此項(xiàng)

必填

totalAmount票據(jù)總金額String20是兩位小數(shù)

payerName付款人名稱String100是

payerType繳款人類型String20是個(gè)人/企業(yè)

企業(yè):統(tǒng)一社會信用代碼

payerId繳款人號碼String20是

個(gè)人:身份證號

contacts聯(lián)系人名稱String50是

contactNumber聯(lián)系電話String20是

email郵箱地址String30否

entryUser錄入人員String30是開具電子發(fā)票需要

entryTime錄入時(shí)間String20是yyyy-MM-ddHH:mm:ss格式

auditUser審核人員String30否

auditTime審核時(shí)間String20否yyyy-MM-ddHH:mm:ss格式

detailData收費(fèi)項(xiàng)目明細(xì)String是

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

guid業(yè)務(wù)idString50是接入系統(tǒng)單據(jù)唯一識別碼

orderId訂單idString50是非稅唯一的訂單id

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

4

DB14/T2543—2022

6.3繳款書狀態(tài)查詢接口

繳款書狀態(tài)查詢接口見表4。

表4繳款書狀態(tài)查詢接口

接口名稱繳款書狀態(tài)查詢接口

接口URLhttp://ip:port/api/queryPaymentStatus接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

orderId訂單idString50是非稅唯一的訂單id

addTime通知書開具時(shí)間String20是yyyy-MM-ddHH:mm:ss格

auditTime通知書審核時(shí)間String20否yyyy-MM-ddHH:mm:ss格式

10-未支付

payStatus支付狀態(tài)String10是11-支付中

20-已支付

payTime支付時(shí)間String20否yyyy-MM-ddHH:mm:ss格

invalidTime作廢時(shí)間String20否yyyy-MM-ddHH:mm:ss格式

payAmount支付金額String20是兩位小數(shù)

refundAmount已退款金額String20否兩位小數(shù)

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.4繳款書作廢接口

繳款書作廢接口見表5。

5

DB14/T2543—2022

表5繳款書作廢接口

接口名稱繳款書作廢接口

接口URLhttp://ip:port/api/invalidPayment接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

applyUser申請人員String30是

applyTime申請時(shí)間String20是yyyy-MM-ddHH:mm:ss格式

reason作廢原因String100是

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

invalidTime作廢時(shí)間String20是yyyy-MM-ddHH:mm:ss格式

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.5退付申請接口

退付申請接口見表6。

表6退付申請接口

接口名稱退付申請接口

接口URLhttp://ip:port/api/applyRefund接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

applyUser申請人員String100是

applyTime申請時(shí)間String20是yyyy-MM-ddHH:mm:ss格式

refundAmount退款金額String20是兩位小數(shù)

reason退款原因String100是

6

DB14/T2543—2022

表6退付申請接口（續(xù)）

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

退回指定賬戶

refundType退回方式String10是

原支付渠道退回

payeeName收款人名稱String100否

payeeAccount收款人賬號String50否

refundType=0時(shí)，必填

payeeBankName收款開戶行String100否

payeeBankNo收款開戶行行號String50否

detailData退款項(xiàng)目明細(xì)String

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

refundId退付IDString50是

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.6退付申請終止接口

退付申請終止接口見表7。

表7退付申請終止接口

接口名稱退付申請終止接口

接口URLhttp://ip:port/api/stopRefound接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

refundId退付IDString50是

applyUser申請人員String30是

applyTime申請時(shí)間String20是yyyy-MM-ddHH:mm:ss格式

reason終止原因String100是

7

DB14/T2543—2022

表7退付申請終止接口（續(xù)）

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

refundId退付IDString50是

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.7繳款書明細(xì)查詢接口

繳款書明細(xì)查詢接口見表8。

表8繳款書明細(xì)查詢接口

接口名稱繳款書明細(xì)查詢接口

接口URLhttp://ip:port/api/queryPaymentList接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

startDate開始日期String10是

endDate結(jié)束日期String10是

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是

billingDate開票日期String10是yyyy-MM-dd格式

payAmount應(yīng)繳金額String20是兩位小數(shù)

payerName付款人名稱String100是

payerId繳款人號碼String20是

10-未支付

payStatus支付狀態(tài)String10是11-支付中

20-已支付

payTime支付時(shí)間String20否yyyy-MM-ddHH:mm:ss格式

payOrgan支付機(jī)構(gòu)String100否

refundAmount已退款金額String20否兩位小數(shù)

8

DB14/T2543—2022

6.8電子票據(jù)信息接口

電子票據(jù)信息接口見表9。

表9電子票據(jù)信息接口

接口名稱電子票據(jù)信息接口

接口URLhttp://ip:port/api/getElectronicBill接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

url電子票據(jù)地址String150否

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.9單位可用收費(fèi)項(xiàng)目接口

單位可用收費(fèi)項(xiàng)目接口見表10。

表10單位可用收費(fèi)項(xiàng)目接口

接口名稱單位可用收費(fèi)項(xiàng)目接口

接口URLhttp://ip:port/api/queryChargeItems接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

siteCode接入節(jié)點(diǎn)代碼String50是

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

chargeItem收費(fèi)項(xiàng)目名稱String100是

chargeCode收費(fèi)代碼String20是

standardType標(biāo)準(zhǔn)類型String20否定額/開放

minAmout最小金額String20否

maxAmout最大金額String20否

9

DB14/T2543—2022

6.10跳轉(zhuǎn)支付頁面接口

跳轉(zhuǎn)支付頁面接口見表11。

表11跳轉(zhuǎn)支付頁面接口

接口名稱跳轉(zhuǎn)支付頁面接口

接口URLhttp://ip:port/api/goToPay接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

deviceType終端設(shè)備類型String10是1-PC個(gè)人電腦2-手機(jī)終端

redirectUrl回調(diào)地址String200否支付成功后的跳轉(zhuǎn)地址

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

payUrl支付頁面地址String200是

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.11生成支付二維碼接口

生成支付二維碼接口見表12。

表12生成支付二維碼接口

接口名稱生成支付二維碼接口

接口URLhttp://ip:port/api/getPayQrCode接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

qrimage二維碼圖片地址String200是

qrcode支付地址String200是

10

DB14/T2543—2022

表12生成支付二維碼接口（續(xù)）

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

6.12繳款書支付結(jié)果異步通知接口

繳款書支付結(jié)果異步通知接口見表13。

表13繳款書支付結(jié)果異步通知接口

接口名稱繳款書支付結(jié)果異步通知接口

接口URL本URL向政府非稅網(wǎng)上支付平臺第三方系統(tǒng)獲取接口請求方式post

請求參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

transacNo支付確認(rèn)流水號String50是收單機(jī)構(gòu)確認(rèn)交易流水號

payTime支付時(shí)間String20否yyyy-MM-ddHH:mm:ss格式

payAmount支付金額String20是兩位小數(shù)

響應(yīng)參數(shù)

參數(shù)代碼參數(shù)名稱數(shù)據(jù)類型長度是否必填說明

paymentId繳款識別碼String20是統(tǒng)一繳款識別碼

result處理結(jié)果String100是

0-成功

status處理狀態(tài)String10是

其他-失敗

11

DB14/T2543—2022

參考