1 概述

聚合支付收款分為線上和線下業(yè)務(wù)場景，本文中的商戶收銀臺接口設(shè)計主要是指線上業(yè)務(wù)場景，線下業(yè)務(wù)場景聚合收款方式后續(xù)會進(jìn)行單獨設(shè)計和分析。

主流的線上支付渠道有微信支付，支付寶支付，云閃付。這三種支付渠道都有各自的線上收款產(chǎn)品APP支付、H5支付、小程序支付、掃碼支付、公眾號支付 。dtpay聚合支付系統(tǒng)商戶收銀臺接口產(chǎn)品主要整合支付渠道不同的線上收款場景，讓線上商戶快速接入各渠道支付場景。

2 線上聚合收銀臺技術(shù)架構(gòu)

系統(tǒng)采用SpringCloud,SpringCloudAalibaba微服務(wù)架構(gòu)，系統(tǒng)采用容器化(Docker,K8S)部署,以下是技術(shù)架構(gòu)使用的技術(shù)棧

3 商戶線上聚合收銀臺接口

商戶聚合收銀臺接口采用接口對接或SDK方式給到商戶自助對接，收銀臺接口系統(tǒng)各參與方有商戶系統(tǒng)、dtpay商戶線上聚合收銀臺接口系統(tǒng)、支付渠道方。商戶不需要對接各支付渠道的支付產(chǎn)品，通過聚合收銀臺快速完成收款方式的對接。

4 收銀臺接口設(shè)計

收銀臺接口主要涵蓋以下接口統(tǒng)一下單支付接口、支付通知接口、支付查詢接口

4.1 統(tǒng)一支付下單支付接口設(shè)計

4.1.1 請求方式

POST/JSON

4.1.2 請求參數(shù)

字段	名稱	類型	長度	必輸	備注
mercOrderNo	商戶訂單號	String	32	是	商戶自己生成的唯一的訂單號，商戶訂單號+商戶號唯一
subject	訂單名稱	String	100	是	訂單名稱、訂單說明兩者必填其一
body	訂單說明	String	200	否	訂單名稱、訂單說明兩者必填其一
tradeType	交易類型	String	2	是	01-支付 02-代付 03-提現(xiàn)
tradeAmt	訂單金額	String	12	是	交易金額(單位元，帶兩位小數(shù)，例:1.23,最大整數(shù)16位)
feeType	幣種	String		否	默認(rèn)是CNY：人民幣，當(dāng)前版本暫不支持其它幣種。
tradeTime	提交支付時間	String	14	是	格式[yyyyMMddHHmmss] ;
orderPeriod	訂單有效時間	String	14	是	訂單有效期(單位分鐘)
notifyUrl	后臺通知地址	String	200	是	支付成功時，后臺通知商戶的地址，必須為http/https協(xié)議地址
returnUrl	前臺通知地址	String	200	是	支付成功是，前臺頁面跳轉(zhuǎn)的提示頁面，為空不發(fā)前臺通知，必須為http/https協(xié)議地址
refererUrl	客戶端地址	String	200	否	重定向地址，可直接跳轉(zhuǎn)到商戶頁面（不會附加參數(shù)返回）
termType	終端接入類型	String	8	是	固定值：wap，pc，app
paywayCode	支付方式	String	20	是	alipay-支付寶 wxpay-微信支付 unionpay-銀聯(lián)支付例如：當(dāng)微信支付時傳值 wxpay
sceneCode	場景編號	String	20	是	h5-H5支付app-APP支付scan-掃碼支付jspay-公眾號支付ebank-網(wǎng)銀支付gateway-網(wǎng)關(guān)支付例如：當(dāng)支付場景為H5支付時傳值“h5”注：當(dāng)支付方式選“ebank”即網(wǎng)銀支付時，場景編號傳送值為“ebank”；
ip	客戶端IP（外網(wǎng)IP）	String	32	是
merchantId	商戶編號	String	8	否
storeId	門店編號	String	8	否
payeeId	收銀員編號	String	8	否
remark	備注	String	100	否
attach	附加信息	String	128	否
deviceInfo	應(yīng)用類型	String	16	否	如果是應(yīng)用于蘋果app,應(yīng)用里值為IOS_SDK;如果是應(yīng)用于安卓app,應(yīng)用里值為AND_SDK;如果是應(yīng)用于手機(jī)網(wǎng)站，應(yīng)用里值為WAP_SDK，微信h5必輸
mchAppName	應(yīng)用名	String	256	否	如果是用于蘋果或安卓app應(yīng)用中，傳分別對應(yīng)在AppStore和安卓分發(fā)市場中的應(yīng)用名（如：王者榮耀）如果是用于手機(jī)網(wǎng)站，傳對應(yīng)的網(wǎng)站名（如：天貓官網(wǎng)）微信h5必輸
mchAppId	應(yīng)用標(biāo)識	String	128	否	如是是用于蘋果或安卓app應(yīng)用中，蘋果傳IOS應(yīng)用中唯一標(biāo)識（如：com.tencent.wzryIOS）,安卓傳包名（如：com.tencent.tmgp.sgame）如果是用于手機(jī)網(wǎng)站，傳網(wǎng)站首頁URL地址，必須保證公網(wǎng)能正常訪問（如：www.itbeien.cn）>微信h5必輸
bankCode	網(wǎng)銀銀行編碼	String	20	否	網(wǎng)銀支付必傳，見銀行代碼
payType	支付卡類型	String	1	否	1 借記卡 2 貸記卡 3借/貸記卡均可使用。網(wǎng)銀支付傳此參數(shù)，不傳默認(rèn)為1，即 借記卡
quickPayAttach	快捷支付參數(shù)	String		否	快捷支付直連時必輸

