1 概述

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

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

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

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

3 商戶線上聚合收銀臺(tái)接口

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

4 收銀臺(tái)接口設(shè)計(jì)

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

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

4.1.1 請(qǐng)求方式

POST/JSON

4.1.2 請(qǐng)求參數(shù)

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

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

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

4.1.4 響應(yīng)報(bào)文實(shí)例

{"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é)議。商戶交易完成后，由聚合收銀臺(tái)異步推送至商戶。商戶接受處理成功后，需返回給平臺(tái)success。

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

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

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é)果反饋

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

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

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

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

5 加入項(xiàng)目實(shí)戰(zhàn)

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