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

DB14/T2543—2022

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

1范圍

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

本文件適用于政府非稅網(wǎng)上支付平臺第三方接入接口的設(shè)計、開發(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個可打印ASCII字符對任意字節(jié)數(shù)據(jù)進(jìn)行編碼的算法。

3.2

siteCode

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

3.3

3DES

三重數(shù)據(jù)加密算法，對每個數(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<>列表類型每一項均為一個子數(shù)據(jù)項，子數(shù)據(jù)項編碼方式與父數(shù)據(jù)項編碼方式相同

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

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

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

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

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

Time時間類型時間表示為：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驗證、

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

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

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

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

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

2

DB14/T2543—2022

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

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

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

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

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

6接口組成

6.1接口列表

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

表2接口列表

接口名稱接口描述

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

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

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

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

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

退付申請終止接口

交退付申請）

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

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

單位可用收費項目接口本接口用于查詢第三方接入單位可用的收費項目信息

跳轉(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收費項目個數(shù)String10是

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

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

必填

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

payerName付款人名稱String100是

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

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

payerId繳款人號碼String20是

個人:身份證號

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

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

email郵箱地址String30否

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

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

auditUser審核人員String30否

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

detailData收費項目明細(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通知書開具時間String20是yyyy-MM-ddHH:mm:ss格

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

10-未支付

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

20-已支付

payTime支付時間String20否yyyy-MM-ddHH:mm:ss格

invalidTime作廢時間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申請時間String20是yyyy-MM-ddHH:mm:ss格式

reason作廢原因String100是

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

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

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

invalidTime作廢時間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申請時間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時，必填

payeeBankName收款開戶行String100否

payeeBankNo收款開戶行行號String50否

detailData退款項目明細(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申請時間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支付時間String20否yyyy-MM-ddHH:mm:ss格式

payOrgan支付機構(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單位可用收費項目接口

單位可用收費項目接口見表10。

表10單位可用收費項目接口

接口名稱單位可用收費項目接口

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

請求參數(shù)

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

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

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

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

chargeItem收費項目名稱String100是

chargeCode收費代碼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個人電腦2-手機終端

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是收單機構(gòu)確認(rèn)交易流水號

payTime支付時間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

參考