4.1.3 同步響應(yīng)參數(shù)

字段	名稱	類型	長度	必輸	備注
mercOrderNo	商戶訂單號	String		是	商戶自己生成的唯一的訂單號
tradeType	交易類型	String		是	01-支付 11-充值 02-代付 03-提現(xiàn)
tradeAmt	交易金額	String		是	交易金額
tradeTime	支付提交時間	String		是	訂單提交時間，格式[yyyyMMddHHmmss] ;
feeType	幣種	String		是	默認(rèn)是CNY：人民幣，當(dāng)前版本暫不支持其它幣種。
termType	終端接入類型	String		是	固定值：wap，pc，app
orderId	平臺訂單號	String	32	是	平臺訂單號，可以理解成支付平臺返回號
codeUrl	二維碼鏈接	String	128	否	二維碼鏈接 掃碼必輸
imgUrl	二維碼圖片	String	128	否	二維碼圖片
payInfo	公眾號支付信息	String	128	否	公眾號支付信息
mwebUrl	H5支付地址	String	128	否	H5支付地址
bankType	付款銀行	String	16	否	銀行類型
resultHtml	支付form	String		否	網(wǎng)銀支付返回必輸，格式為form表單

4.1.4 響應(yīng)報文實例

{"orderId":"2024061812582900001378","signature":"5974FF8536CC614F6C2XXXXXXXXXXXX","termType":"wap","mercOrderNo":"D20180315125826","tradeType":"01","codeUrl":"https://www.itbeien.cn/qr/5519dddb","respDesc":"處理成功","feeType":"CNY","mercNo":"ORG1520825458796","tradeTime":"20240618125826","interfaceCode":"pay","respCode":"000000"
}

4.2 支付通知接口

商戶回調(diào)接口使用HTTPS協(xié)議可以保證數(shù)據(jù)傳輸?shù)陌踩?#xff0c;所以建議商戶提供的回調(diào)接口采用HTTPS協(xié)議。商戶交易完成后，由聚合收銀臺異步推送至商戶。商戶接受處理成功后，需返回給平臺success。

4.2.1 通知結(jié)果參數(shù)列表

字段	名稱	類型	長度	必輸	備注
mercOrderNo	商戶訂單號	String		是	商戶自己生成的唯一的訂單號
tradeType	交易類型	String		是	01-支付 11-充值 02-代付 03-提現(xiàn)
tradeAmt	交易金額	String		是	交易金額
tradeTime	支付提交時間	String		是	訂單提交時間，格式[yyyyMMddHHmmss] ;
feeType	幣種	String		是	默認(rèn)是CNY：人民幣，當(dāng)前版本暫不支持其它幣種。
termType	終端接入類型	String		是	固定值：wap，pc，app
orderId	平臺訂單號	String	32	是	平臺訂單號，可以理解成支付平臺返回號
tradeEndTime	交易完成時間	String		是	支付平臺保證精確的支付交易完成時間。
payStatus	支付狀態(tài)	String		是	p0001 :提交訂單 p0002：支付中 p0000 :支付成功 p0004:支付失敗 p0005:已取消 p0006:過期已作廢
bankType	付款銀行	String	16	否	銀行類型

4.2.2 支付異步通知參數(shù)示例

{"tradeAmt":"0.01","charset":"UTF-8","orderId":"2024061812582900001378","signature":"0B5E5BAD0C447582A99618EEB0A35567","termType":"wap","mercOrderNo":"D20180315125826","feeType":"CNY","locale":"CN","tradeEndTime":"20240618125846","version":"1.0","mercNo":"ORG1520825458796","tradeTime":"20240618125828","signType":"MD5","payStatus":"p0000","tradeType":"01"
}

4.2.3 通知結(jié)果反饋

聚合收銀臺通過 notifyUrl 通知商戶，商戶做業(yè)務(wù)處理后，需要以字符串的形式反饋處理結(jié)果，內(nèi)容如下：

返回結(jié)果	結(jié)果說明
success	處理成功
fail	處理不成功

4.2.4 補(bǔ)單機(jī)制

注意：聚合收銀臺通知交互模式，如果聚合收銀臺收到商戶的應(yīng)答不是純字符串success或超過5秒后返回時，聚合收銀臺認(rèn)為通知失敗，聚合收銀臺會通過一定的策略（通知頻率為10/10/10/10/10，單位：秒）間接性重新發(fā)起通知，盡可能提高通知的成功率，但平臺不保證通知最終能成功。由于存在重新發(fā)送后臺通知的情況，因此同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。聚合收銀臺推薦的做法是，當(dāng)收到通知進(jìn)行處理時，首先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，判斷該通知是否已經(jīng)處理過，如果沒有處理過再進(jìn)行處理，如果處理過直接返回純字符串success。在對業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重復(fù)插入數(shù)據(jù)造成的數(shù)據(jù)混亂。

5 加入項目實戰(zhàn)

歡迎關(guān)注我的視頻號，視頻號有相關(guān)技術(shù)和業(yè)務(wù)視頻可學(xué)習(xí)支付業(yè)務(wù)/文旅行業(yè)數(shù)字化。探討技術(shù)(系統(tǒng)架構(gòu)、微服務(wù)、容器化、云原生)