# 1. 接口規(guī)則

為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。

# 2. 開發(fā)準(zhǔn)備

# 2.1. 搭建和配置開發(fā)環(huán)境

為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。

測試步驟：

1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項目，具體配置請參考下面鏈接的詳細(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)建加載商戶私鑰、加載平臺證書、初始化httpClient的通用方法。

3、基于接口的示例代碼，替換請求參數(shù)后可發(fā)起測試。

說明：

• 上面的開發(fā)庫為微信支付官方開發(fā)庫，其它沒有審核或者控制下的第三方工具和庫，微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后，可根據(jù)下面每個接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測試。
• 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn)，可閱讀下面的詳細(xì)說明：

1. 簽名生成
2. 簽名驗證
3. 敏感信息加解密
4. merchantPrivateKey（私鑰）
5. wechatpayCertificates（平臺證書）
6. APIV3Key（V3 key）

• 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。

# 3. 快速接入

# 3.1. 業(yè)務(wù)流程圖

# 業(yè)務(wù)流程時序圖

# 申請單狀態(tài)變化如下

重點步驟說明：

步驟3 商戶入駐，服務(wù)商收集商戶資料后，調(diào)用提交申請單接口，提交創(chuàng)建入駐申請單。

步驟5 創(chuàng)建申請單后，可通過查詢申請單狀態(tài)接口，獲取特約商戶簽約鏈接，讓商戶掃碼確認(rèn)聯(lián)系信息，后續(xù)申請單進(jìn)度可通過公眾號自動通知超級管理員（簡稱超管）。

步驟10 進(jìn)件成功后，若特約商戶需修改結(jié)算賬號時，服務(wù)商可調(diào)用修改結(jié)算賬號接口來幫助特約商戶修改結(jié)算信息，修改后通過狀態(tài)碼判斷是否修改成功。也可通過調(diào)用查詢結(jié)算賬號接口來查詢核查結(jié)算賬號信息。

# 3.2. API接入（含示例代碼）

文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對接的部分。

# 3.2.1. 【服務(wù)端】提交申請單

步驟說明：服務(wù)商收集商戶資料后，調(diào)用提交申請單接口，提交創(chuàng)建入駐申請單。

重要入?yún)⒄f明：

• business_code 業(yè)務(wù)申請編號。
  • 服務(wù)商自定義的唯一編號。
  • 每個編號對應(yīng)一個申請單，每個申請單審核通過后會生成一個微信支付商戶號。
  • 若申請單被駁回，可填寫相同的“業(yè)務(wù)申請編號”，即可覆蓋修改原申請單信息
• mobile_phone： 聯(lián)系手機(jī)。
  • 11位數(shù)字。
  • 用于接收微信支付的重要管理信息及日常操作驗證碼。
  • 該字段需進(jìn)行加密處理，加密方法詳見敏感信息加密說明。(提醒：必須在HTTP頭中上送Wechatpay-Serial)
• bank_account_type： 賬戶類型。
  • 若主體為企業(yè)/黨政、機(jī)關(guān)及事業(yè)單位/其他組織，可填寫：對公銀行賬戶。
  • 若主體為個體戶，可選擇填寫：對公銀行賬戶或經(jīng)營者個人銀行卡。 枚舉值：
    • BANK_ACCOUNT_TYPE_CORPORATE：對公銀行賬戶
    • BANK_ACCOUNT_TYPE_PERSONAL：經(jīng)營者個人銀行卡
• account_name： 開戶名稱。
  • 選擇“經(jīng)營者個人銀行卡”時，開戶名稱必須與“經(jīng)營者證件姓名”一致。
  • 選擇“對公銀行賬戶”時，開戶名稱必須與營業(yè)執(zhí)照/登記證書的“商戶名稱”一致。
  • 該字段需進(jìn)行加密處理，加密方法詳見敏感信息加密說明。(提醒：必須在HTTP頭中上送Wechatpay-Serial)

更多參數(shù)、響應(yīng)詳情及錯誤碼請參見提交申請單接口文檔。

# 3.2.2.【服務(wù)端】查詢申請單狀態(tài)

步驟說明：創(chuàng)建申請單后，可通過查詢申請單狀態(tài)接口，獲取特約商戶簽約鏈接，讓商戶掃碼確認(rèn)聯(lián)系信息，后續(xù)申請單進(jìn)度可通過公眾號自動通知超級管理員（簡稱超管）。

重要入?yún)⒄f明：

