# 1、開(kāi)發(fā)前配置

開(kāi)發(fā)前，開(kāi)發(fā)者需要完成如下兩個(gè)步驟：配置開(kāi)發(fā)參數(shù)和配置產(chǎn)品功能。

# 1.1、配置開(kāi)發(fā)參數(shù)

參數(shù)名	用途和申請(qǐng)說(shuō)明
mchid	商戶在微信側(cè)入駐的商戶號(hào)，在商戶平臺(tái) (opens new window)申請(qǐng)。
appid	商戶應(yīng)用載體ID，可以是公眾號(hào)/小程序/移動(dòng)應(yīng)用，在開(kāi)放平臺(tái) (opens new window)(移動(dòng)應(yīng)用)和公眾平臺(tái) (opens new window)(公眾號(hào)/小程序)申請(qǐng)，商戶號(hào)需要綁定appid才能在該載體中使用微信支付，詳細(xì)請(qǐng)參考微信支付普通商戶與AppID賬號(hào)關(guān)聯(lián)管理 (opens new window)。
APIV2密鑰	商戶調(diào)用APIv2接口需使用該密鑰簽名驗(yàn)簽，商戶前端拉起支付分小程序需要用到APIv2密鑰生成簽名，設(shè)置方式參考APIv2密鑰設(shè)置及修改方法 (opens new window)。
APIV3密鑰	商戶接收APIv3回調(diào)密文后需使用該密鑰解密，獲取平臺(tái)證書(shū)公鑰也需要使用該密鑰解密，設(shè)置方式參考APIv3密鑰設(shè)置方法 (opens new window)。
商戶API證書(shū)	商戶調(diào)用APIv3接口請(qǐng)求時(shí)需要使用該證書(shū)私鑰生成請(qǐng)求簽名，v2部分涉及資金操作接口(如退款/撤銷(xiāo)/企業(yè)付款等)請(qǐng)求也需要攜帶該證書(shū)，獲取方式參考商戶API證書(shū)獲取方法及功能介紹 (opens new window)。
微信支付平臺(tái)證書(shū)	商戶調(diào)用APIv3接口返回時(shí)需要使用該證書(shū)公鑰進(jìn)行驗(yàn)簽，v3部分含有敏感信息參數(shù)接口也需要使用平臺(tái)證書(shū)公鑰加密，獲取方式參考如何下載平臺(tái)證書(shū) (opens new window)。

# 1.2、配置產(chǎn)品功能

步驟	說(shuō)明
綁定服務(wù)ID	支付分接入權(quán)限審核通過(guò)后，微信支付運(yùn)營(yíng)會(huì)向商戶提供支付分服務(wù)ID，服務(wù)ID下默認(rèn)綁定商戶申請(qǐng)支付分時(shí)填寫(xiě)的商戶號(hào)和appid，商戶后續(xù)新增商戶號(hào)或appid需聯(lián)系微信支付運(yùn)營(yíng)同學(xué)綁定。
配置用于開(kāi)發(fā)的微信號(hào)	支付分服務(wù)上線前無(wú)法開(kāi)放給線上用戶使用。為支持開(kāi)發(fā)過(guò)程中的調(diào)試和測(cè)試，支付分提供了測(cè)試號(hào)白名單功能。上線前，僅白名單中的微信號(hào)用戶可使用支付分服務(wù)。商戶需登錄商戶平臺(tái) (opens new window)進(jìn)行配置，具體參考測(cè)試微信號(hào)配置指引。

# 2、詳細(xì)開(kāi)發(fā)指引

# 2.1、整體業(yè)務(wù)開(kāi)發(fā)流程概覽

• 當(dāng)用戶通過(guò)商戶提供的入口申請(qǐng)使用服務(wù)后，商戶系統(tǒng)同步創(chuàng)建微信支付分服務(wù)訂單，商家再根據(jù)返回參數(shù)拉起支付分確定訂單界面，用戶確認(rèn)訂單后商家開(kāi)始向用戶提供服務(wù)。

• 服務(wù)結(jié)束后商戶通過(guò)完結(jié)訂單接口告知支付分需要收款，由支付分完成自動(dòng)扣款，最后通過(guò)下載交易賬單進(jìn)行對(duì)賬。特殊需要退款的服務(wù)訂單，也可調(diào)用退款接口完成退款。

• 整個(gè)業(yè)務(wù)開(kāi)發(fā)過(guò)程中的前端UI交互，需要滿足支付分合作品牌線上應(yīng)用規(guī)范。

