# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡(jiǎn)單、一致且易用的開發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請(qǐng)參考APIv3接口規(guī)則。
# 2. 開發(fā)準(zhǔn)備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語(yǔ)言版本的開發(fā)庫(kù)，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語(yǔ)言版本的開發(fā)庫(kù)將在近期陸續(xù)提供）。
測(cè)試步驟：
1、根據(jù)自身開發(fā)語(yǔ)言，選擇對(duì)應(yīng)的開發(fā)庫(kù)并構(gòu)建項(xiàng)目，具體配置請(qǐng)參考下面鏈接的詳細(xì)說明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，適用于Go開發(fā)者。
更多資源可前往微信支付開發(fā)者社區(qū) (opens new window)搜索查看。
2、創(chuàng)建加載商戶私鑰、加載平臺(tái)證書、初始化httpClient的通用方法。
3、基于接口的示例代碼，替換請(qǐng)求參數(shù)后可發(fā)起測(cè)試。
說明：
- 上面的開發(fā)庫(kù)為微信支付官方開發(fā)庫(kù)，其它沒有審核或者控制下的第三方工具和庫(kù)，微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測(cè)試。
- 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說明：
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 2.2. 業(yè)務(wù)開發(fā)配置
# 2.2.1. 服務(wù)商開通連鎖品牌工具箱
服務(wù)商可登錄【服務(wù)商平臺(tái) (opens new window)-合作工具箱】申請(qǐng)開通【連鎖品牌工具箱】。進(jìn)行品牌申請(qǐng)、查看品牌申請(qǐng)進(jìn)度、邀請(qǐng)品牌總部授權(quán)、品牌門店管理、品牌流量場(chǎng)景管理等日常管理。
# 2.2.2. 設(shè)置分賬比例
連鎖工具箱開通后，品牌主在商戶平臺(tái)進(jìn)入：“品牌專區(qū)-品牌交易-品牌供應(yīng)鏈分賬-供應(yīng)鏈分賬管理”中可進(jìn)行分賬比例的調(diào)整。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重點(diǎn)步驟說明：
步驟4 分賬前需調(diào)用《添加分賬接收方》接口添加分賬接收方。
步驟6 分賬訂單發(fā)起分賬需調(diào)用《請(qǐng)求分賬》接口進(jìn)行分賬，微信支付將會(huì)把結(jié)算資金分給分賬接收方。
步驟8 分賬完成后，微信會(huì)通過《分賬動(dòng)賬通知》接口，主動(dòng)通知商戶。商戶也可以通過《查詢分賬結(jié)果》接口，主動(dòng)查詢分賬結(jié)果。
步驟12 分賬后若產(chǎn)生退款，則需先調(diào)用《請(qǐng)求分賬回退》接口，請(qǐng)求將已經(jīng)分給分賬方的資金回退，再處理退款。
步驟13 分賬回退完成后，微信同樣會(huì)通過《分賬動(dòng)賬通知》接口，主動(dòng)通知商戶。商戶也可以通過《查詢分賬回退結(jié)果》接口，主動(dòng)查詢分賬結(jié)果。
步驟17 分賬結(jié)束后，商戶需調(diào)用《完結(jié)分賬》接口結(jié)束分賬訂單。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入連鎖品牌分賬產(chǎn)品，完成與微信支付對(duì)接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號(hào)及請(qǐng)求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請(qǐng)商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評(píng)估、修改。
# 3.2.1. 【服務(wù)端】請(qǐng)求分賬
**步驟說明：**微信訂單支付成功后，由服務(wù)商發(fā)起分賬請(qǐng)求，將結(jié)算后的資金分給分賬接收方。
重要入?yún)⒄f明：
- brand_mchid：品牌主商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- sub_mchid：子商戶號(hào)，訂單收款方商戶號(hào)，可以是品牌主商戶號(hào)，也可以是門店商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- AppID：公眾賬號(hào)ID，微信分配的公眾賬號(hào)ID，這里指服務(wù)商的AppID。
- out_order_no：商戶分賬單號(hào)，商戶系統(tǒng)內(nèi)部的分賬單號(hào)，在商戶系統(tǒng)內(nèi)部唯一（單次分賬、多次分賬、完結(jié)分賬應(yīng)使用不同的商戶分賬單號(hào)），同一分賬單號(hào)多次請(qǐng)求等同一次，只能是數(shù)字、大小寫字母
_``-``|``*``@。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見請(qǐng)求分賬接口文檔。
# 3.2.2. 【服務(wù)端】查詢分賬結(jié)果
步驟說明： 發(fā)起分賬請(qǐng)求后，可調(diào)用此接口查詢分賬結(jié)果 。發(fā)起分賬完結(jié)請(qǐng)求后，可調(diào)用此接口查詢分賬完結(jié)的結(jié)果。
重要入?yún)⒄f明：
- transaction_id：微信訂單號(hào)， 微信支付訂單號(hào)。
- sub_mchid：子商戶號(hào)，訂單收款方商戶號(hào)，可以是品牌主商戶號(hào)，也可以是門店商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- out_order_no：商戶分賬單號(hào)，商戶系統(tǒng)內(nèi)部的分賬單號(hào)，在商戶系統(tǒng)內(nèi)部唯一（單次分賬、多次分賬、完結(jié)分賬應(yīng)使用不同的商戶分賬單號(hào)），同一分賬單號(hào)多次請(qǐng)求等同一次，只能是數(shù)字、大小寫字母_-|*@。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見查詢分賬結(jié)果接口文檔。
# 3.2.3. 【服務(wù)端】分賬動(dòng)賬通知
步驟說明： 此功能僅針對(duì)分賬接收方，當(dāng)分賬動(dòng)賬金額發(fā)生變動(dòng)時(shí)，微信會(huì)把相關(guān)變動(dòng)結(jié)果發(fā)送給需要實(shí)時(shí)關(guān)注的分賬接收方。
注意
- 分賬動(dòng)賬通知是以POST 方法訪問商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過請(qǐng)求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請(qǐng)求來自微信。微信會(huì)對(duì)發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗(yàn)證簽名，以確認(rèn)請(qǐng)求來自微信，而不是其他的第三方。簽名驗(yàn)證的算法請(qǐng)參考《微信支付API v3簽名驗(yàn)證》。
- 分賬動(dòng)賬通知HTTP應(yīng)答碼為200或204才會(huì)當(dāng)作正常接收，當(dāng)回調(diào)處理異常時(shí)，應(yīng)答的HTTP狀態(tài)碼應(yīng)為500，或者4xx。
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204。
- 同樣的通知可能會(huì)多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是，當(dāng)商戶系統(tǒng)收到通知進(jìn)行處理時(shí)，先檢查對(duì)應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進(jìn)行處理；如果已處理，則直接返回結(jié)果成功。在對(duì)業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見分賬動(dòng)賬通知接口文檔。
# 3.2.4. 【服務(wù)端】請(qǐng)求分賬回退
步驟說明： 如果訂單已經(jīng)分賬，在退款時(shí)，可以先調(diào)此接口，將已分賬的資金從商戶類型的分賬接收方的賬戶回退給分賬方，再發(fā)起退款。
重要入?yún)⒄f明：
- sub_mchid：子商戶號(hào)，訂單收款方商戶號(hào)，可以是品牌主商戶號(hào)，也可以是門店商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- out_order_no：商戶分賬單號(hào)，商戶系統(tǒng)內(nèi)部的分賬單號(hào)，在商戶系統(tǒng)內(nèi)部唯一（單次分賬、多次分賬、完結(jié)分賬應(yīng)使用不同的商戶分賬單號(hào)），同一分賬單號(hào)多次請(qǐng)求等同一次，只能是數(shù)字、大小寫字母_-|*@。
- out_return_no：商戶回退單號(hào)，此回退單號(hào)是商戶在自己后臺(tái)生成的一個(gè)新的回退單號(hào)，在商戶后臺(tái)唯一，只能是數(shù)字、大小寫字母_-|*@。
- return_mchid：回退商戶號(hào)，回退商戶號(hào)只能填寫原分賬請(qǐng)求中接收分賬的商戶號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見請(qǐng)求分賬回退接口文檔。
# 3.2.5. 【服務(wù)端】查詢分賬回退結(jié)果
步驟說明：商戶需要核實(shí)回退結(jié)果，可調(diào)用此接口查詢回退結(jié)果。如果分賬回退接口返回狀態(tài)為處理中，可調(diào)用此接口查詢回退結(jié)果。
重要入?yún)⒄f明：
- sub_mchid：子商戶號(hào)，訂單收款方商戶號(hào)，可以是品牌主商戶號(hào)，也可以是門店商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- out_order_no：商戶分賬單號(hào)，商戶系統(tǒng)內(nèi)部的分賬單號(hào)，在商戶系統(tǒng)內(nèi)部唯一（單次分賬、多次分賬、完結(jié)分賬應(yīng)使用不同的商戶分賬單號(hào)），同一分賬單號(hào)多次請(qǐng)求等同一次，只能是數(shù)字、大小寫字母_-|*@。
- out_return_no：商戶回退單號(hào)，調(diào)用回退接口提供的商戶系統(tǒng)內(nèi)部的回退單號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見查詢分賬回退結(jié)果接口文檔。
# 3.2.6. 【服務(wù)端】完結(jié)分賬
步驟說明： 不需要進(jìn)行分賬的訂單，可直接調(diào)用本接口將訂單的金額全部解凍給分賬方商戶。
重要入?yún)⒄f明：
- transaction_id：微信訂單號(hào)， 微信支付訂單號(hào)。
- sub_mchid：子商戶號(hào)，訂單收款方商戶號(hào)，可以是品牌主商戶號(hào)，也可以是門店商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- out_order_no：商戶分賬單號(hào)，商戶系統(tǒng)內(nèi)部的分賬單號(hào)，在商戶系統(tǒng)內(nèi)部唯一（單次分賬、多次分賬、完結(jié)分賬應(yīng)使用不同的商戶分賬單號(hào)），同一分賬單號(hào)多次請(qǐng)求等同一次，只能是數(shù)字、大小寫字母_-|*@。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見完結(jié)分賬接口文檔。
# 3.2.7. 【服務(wù)端】查詢訂單剩余待分金額
步驟說明： 可調(diào)用此接口查詢訂單剩余待分金額。
重要入?yún)⒄f明：
- transaction_id：微信訂單號(hào)， 微信支付訂單號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見查詢訂單剩余待分金額接口文檔。
# 3.2.8. 【服務(wù)端】查詢最大分賬比例
步驟說明： 服務(wù)商可通過此接口添加分賬接收方，建立分賬接收方列表。連鎖加盟模式下，服務(wù)商添加的分賬接收方統(tǒng)一在品牌主商戶號(hào)維度進(jìn)行管理。
重要入?yún)⒄f明：
- brand_mchid：品牌主商戶號(hào)，通過微信支付認(rèn)證的品牌主商戶號(hào)，填寫微信支付分配的商戶號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見查詢最大分賬比例接口文檔。
# 3.2.9. 【服務(wù)端】添加分賬接收方
步驟說明： 服務(wù)商可通過此接口添加分賬接收方，建立分賬接收方列表。連鎖加盟模式下，服務(wù)商添加的分賬接收方統(tǒng)一在品牌主商戶號(hào)維度進(jìn)行管理。
重要入?yún)⒄f明：
- brand_mchid：品牌主商戶號(hào)，通過微信支付認(rèn)證的品牌主商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- AppID：公眾賬號(hào)ID，微信分配的公眾賬號(hào)ID，這里指服務(wù)商的AppID。
- type：分賬接收方類型，枚舉值：
- MERCHANT_ID：商戶號(hào)（mch_id或者sub_mch_id）
- PERSONAL_OPENID：個(gè)人OpenID（由服務(wù)商的AppID轉(zhuǎn)換得到）
- PERSONAL_SUB_OPENID：個(gè)人sub_openid（由品牌主的AppID轉(zhuǎn)換得到）
- account：分賬接收方賬號(hào)：
- 分賬接收方類型為：MERCHANT_ID時(shí)，分賬接收方賬號(hào)為商戶號(hào)（mch_id或者sub_mch_id）
- 分賬接收方類型為：PERSONAL_OPENID時(shí)，分賬接收方賬號(hào)為個(gè)人OpenID
- 分賬接收方類型為：PESONAL_SUB_OPENID時(shí)，分賬接收方賬號(hào)為個(gè)人sub_openid
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見添加分賬接收方接口文檔。
# 3.2.10. 【服務(wù)端】刪除分賬接收方
步驟說明： 服務(wù)商發(fā)起刪除分賬接收方請(qǐng)求。刪除后，不再支持品牌主或門店分到該分賬接收方。
重要入?yún)⒄f明：
- brand_mchid：品牌主商戶號(hào)，通過微信支付認(rèn)證的品牌主商戶號(hào)，填寫微信支付分配的商戶號(hào)。
- AppID：公眾賬號(hào)ID，微信分配的公眾賬號(hào)ID，這里指服務(wù)商的AppID。
- type：分賬接收方類型，枚舉值：
- MERCHANT_ID：商戶號(hào)（mch_id或者sub_mch_id）
- PERSONAL_OPENID：個(gè)人OpenID（由服務(wù)商的AppID轉(zhuǎn)換得到）
- PERSONAL_SUB_OPENID：個(gè)人sub_openid（由品牌主的AppID轉(zhuǎn)換得到）
- account：分賬接收方賬號(hào)：
- 分賬接收方類型為：MERCHANT_ID時(shí)，分賬接收方賬號(hào)為商戶號(hào)（mch_id或者sub_mch_id）
- 分賬接收方類型為：PERSONAL_OPENID時(shí)，分賬接收方賬號(hào)為個(gè)人OpenID
- 分賬接收方類型為：PESONAL_SUB_OPENID時(shí)，分賬接收方賬號(hào)為個(gè)人sub_openid
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見刪除分賬接收方接口文檔。
# 4. 常見問題
# Q：分賬調(diào)用“請(qǐng)求分賬接口”返回“非分賬訂單不支持分賬”
A：請(qǐng)按照以下幾點(diǎn)檢查：
- 微信訂單號(hào)填寫錯(cuò)誤；
- 下單的時(shí)候未傳分賬標(biāo)識(shí)（profit_sharing）的訂單，是沒有分賬權(quán)限的。
# Q：分賬調(diào)用“請(qǐng)求分賬接口”返回“分賬金額不足”
A：請(qǐng)按照以下幾點(diǎn)檢查：
- 該訂單已全額退款，沒有資金可以分賬；
- 已經(jīng)調(diào)用過“請(qǐng)求單次分賬”，訂單剩余的待分賬金額已經(jīng)解凍，已無(wú)分賬資金；
- 超過訂單可分賬金額或者該訂單已無(wú)可分賬金額，請(qǐng)檢查確認(rèn)。
# Q：分賬調(diào)用“請(qǐng)求分賬接口”返回“訂單處理中，暫時(shí)無(wú)法分賬，請(qǐng)稍后再試”
A：請(qǐng)按照以下幾點(diǎn)檢查：
- 請(qǐng)?jiān)谟唵沃Ц冻晒?分鐘后再調(diào)用分賬接口；
- 未結(jié)算的訂單，請(qǐng)?jiān)诮Y(jié)算后再調(diào)用分賬接口請(qǐng)求分賬；
- 老資金流商戶的訂單，不支持分賬；
- 商戶開通了收支分離但手續(xù)費(fèi)賬戶余額不足（手續(xù)費(fèi)賬戶最低余額要求是100元以上，在充值手續(xù)費(fèi)賬戶1小時(shí)后，訂單會(huì)正常結(jié)算，即可正常調(diào)用分賬接口）。
# Q：分賬調(diào)用“請(qǐng)求分賬接口”返回“分賬接收商戶全稱不匹配”
A：請(qǐng)按照以下幾點(diǎn)檢查：
- 分賬接收商戶全稱填寫錯(cuò)誤，請(qǐng)?zhí)顚懻_的商戶全稱；
- 接口需要使用UTF-8編碼。
# Q：分賬調(diào)用“添加分賬接收方接口”返回“系統(tǒng)繁忙，請(qǐng)稍后重試”
A：receiver中的參數(shù)account錯(cuò)誤，參數(shù)account的規(guī)則如下：
- 類型是MERCHANT_ID時(shí)，是商戶ID；
- 類型是PERSONAL_OPENID時(shí)，是個(gè)人OpenID；
- 類型是PERSONAL_SUB_OPENID時(shí)，是個(gè)人sub_openid；
- AppID與mchid不匹配也會(huì)報(bào)該錯(cuò)誤，請(qǐng)檢查確認(rèn)；
- 簽名類型錯(cuò)誤，分賬接口簽名類型目前支持SHA256-RSA、國(guó)密（又稱商用加密算法，即商密SM）。
