# 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三種語言版本的開發(fā)庫(kù)，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫(kù)將在近期陸續(xù)提供）。
測(cè)試步驟：
1、根據(jù)自身開發(fā)語言，選擇對(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ī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
# 業(yè)務(wù)流程時(shí)序圖
申請(qǐng)單狀態(tài)變化如下：
重點(diǎn)步驟說明：
步驟1： 獲取微信支付商戶號(hào)：渠道商使用銀行或者支付機(jī)構(gòu)提供的API或者后臺(tái)系統(tǒng)錄入商家門店信息，獲取商家每個(gè)門店在微信支付側(cè)的商戶號(hào)（上送給微信支付的“商戶名稱”字段必須與營(yíng)業(yè)執(zhí)照上商戶名稱一致，具體規(guī)則 點(diǎn)擊查看 (opens new window) ）。
步驟2： 查詢微信支付商戶號(hào)授權(quán)狀態(tài)：渠道商使用《獲取商戶號(hào)開戶意愿確認(rèn)狀態(tài)接口》查詢微信支付商戶號(hào)是否完成開戶意愿確認(rèn)。
步驟5： 提交商家資料給微信支付：渠道商根據(jù)商家類型（企業(yè)、個(gè)體戶、小微、事業(yè)單位、其他組織等）準(zhǔn)備好相關(guān)的商家資料，使用微信支付接口《提交開戶意愿確認(rèn)申請(qǐng)單》獲取微信支付申請(qǐng)單編號(hào)。
步驟8： 查詢申請(qǐng)單審核結(jié)果：渠道商提交商家資料后，建議每隔五分鐘調(diào)用《查詢申請(qǐng)單審核結(jié)果接口》查詢申請(qǐng)單審核結(jié)果。
# 申請(qǐng)單正常情況下的狀態(tài)轉(zhuǎn)換如下
- 提交后申請(qǐng)單狀態(tài)為“審核中”，微信支付后臺(tái)會(huì)進(jìn)行審核，審核通過后申請(qǐng)單狀態(tài)變成“待聯(lián)系人確認(rèn)”，同時(shí)接口會(huì)提供“申請(qǐng)單小程序碼” （小程序碼的圖片）。
- 聯(lián)系人掃“申請(qǐng)單小程序碼”后確認(rèn)資料無誤后，申請(qǐng)單狀態(tài)變成“待賬戶驗(yàn)證”。
- 聯(lián)系人將“法人確認(rèn)二維碼”在微信上發(fā)給法人確認(rèn)后（或打款驗(yàn)證），申請(qǐng)單狀態(tài)變成“審核通過”。
- 當(dāng)審核結(jié)果為“審核駁回”時(shí)，請(qǐng)根據(jù)駁回原因重新提交商家資料，重新提交前請(qǐng)使用《撤銷原申請(qǐng)單》，再次提交新的商家資料。
- 當(dāng)審核結(jié)果為“待聯(lián)系人確認(rèn)”或“待賬戶驗(yàn)證”或“審核通過”時(shí)，接口會(huì)同時(shí)給出“申請(qǐng)單小程序碼”。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對(duì)接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號(hào)及請(qǐng)求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請(qǐng)商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評(píng)估、修改。
# 3.2.1. 【服務(wù)端】提交申請(qǐng)單
步驟說明： 服務(wù)商收集商戶資料后，調(diào)用提交申請(qǐng)單接口，提交創(chuàng)建入駐申請(qǐng)單。
重要入?yún)⒄f明：
out_trade_no： 業(yè)務(wù)申請(qǐng)編號(hào)，服務(wù)商自定義的唯一編號(hào)，每個(gè)編號(hào)對(duì)應(yīng)一個(gè)申請(qǐng)單。
subject_type： 主體類型。枚舉值：
- SUBJECT_TYPE_ENTERPRISE：企業(yè)
- SUBJECT_TYPE_INSTITUTIONS_CLONED：事業(yè)單位
- SUBJECT_TYPE_INDIVIDUAL：個(gè)體工商戶
- SUBJECT_TYPE_OTHERS：其他組織
- SUBJECT_TYPE_MICRO：小微商戶
licence_number： 營(yíng)業(yè)執(zhí)照注冊(cè)號(hào)。校驗(yàn)規(guī)則：
- 請(qǐng)?zhí)顚憼I(yíng)業(yè)執(zhí)照上的注冊(cè)號(hào)。
- 若主體類型為個(gè)體工商戶或企業(yè)，注冊(cè)號(hào)格式須為15位數(shù)字或18位數(shù)字|大寫字母。
merchant_name： 商戶名稱。
- 個(gè)體工商戶，不能以“公司”結(jié)尾。
- 個(gè)體工商戶，若營(yíng)業(yè)執(zhí)照上商戶名稱為空或?yàn)椤盁o”，請(qǐng)?zhí)顚?quot;個(gè)體戶+經(jīng)營(yíng)者姓名"，如“個(gè)體戶張三”。
legal_person： 法人姓名。
- 只能由中文字符、英文字符、可見符號(hào)組成。
- 請(qǐng)?zhí)顚憼I(yíng)業(yè)執(zhí)照的經(jīng)營(yíng)者/法定代表人姓名。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見提交申請(qǐng)單接口文檔。
# 3.2.2.【服務(wù)端】撤銷申請(qǐng)單
步驟說明： 服務(wù)商提交申請(qǐng)單后需要修改信息時(shí)，或者申請(qǐng)單審核結(jié)果為“已駁回”時(shí)服務(wù)商要修改申請(qǐng)材料時(shí)，均需要先調(diào)用撤銷申請(qǐng)單接口。
重要入?yún)⒄f明：
- applyment_id： 申請(qǐng)單編號(hào)，微信支付分配的申請(qǐng)單號(hào)，申請(qǐng)單編號(hào)和業(yè)務(wù)申請(qǐng)編號(hào)至少傳一個(gè)。
- business_code： 業(yè)務(wù)申請(qǐng)編號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見撤銷申請(qǐng)單接口文檔。
# 3.2.3. 【服務(wù)端】查詢申請(qǐng)單審核結(jié)果
步驟說明： 查詢申請(qǐng)單審核結(jié)果。
重要入?yún)⒄f明：
- applyment_id： 申請(qǐng)單編號(hào)，微信支付分配的申請(qǐng)單號(hào)，申請(qǐng)單編號(hào)和業(yè)務(wù)申請(qǐng)編號(hào)至少傳一個(gè)。
- business_code： 業(yè)務(wù)申請(qǐng)編號(hào)。
- 服務(wù)商自定義的唯一編號(hào)。
- 每個(gè)編號(hào)對(duì)應(yīng)一個(gè)申請(qǐng)單。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見撤銷申請(qǐng)單接口文檔。 origin/master
# 3.2.4. 【服務(wù)端】獲取商戶開戶意愿確認(rèn)狀態(tài)
步驟說明： 當(dāng)服務(wù)商需要確認(rèn)微信支付子商戶號(hào)是否完成確認(rèn)時(shí)，如果調(diào)用此接口提到“已授權(quán)”狀態(tài)，則說明該商戶號(hào)已完成開戶意愿確認(rèn)。
重要入?yún)⒄f明：
- sub_mchid： 特約商戶號(hào)，微信支付分配的特約商戶的唯一標(biāo)識(shí)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見獲取商戶開戶意愿確認(rèn)狀態(tài)接口文檔。
# 4. 常見問題
# Q1：商戶開戶意愿調(diào)用“提交申請(qǐng)單”返回：暫未查詢到該營(yíng)業(yè)執(zhí)照注冊(cè)號(hào)，請(qǐng)檢查營(yíng)業(yè)執(zhí)照注冊(cè)號(hào)是否填寫正確
A1：請(qǐng)求參數(shù)“營(yíng)業(yè)執(zhí)照注冊(cè)號(hào)（licence_number）”填寫錯(cuò)誤，請(qǐng)?zhí)顚憼I(yíng)業(yè)執(zhí)照上的注冊(cè)號(hào)，若主體類型為個(gè)體工商戶或企業(yè)，注冊(cè)號(hào)格式須為15位數(shù)字或18位數(shù)字|大寫字母。
# Q2：商戶開戶意愿調(diào)用“提交申請(qǐng)單”返回：系統(tǒng)繁忙，請(qǐng)稍后重試
A2：請(qǐng)按照以下幾點(diǎn)檢查：
- 系統(tǒng)異常，請(qǐng)使用相同參數(shù)稍后重新調(diào)用；
- 請(qǐng)求參數(shù)錯(cuò)誤，請(qǐng)確認(rèn)參數(shù)的大小寫、參數(shù)名、格式是否與接口文檔一致；
- 請(qǐng)求頭里面的參數(shù)mchid錯(cuò)誤，也會(huì)報(bào)這個(gè)錯(cuò)誤，請(qǐng)檢查確認(rèn)。
# Q3：商戶開戶意愿調(diào)用“撤消申請(qǐng)單”返回：查詢申請(qǐng)單不存在，請(qǐng)檢查申請(qǐng)單號(hào)是否正確
A3：請(qǐng)求參數(shù)申請(qǐng)單編號(hào)（applyment_id）填寫錯(cuò)誤或沒有填寫，請(qǐng)?zhí)顚懳⑿胖Ц斗峙涞纳暾?qǐng)單號(hào)，申請(qǐng)單編號(hào)和業(yè)務(wù)申請(qǐng)編號(hào)至少傳一個(gè)。
# Q4：商戶開戶意愿調(diào)用“獲取特約商戶授權(quán)狀態(tài)”返回：Authorization不合法
A4：請(qǐng)按照以下幾點(diǎn)檢查：
Authorization頭認(rèn)證類型或簽名信息錯(cuò)誤,請(qǐng)嚴(yán)格按照文檔要求填寫參數(shù)。
- Authorization頭認(rèn)證類型目前為WECHATPAY2-SHA256-RSA2048。
- Authorization頭簽名信息包括發(fā)起請(qǐng)求的商戶（渠道商）的商戶號(hào)mchid。
- 商戶API證書序列號(hào)serial_no，用于聲明所使用的證書
- 請(qǐng)求隨機(jī)串nonce_str
- 時(shí)間戳timestamp
- 簽名值signature
Authorization頭參數(shù)存在換行，實(shí)際數(shù)據(jù)應(yīng)在一行。
# Q5：商戶開戶意愿調(diào)用“提交申請(qǐng)單”返回：商戶未申請(qǐng)過證書，請(qǐng)到商戶平臺(tái)上申請(qǐng)證書授權(quán)機(jī)構(gòu)頒發(fā)的證書
A5：請(qǐng)按照錯(cuò)誤提示，到商戶平臺(tái)上申請(qǐng)下載API證書并正確使用，請(qǐng)參考以下幾點(diǎn)：
# Q6：商戶開戶意愿調(diào)用“撤銷申請(qǐng)單”返回：無法將傳入?yún)?shù)“申請(qǐng)單編號(hào)”轉(zhuǎn)換為uint64類型
A6：請(qǐng)求參數(shù)類型填寫錯(cuò)誤，正確的參數(shù)類型是uint64。