# 2.2、詳細(xì)開(kāi)發(fā)步驟說(shuō)明

# 2.2.1、商戶創(chuàng)建支付分訂單

當(dāng)用戶申請(qǐng)使用服務(wù)時(shí)，商戶需調(diào)用創(chuàng)建支付分訂單API接口創(chuàng)建訂單。在接口參數(shù)中，商戶需要通過(guò)post_payments字段，上傳本筆訂單的預(yù)估費(fèi)用或計(jì)費(fèi)規(guī)則等信息，不同的場(chǎng)景有不同的傳值要求，詳見(jiàn)：post_payments(后付費(fèi)項(xiàng)目)字段傳參說(shuō)明

下單接口需要注意的參數(shù)：

service_id： 支付分服務(wù)ID，商戶支付分服務(wù)的唯一標(biāo)識(shí)，支付分產(chǎn)品權(quán)限申請(qǐng)審核通過(guò)后，微信支付運(yùn)營(yíng)同學(xué)會(huì)向商戶提供支付分服務(wù)ID。

need_user_confirm： 該參數(shù)表示這一筆服務(wù)訂單，是否需要用戶確認(rèn)。需確認(rèn)模式下，商戶必須固定傳"true"。

risk_fund.name： 服務(wù)風(fēng)險(xiǎn)金名稱。

先免模式下，該參數(shù)只能傳 押金[DEPOSIT]、預(yù)付款[ADVANCE]、保證金[CASH_DEPOSIT] 中的一個(gè)值；

先享模式，該參數(shù)只能傳 [預(yù)估訂單費(fèi)用]ESTIMATE_ORDER_COST。

risk_fund.amount： 服務(wù)風(fēng)險(xiǎn)金金額，不可超過(guò)服務(wù)ID風(fēng)險(xiǎn)金額上限，支付分運(yùn)營(yíng)同學(xué)提供service_id時(shí)會(huì)告知服務(wù)ID風(fēng)險(xiǎn)金額上限。

先免模式下，傳這筆服務(wù)單需要的押金、預(yù)付款、保證金數(shù)額。

先享模式，傳這筆訂單預(yù)估的實(shí)際費(fèi)用。

time_range： 時(shí)間參數(shù)時(shí)需注意如果選用"yyyyMMddHHmmss"精確到秒格式，由于商戶系統(tǒng)和微信支付分系統(tǒng)可能存在一定時(shí)差，導(dǎo)致API接口調(diào)用出現(xiàn)時(shí)間檢驗(yàn)不通過(guò)失敗情況，因此商戶在傳入時(shí)間參數(shù)時(shí)需預(yù)留一定誤差時(shí)間。

package： 用于拉起支付分小程序確認(rèn)訂單，創(chuàng)單成功后返回。

# 2.2.2、用戶確認(rèn)支付分訂單

商戶調(diào)用創(chuàng)建支付分訂單API接口生成訂單后，會(huì)獲取到用于拉起支付分訂單確認(rèn)頁(yè)面的關(guān)鍵參數(shù)"package"，商戶根據(jù)自己使用支付分的載體選擇對(duì)應(yīng)API接口拉起支付分，移動(dòng)應(yīng)用類(lèi)型使用APP調(diào)起支付分訂單確認(rèn)頁(yè)面，公眾號(hào)類(lèi)型使用JSAPI調(diào)起支付分訂單確認(rèn)頁(yè)面，小程序類(lèi)型使用小程序調(diào)起支付分訂單確認(rèn)頁(yè)面。

# 2.2.3、商戶提供服務(wù)

• 用戶確認(rèn)訂單后，微信支付會(huì)向商戶發(fā)送回調(diào)通知，告知用戶已確認(rèn)完成。商戶也可通過(guò)查詢支付分訂單API獲取用戶確認(rèn)訂單的狀態(tài)（確認(rèn)后state為DOING，未確認(rèn)為CREATED），用戶確認(rèn)訂單后，商戶可以開(kāi)始向用戶提供服務(wù)。

• 服務(wù)完成后，商戶需調(diào)用完結(jié)支付分訂單API，通知微信支付服務(wù)已結(jié)束(collection.state參數(shù)變?yōu)閁SER_PAYING狀態(tài)，即用戶待支付狀態(tài))。在接口參數(shù)中，商戶需要通過(guò)post_payments字段，上傳本筆訂單實(shí)際的付費(fèi)項(xiàng)目明細(xì)，不同的場(chǎng)景有不同的傳值要求，詳見(jiàn)： post_payments(后付費(fèi)項(xiàng)目)字段傳參說(shuō)明