• business_code: 業(yè)務(wù)申請編號。
  • 只能由數(shù)字、字母或下劃線組成，建議前綴為服務(wù)商商戶號。
  • 服務(wù)商自定義的唯一編號。
  • 每個編號對應(yīng)一個申請單，每個申請單審核通過后生成一個微信支付商戶號。
  • 若申請單被駁回，可填寫相同的“業(yè)務(wù)申請編號”，即可覆蓋修改原申請單信息。
• applyment_id: 申請單號， 微信支付分配的申請單號。

更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢申請單狀態(tài)接口文檔

# 3.2.3. 【服務(wù)端】修改結(jié)算賬號

步驟說明： 進(jìn)件成功后，若特約商戶需修改結(jié)算賬號時，服務(wù)商可調(diào)用修改結(jié)算賬號接口來幫助特約商戶修改結(jié)算信息。

重要入?yún)⒄f明：

• sub_mchid: 投訴單對應(yīng)的投訴單號，在投訴通知回調(diào)中會返回這個參數(shù)
• account_bank：開戶銀行，請?zhí)顚戦_戶銀行名稱，詳細(xì)參見開戶銀行對照表。
• account_number：銀行賬號。
  • 數(shù)字，長度遵循系統(tǒng)支持的開戶銀行對照表中對公/對私卡號長度要求。
  • 該字段需進(jìn)行加密處理，加密方法詳見敏感信息加密說明。(提醒：必須在HTTP頭中上送Wechatpay-Serial)

更多參數(shù)、響應(yīng)詳情及錯誤碼請參見修改結(jié)算賬號接口文檔。

# 3.2.4. 【服務(wù)端】查詢結(jié)算賬戶

步驟說明： 服務(wù)商調(diào)用修改結(jié)算賬號接口來幫助特約商戶修改結(jié)算信息，修改后通過狀態(tài)碼判斷是否修改成功。也可通過調(diào)用查詢結(jié)算賬號接口來查詢核查結(jié)算賬號信息。

重要入?yún)⒄f明：

• sub_mchid: 特約商戶號、請輸入本服務(wù)商進(jìn)件、已簽約的特約商戶號。

更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢結(jié)算賬戶接口文檔。

# 4. 常見問題

# Q1：調(diào)用特約商戶進(jìn)件“提交申請單接口”返回“暫無權(quán)限”？

A1：請按照以下幾點檢查

1. 服務(wù)商商戶號被處罰，被限制權(quán)限，請登錄服務(wù)商商戶平臺查看站內(nèi)信，按照收到的站內(nèi)信提示申訴解決
2. 請求頭中的參數(shù)mchid填寫錯誤，該參數(shù)只能填寫為普通服務(wù)商的商戶號，不能填寫為其他類型的商戶號
3. 特約商戶進(jìn)件接口不允許進(jìn)件小微商戶

# Q2：調(diào)用特約商戶進(jìn)件“提交申請單接口”返回“身份證號碼，與營業(yè)執(zhí)照不匹配，請核對修改”？

A2：請按照以下幾點檢查

1. 身份證號碼字段（id_card_number）取值錯誤，請?zhí)顚憘€體戶經(jīng)營者/法定代表人對應(yīng)身份證的號碼
2. 身份證號碼字段（id_card_number）取值錯誤，身份證號碼的規(guī)則是15位數(shù)字或17位數(shù)字+1位數(shù)字|X，該字段需進(jìn)行加密處理
3. 請使用辦理營業(yè)執(zhí)照的身份證號碼

# Q3：調(diào)用特約商戶進(jìn)件“提交申請單接口”返回："參數(shù)“組織機(jī)構(gòu)代碼證照片”是必填項

A3：請仔細(xì)檢查上傳的參數(shù)是否有問題，如果傳入組織機(jī)構(gòu)代碼證的結(jié)構(gòu)（organization_info），將進(jìn)行真實校驗，請去掉組織機(jī)構(gòu)代碼證的結(jié)構(gòu)（organization_info）

# Q4：調(diào)用特約商戶進(jìn)件“提交申請單接口”返回“系統(tǒng)繁忙，請稍后重試”

A4：請按照以下幾點檢查

1. 系統(tǒng)繁忙，可以稍后重試
2. 請求頭中的參數(shù)mchid填寫錯誤，該參數(shù)只能填寫為普通服務(wù)商的商戶號
3. 在請求參數(shù)中，不需要的參數(shù)不要上傳，不能傳空值，空的字段也不能上傳

# Q5：查詢結(jié)算賬戶API不返回verify_result字段，是什么原因？

A5：入駐后若沒有修改過銀行卡，除非是匯款失敗，否則不返回verify_result字段