• 訂單完結(jié)后，支付分會(huì)持續(xù)自動(dòng)扣款，無(wú)需重復(fù)調(diào)用完結(jié)接口。

完結(jié)訂單接口需要注意的參數(shù)：

total_amount： 訂單收款總金額，先免模式(訂單收款總金額<=創(chuàng)單傳的服務(wù)風(fēng)險(xiǎn)金額<=服務(wù)ID風(fēng)險(xiǎn)金額上限)，先享模式(訂單收款總金額<=服務(wù)ID風(fēng)險(xiǎn)金額上限)，支付分運(yùn)營(yíng)同學(xué)在提供service_id時(shí)會(huì)告知服務(wù)ID風(fēng)險(xiǎn)金額上限。

post_payments： 后付費(fèi)項(xiàng)目，表示本次服務(wù)完成后，商家收取的服務(wù)費(fèi)用項(xiàng)目。商戶需要嚴(yán)格按照post_payments(后付費(fèi)項(xiàng)目)字段傳參說(shuō)明傳參，否則會(huì)導(dǎo)致支付分訂單頁(yè)無(wú)法正常展示后付費(fèi)項(xiàng)目，影響驗(yàn)收上線。

time_range： 實(shí)際服務(wù)時(shí)間，該參數(shù)有三種參數(shù)格式，如果選用"yyyyMMddHHmmss"精確到秒格式，可能由于商戶系統(tǒng)和微信支付分系統(tǒng)存在一定時(shí)差，導(dǎo)致API接口調(diào)用出現(xiàn)時(shí)間檢驗(yàn)不通過(guò)失敗情況，因此商戶在傳入時(shí)間參數(shù)時(shí)需預(yù)留一定誤差時(shí)間。

# 2.2.4、商戶收款

商戶調(diào)用完結(jié)支付分訂單API成功后，微信支付分就會(huì)對(duì)用戶發(fā)起扣款，商戶也可以調(diào)起支付分小程序訂單詳情頁(yè)引導(dǎo)用戶主動(dòng)支付，用戶如果有滿足核銷(xiāo)條件的代金券 (opens new window)會(huì)自動(dòng)使用(使用后，在支付成功回調(diào)和查詢支付分訂單接口的promotion_detail字段會(huì)返回代金券信息)，目前支付分只支持全場(chǎng)券。若扣款成功，微信支付會(huì)給商戶系統(tǒng)發(fā)支付成功回調(diào)，支付分訂單結(jié)束。商戶系統(tǒng)也可以通過(guò)調(diào)用查詢支付分訂單API主動(dòng)查詢扣款情況。

下面介紹幾種扣款過(guò)程中的異常處理情況：

• 如果訂單在“待支付”狀態(tài)下（collection.state: USER_PAYING），若扣款金額有誤可調(diào)用修改訂單金額API修改訂單金額，系統(tǒng)將按照修改后的金額發(fā)起扣款(注意只能下調(diào)扣款金額)。

• 如果訂單在“待支付”狀態(tài)下（collection.state: USER_PAYING），希望微信支付分停止繼續(xù)扣款。可調(diào)用取消支付分訂單API取消待支付的支付分訂單，支付分訂單將變成已取消狀態(tài)。

• 如果訂單在“待支付”狀態(tài)下（collection.state: USER_PAYING），用戶通過(guò)其他方式完成支付，商戶可調(diào)用同步訂單信息API將訂單支付成功狀態(tài)同步給微信支付，后續(xù)微信支付將不再發(fā)起扣款，支付分訂單將變成已完成狀態(tài)。

# 2.2.5、商戶對(duì)賬

商戶可在次日上午10點(diǎn)后通過(guò)商戶平臺(tái) (opens new window)手動(dòng)下載交易賬單文件進(jìn)行對(duì)賬，詳見(jiàn)如何在商戶平臺(tái)下載賬單 (opens new window)。另外，商戶也可以通過(guò)申請(qǐng)交易賬單API (opens new window)請(qǐng)求賬單，然后使用下載賬單API (opens new window)下載交易賬單進(jìn)行對(duì)賬。

需要注意以下幾點(diǎn)：

• 訂單只有在支付成功后才會(huì)出現(xiàn)在交易賬單中，未支付成功的訂單不會(huì)顯示在賬單里。

• 主動(dòng)支付完成的支付分訂單賬單的交易類(lèi)型是JSAPI，而自動(dòng)扣款完成的支付分訂單賬單的交易類(lèi)型為AUTH。

• 在賬單中，商戶訂單號(hào)并非支付分商戶服務(wù)單號(hào)，而是在賬單的商戶數(shù)據(jù)包中（格式為wxzff|微信服務(wù)單號(hào)|商戶服務(wù)單號(hào)）。

# 2.2.6、訂單退款

支付分訂單支付后，若訂單需要退款，商戶可登錄商戶平臺(tái) (opens new window)手動(dòng)操作提交退款，具體參考交易退款方法介紹 (opens new window)。

同時(shí)也可通過(guò)支付成功回調(diào)和查詢訂單獲取微信交易單號(hào)（transaction_id），然后使用申請(qǐng)退款A(yù)PI提交退款。提交退款后，可使用查詢單筆退款A(yù)PI查看當(dāng)前退款狀態(tài)，成功退款后將收到退款結(jié)果通知。

# 2.3、訂單狀態(tài)流轉(zhuǎn)圖

1、當(dāng)支付分訂單狀態(tài)為待支付（collection.state: USER_PAYING）時(shí)，微信側(cè)會(huì)定期輪詢扣款，扣款失敗時(shí)狀態(tài)不變，扣款成功時(shí)訂單狀態(tài)才改變。

2、當(dāng)支付分訂單狀態(tài)在待支付狀態(tài)（collection.state: USER_PAYING）下，商戶可以調(diào)用接口修改訂單金額，修改成功后微信側(cè)將按新金額發(fā)起扣款。

3、當(dāng)支付分訂單狀態(tài)為已創(chuàng)建(state:CREATE)和待支付狀態(tài)(collection.state: USER_PAYING)和用戶已確認(rèn)訂單(collection.state: USER_CONFIRM)下，商戶可以調(diào)用取消服務(wù)訂單接口，取消支付分服務(wù)訂單。

4、以下三個(gè)狀態(tài)為終態(tài)

• state：EXPIRED

• state：REVOKED

• state：DONE

# 2.4、開(kāi)發(fā)驗(yàn)收

商戶側(cè)使用測(cè)試微信號(hào)完成開(kāi)發(fā)測(cè)試后，需按照以下流程進(jìn)行驗(yàn)收和上線工作(驗(yàn)收審核通過(guò)后對(duì)應(yīng)服務(wù)才能配置上線并開(kāi)放用戶使用)：

# 2.4.1、產(chǎn)品方案驗(yàn)收

步驟	說(shuō)明
1、提交資料	1、產(chǎn)品流程錄屏： 第一人稱視角手機(jī)錄屏，清晰展示包含首頁(yè)/商品介紹頁(yè)面→ 微信支付分確認(rèn)訂單頁(yè)面（含介紹、計(jì)費(fèi)規(guī)則、下單確認(rèn)）→ 使用微信支付分開(kāi)通授權(quán)成功 → 扣款成功 → 商戶側(cè)訂單詳情 → 查看微信通知 → 查看微信支付分訂單詳情 注： 微信支付分相關(guān)展示須符合支付分合作品牌線上應(yīng)用規(guī)范 2、第三方視角拍攝錄屏： 線下場(chǎng)景第三方視角拍攝視頻，清晰展示實(shí)體產(chǎn)品設(shè)備、使用微信支付分流程、實(shí)體設(shè)備360度全貌，清晰露出設(shè)備品牌名稱，硬件說(shuō)明文字等 3、微信支付分訂單詳情頁(yè)面截圖： 提供微信支付分進(jìn)行中、已完成、已取消三個(gè)訂單狀態(tài)詳情截圖，須確保按以下回傳規(guī)范傳值post_payments(后付費(fèi)項(xiàng)目)字段傳參說(shuō)明
2、提供上線信息	正式service id（服務(wù)id）： 服務(wù)名稱： 商戶號(hào)： 1、預(yù)計(jì)上線時(shí)間、放量計(jì)劃： 2、上線計(jì)劃： ??（1）上線城市和計(jì)劃： ??（2）應(yīng)急機(jī)制：若遇緊急情況是否支持隨時(shí)隱藏支付分入口：支持（默認(rèn)支持）
3、上線完成	驗(yàn)收完成后，微信支付側(cè)將完成服務(wù)配置，產(chǎn)品正式上線；上線后，雙方將共同監(jiān)控產(chǎn)品運(yùn)行情況，確保穩(wěn)定運(yùn)行并滿足用戶需求。