付款
接口介紹
| 業(yè)務(wù)流程 | 接口 | 簡(jiǎn)介 |
|---|---|---|
| 付款 | 付款 | 用于向微信用戶個(gè)人付款 目前支持向指定微信用戶的openid付款。（獲取openid參見微信公眾平臺(tái)開發(fā)者文檔： 網(wǎng)頁(yè)授權(quán)獲取用戶基本信息） |
請(qǐng)仔細(xì)閱讀以下注意事項(xiàng)：
◆ 當(dāng)返回錯(cuò)誤碼為“SYSTEMERROR”時(shí)，請(qǐng)不要更換商戶訂單號(hào)，一定要使用原商戶訂單號(hào)重試（支持在2個(gè)自然日內(nèi)重試），否則可能造成重復(fù)支付等資金風(fēng)險(xiǎn)。
◆ XML具有可擴(kuò)展性，因此返回參數(shù)可能會(huì)有新增，而且順序可能不完全遵循此文檔規(guī)范，如果在解析回包的時(shí)候發(fā)生錯(cuò)誤，請(qǐng)商戶務(wù)必不要換單重試，請(qǐng)商戶聯(lián)系客服確認(rèn)付款情況。如果有新回包字段，會(huì)更新到此API文檔中。
◆ 因?yàn)殄e(cuò)誤代碼字段err_code的值后續(xù)可能會(huì)增加，所以商戶如果遇到回包返回新的錯(cuò)誤碼，請(qǐng)商戶務(wù)必不要換單重試，請(qǐng)商戶聯(lián)系客服確認(rèn)付款情況。如果有新的錯(cuò)誤碼，會(huì)更新到此API文檔中。
◆ 錯(cuò)誤代碼描述字段err_code_des只供人工定位問題時(shí)做參考，系統(tǒng)實(shí)現(xiàn)時(shí)請(qǐng)不要依賴這個(gè)字段來(lái)做自動(dòng)化處理。
◆ 請(qǐng)商戶在自身的系統(tǒng)中合理設(shè)置付款頻次并做好并發(fā)控制，防范錯(cuò)付風(fēng)險(xiǎn)。
◆ 因商戶自身系統(tǒng)設(shè)置存在問題導(dǎo)致的資金損失，由商戶自行承擔(dān)。
接口調(diào)用請(qǐng)求說(shuō)明
| 請(qǐng)求Url | https://api.mch.weixin.qq.com/mmpaymkttransfers/promotion/transfers |
|---|---|
| 是否需要證書 | 是（證書及使用說(shuō)明詳見商戶證書） |
| 請(qǐng)求方式 | POST |
| 簽名方式 | MD5 |
| 接口調(diào)用頻率限制 | 100/s |
| 超時(shí)時(shí)間（同筆訂單最短重試時(shí)間） | 1s |
請(qǐng)求參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 描述 |
|---|---|---|---|---|---|
| 商戶賬號(hào)appid | mch_appid | 是 | wx8888888888888888 | String(128) | 申請(qǐng)商戶號(hào)的appid或商戶號(hào)綁定的appid |
| 商戶號(hào) | mchid | 是 | 1900000109 | String(32) | 微信支付分配的商戶號(hào) |
| 設(shè)備號(hào) | device_info | 否 | 013467007045764 | String(32) | 微信支付分配的終端設(shè)備號(hào) |
| 隨機(jī)字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 隨機(jī)字符串，不長(zhǎng)于32位 |
| 簽名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 簽名，詳見簽名算法 |
| 商戶訂單號(hào) | partner_trade_no | 是 | 10000098201411111234567890 | String(32) | 商戶訂單號(hào)，需保持唯一性 (只能是字母或者數(shù)字，不能包含有其它字符) |
| 用戶openid | openid | 是 | oxTWIuGaIt6gTKsQRLau2M0yL16E | String(64) | openid是微信用戶在公眾賬號(hào)下的唯一用戶標(biāo)識(shí)（appid不同，則獲取到的openid就不同），可用于永久標(biāo)記一個(gè)用戶。 獲取openid的鏈接 |
| 校驗(yàn)用戶姓名選項(xiàng) | check_name | 是 | FORCE_CHECK | String(16) | NO_CHECK：不校驗(yàn)真實(shí)姓名 FORCE_CHECK：強(qiáng)校驗(yàn)真實(shí)姓名 |
| 收款用戶姓名 | re_user_name | 否 | 王小王 | String(64) | 收款用戶真實(shí)姓名。 如果check_name設(shè)置為FORCE_CHECK，則必填用戶真實(shí)姓名； 如需電子回單，需要傳入收款用戶姓名。 商戶需確保向微信支付傳輸用戶身份信息和賬號(hào)標(biāo)識(shí)信息做一致性校驗(yàn)已合法征得用戶授權(quán)。 |
| 金額 | amount | 是 | 10099 | int | 付款金額，單位為分 |
| 付款備注 | desc | 是 | 理賠 | String(100) | 付款備注，必填。 |
| Ip地址 | spbill_create_ip | 否 | 192.168.0.1 | String(32) | 該IP同在商戶平臺(tái)設(shè)置的IP白名單中的IP沒有關(guān)聯(lián)，該IP可傳用戶端或者服務(wù)端的IP。 |
| 付款場(chǎng)景 | scene | 否 | BRAND_REDPACKET | String(64) | BRAND_REDPACKET：品牌紅包， 其他值或不傳則默認(rèn)為普通付款到零錢 （品牌紅包能力暫未全量開放，若有意愿參與內(nèi)測(cè)請(qǐng)?zhí)顚憜柧?a rel="noopener" target="_blank">https://wj.qq.com/s2/9229085/29f4/） |
| 品牌ID | brand_id | 否 | 1234 | int | 品牌在微信支付的唯一標(biāo)識(shí)。僅在付款場(chǎng)景為品牌紅包時(shí)必填。 |
| 消息模板ID | finder_template_id | 否 | 1243100000000000 | String(128) | 品牌所配置的消息模板的唯一標(biāo)識(shí)。僅在付款場(chǎng)景為品牌紅包時(shí)必填。 |
請(qǐng)求示例：
<xml>
<mch_appid>wxe062425f740c30d8</mch_appid>
<mchid>10000098</mchid>
<nonce_str>3PG2J4ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
<partner_trade_no>100000982014120919616</partner_trade_no>
<openid>ohO4Gt7wVPxIT1A9GjFaMYMiZY1s</openid>
<check_name>FORCE_CHECK</check_name>
<re_user_name>張三</re_user_name>
<amount>100</amount>
<desc>節(jié)日快樂!</desc>
<spbill_create_ip>10.2.3.10</spbill_create_ip>
<sign>C97BDBACF37622775366F38B629F45E3</sign>
</xml>
返回參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 描述 |
|---|---|---|---|---|---|
| 返回狀態(tài)碼 | return_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 此字段是通信標(biāo)識(shí)，非交易標(biāo)識(shí)，交易是否成功需要查看result_code來(lái)判斷 |
| 返回信息 | return_msg | 否 | 簽名失敗 | String(128) | 返回信息，如非空，為錯(cuò)誤原因 簽名失敗 參數(shù)格式校驗(yàn)錯(cuò)誤 |
以下字段在return_code為SUCCESS的時(shí)候有返回
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 描述 |
|---|---|---|---|---|---|
| 商戶appid | mch_appid | 是 | wx8888888888888888 | String(128) | 申請(qǐng)商戶號(hào)的appid或商戶號(hào)綁定的appid（號(hào)corpid即為此appId） |
| 商戶號(hào) | mchid | 是 | 1900000109 | String(32) | 微信支付分配的商戶號(hào) |
| 設(shè)備號(hào) | device_info | 否 | 013467007045764 | String(32) | 微信支付分配的終端設(shè)備號(hào)， |
| 隨機(jī)字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 隨機(jī)字符串，不長(zhǎng)于32位 |
| 業(yè)務(wù)結(jié)果 | result_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL，注意：當(dāng)狀態(tài)為FAIL時(shí)，存在業(yè)務(wù)結(jié)果未明確的情況。如果狀態(tài)為FAIL，請(qǐng)務(wù)必關(guān)注錯(cuò)誤代碼（err_code字段），通過(guò)查詢接口確認(rèn)此次付款的結(jié)果。 |
| 錯(cuò)誤代碼 | err_code | 否 | SYSTEMERROR | String(32) | 錯(cuò)誤碼信息，注意：出現(xiàn)未明確的錯(cuò)誤碼時(shí)（SYSTEMERROR等），請(qǐng)務(wù)必用原商戶訂單號(hào)重試，或通過(guò)查詢接口確認(rèn)此次付款的結(jié)果。 |
| 錯(cuò)誤代碼描述 | err_code_des | 否 | 系統(tǒng)錯(cuò)誤 | String(128) | 結(jié)果信息描述 |
以下字段在return_code 和result_code都為SUCCESS的時(shí)候有返回
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 描述 |
|---|---|---|---|---|---|
| 商戶訂單號(hào) | partner_trade_no | 是 | 1217752501201407033233368018 | String(32) | 商戶訂單號(hào)，需保持歷史全局唯一性(只能是字母或者數(shù)字，不能包含有其它字符) |
| 微信付款單號(hào) | payment_no | 是 | 1007752501201407033233368018 | String(64) | 付款成功，返回的微信付款單號(hào) |
| 付款成功時(shí)間 | payment_time | 是 | 2015-05-19 15:26:59 | String(32) | 付款成功時(shí)間 |
成功示例：
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[]]></return_msg>
<mch_appid><![CDATA[wxec38b8ff840bd989]]></mch_appid>
<mchid><![CDATA[10013274]]></mchid>
<device_info><![CDATA[]]></device_info>
<nonce_str><![CDATA[lxuDzMnRjpcXzxLx0q]]></nonce_str>
<result_code><![CDATA[SUCCESS]]></result_code>
<partner_trade_no><![CDATA[10013574201505191526582441]]></partner_trade_no>
<payment_no><![CDATA[1000018301201505190181489473]]></payment_no>
<payment_time><![CDATA[2015-05-19 15:26:59]]></payment_time>
</xml>
錯(cuò)誤示例：
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[系統(tǒng)繁忙,請(qǐng)稍后再試.]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code><![CDATA[SYSTEMERROR]]></err_code>
<err_code_des><![CDATA[系統(tǒng)繁忙,請(qǐng)稍后再試.]]></err_code_des>
</xml>
錯(cuò)誤碼
| 錯(cuò)誤代碼 | 描述 | 原因 | 解決方案 |
|---|---|---|---|
| NO_AUTH | 沒有該接口權(quán)限 | 1. 用戶賬號(hào)被凍結(jié)，無(wú)法付款 2. 產(chǎn)品權(quán)限沒有開通或者被風(fēng)控凍結(jié) 3. 此IP地址不允許調(diào)用接口，如有需要請(qǐng)登錄微信支付商戶平臺(tái)更改配置 |
請(qǐng)根據(jù)具體的錯(cuò)誤返回描述做對(duì)應(yīng)處理，如返回描述不夠明確，請(qǐng)參考此處的錯(cuò)誤原因做排查。 |
| AMOUNT_LIMIT | 金額超限 |
1. 被微信風(fēng)控?cái)r截，最低單筆付款限額調(diào)整為5元。 2. 低于最低單筆付款限額或者高于最高單筆付款限額 |
目前最低付款金額為1元，最高10萬(wàn)元，請(qǐng)確認(rèn)是否付款金額超限。 |
| PARAM_ERROR | 參數(shù)錯(cuò)誤 | 1. 請(qǐng)求參數(shù)校驗(yàn)錯(cuò)誤 2. 字符中包含非utf8字符 3. 商戶號(hào)和appid沒有綁定關(guān)系 |
請(qǐng)參照原因檢查您的請(qǐng)求參數(shù)是否正確。 |
| PARAM_ERROR | 轉(zhuǎn)賬備注設(shè)置失敗 | 付款備注設(shè)置失敗 | 請(qǐng)調(diào)整對(duì)應(yīng)文案后重新再試。 |
| OPENID_ERROR | Openid錯(cuò)誤 | Openid格式錯(cuò)誤或者不屬于商家公眾賬號(hào) | Openid與appid是有一一映射關(guān)系的，請(qǐng)確保正確使用。 |
| SEND_FAILED | 付款錯(cuò)誤 | 付款錯(cuò)誤，請(qǐng)查單確認(rèn)付款結(jié)果 |
請(qǐng)查單確認(rèn)付款結(jié)果，以查單結(jié)果為準(zhǔn)。 |
| NOTENOUGH | 余額不足 | 您的付款賬號(hào)余額不足或資金未到賬 |
如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| SYSTEMERROR | 系統(tǒng)繁忙，請(qǐng)稍后再試。 | 微信內(nèi)部接口調(diào)用發(fā)生錯(cuò)誤 |
請(qǐng)先調(diào)用查詢接口，查看此次付款結(jié)果，如結(jié)果為不明確狀態(tài)（如訂單號(hào)不存在），請(qǐng)務(wù)必使用原商戶訂單號(hào)進(jìn)行重試。 |
| NAME_MISMATCH | 姓名校驗(yàn)出錯(cuò) | 收款人身份校驗(yàn)不通過(guò) |
如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| SIGN_ERROR | 簽名錯(cuò)誤 | 校驗(yàn)簽名錯(cuò)誤 |
請(qǐng)檢查您的請(qǐng)求參數(shù)和簽名密鑰KEY是否正確，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| XML_ERROR | Post內(nèi)容出錯(cuò) | Post請(qǐng)求數(shù)據(jù)不是合法的xml格式內(nèi)容 |
格式問題，請(qǐng)檢查請(qǐng)求格式是否正確。 |
| FATAL_ERROR | 兩次請(qǐng)求參數(shù)不一致 | 兩次請(qǐng)求商戶單號(hào)一樣，但是參數(shù)不一致 |
重入必須保證所有參數(shù)值都不變。 |
| FREQ_LIMIT | 超過(guò)頻率限制，請(qǐng)稍后再試。 | 接口請(qǐng)求頻率超時(shí)接口限制 |
調(diào)用接口過(guò)于頻繁，請(qǐng)稍后再試，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| MONEY_LIMIT | 已經(jīng)達(dá)到今日付款總額上限/已達(dá)到付款給此用戶額度上限 | 請(qǐng)關(guān)注接口的付款限額條件 |
付款額度已經(jīng)超限，請(qǐng)參考接口使用條件，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| CA_ERROR | 商戶API證書校驗(yàn)出錯(cuò) | 請(qǐng)求沒帶商戶API證書或者帶上了錯(cuò)誤的商戶API證書 | 您使用的調(diào)用證書有誤，請(qǐng)確認(rèn)是否使用了正確的證書，可以前往商戶平臺(tái)重新下載，證書需與商戶號(hào)對(duì)應(yīng)，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| V2_ACCOUNT_SIMPLE_BAN | 無(wú)法給未實(shí)名用戶付款 | 用戶微信支付賬戶未實(shí)名，無(wú)法付款 | 不支持給未實(shí)名用戶付款，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
| PARAM_IS_NOT_UTF8 | 請(qǐng)求參數(shù)中包含非utf8編碼字符 | 接口規(guī)范要求所有請(qǐng)求參數(shù)都必須為utf8編碼 |
微信接口使用編碼是UTF-8，請(qǐng)確認(rèn)，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
SENDNUM_LIMIT |
該用戶今日付款次數(shù)超過(guò)限制,如有需要請(qǐng)進(jìn)入【微信支付商戶平臺(tái)-產(chǎn)品中心-付款到零錢-產(chǎn)品設(shè)置】進(jìn)行修改 |
該用戶今日付款次數(shù)超過(guò)限制,如有需要請(qǐng)進(jìn)入【微信支付商戶平臺(tái)-產(chǎn)品中心-付款到零錢-產(chǎn)品設(shè)置】進(jìn)行修改 |
向用戶付款的次數(shù)超限了，請(qǐng)參考接口使用條件，如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試。 |
RECV_ACCOUNT_NOT_ALLOWED |
收款賬戶不在收款賬戶列表 |
收款賬戶不在收款賬戶列表 |
請(qǐng)登陸商戶平臺(tái)，查看產(chǎn)品中心付款到零錢的產(chǎn)品配置 |
PAY_CHANNEL_NOT_ALLOWED |
本商戶號(hào)未配置API發(fā)起能力? |
本商戶號(hào)未配置API發(fā)起能力? |
請(qǐng)登陸商戶平臺(tái)，查看產(chǎn)品中心付款到零錢的產(chǎn)品配置 |
| SEND_MONEY_LIMIT | 已達(dá)到今日商戶付款額度上限 | 請(qǐng)?zhí)岣呱虘舾犊铑~度，或明日再試 | 如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試 |
| RECEIVED_MONEY_LIMIT | 已達(dá)到今日付款給此用戶額度上限 | 請(qǐng)?zhí)岣哂脩羰湛铑~度，或明日再試 | 如果要繼續(xù)付款必須使用原商戶訂單號(hào)重試 |
| PARAM_ERROR | 付款商戶號(hào)無(wú)法使用該品牌信息 | 付款商戶號(hào)不是該品牌的品牌主商戶號(hào)或門店收款商戶號(hào) | 使用品牌的品牌主商戶號(hào)或門店收款商戶號(hào)進(jìn)行付款 |
| NO_AUTH | 付款商戶號(hào)無(wú)品牌紅包產(chǎn)品權(quán)限 | 付款商戶號(hào)沒有品牌紅包產(chǎn)品權(quán)限 | 付款商戶號(hào)開通品牌紅包產(chǎn)品權(quán)限后再進(jìn)行付款 |
| PARAM_ERROR | 品牌信息查詢失敗，請(qǐng)確認(rèn)品牌狀態(tài)有效 | 品牌已被注銷或狀態(tài)無(wú)效 | 確認(rèn)品牌信息有效后重試 |
| PARAM_ERROR | 品牌和視頻號(hào)沒有綁定關(guān)系 | 品牌和視頻號(hào)沒有綁定或已解綁 | 確認(rèn)品牌和視頻號(hào)仍然是綁定狀態(tài)后重試 |
| PARAM_ERROR | 品牌下未查到對(duì)應(yīng)品牌紅包消息模板 | 品牌和品牌紅包消息模板沒有對(duì)應(yīng)關(guān)系 | 確認(rèn)品牌和消息模版的對(duì)應(yīng)關(guān)系后重試 |
| PARAM_ERROR | 品牌紅包消息模板已被刪除 | 品牌紅包消息模板已被刪除 | 傳入未被刪除的消息模版 |
| EXCEED_PAYEE_ACCOUNT_LIMIT | 用戶賬戶收款受限 | 收款用戶身份信息待完善 | 請(qǐng)聯(lián)系用戶完善其在微信支付的身份信息以繼續(xù)收款 |
| PAYER_ACCOUNT_ABNORMAL | 商戶賬戶付款受限 | 商戶號(hào)被處罰、凍結(jié) | 可前往“商戶平臺(tái)>賬戶中心>違約記錄”或“商家助手小程序>風(fēng)險(xiǎn)處理”了解更多詳情，解除功能限制指引 |
| PAYEE_ACCOUNT_ABNORMAL | 用戶賬戶收款異常 | 收款用戶身份信息待完善 | 請(qǐng)引導(dǎo)用戶完善其在微信支付的身份信息以繼續(xù)收款 |
| PAYMENT_IN_PROGRESS | 該筆付款正在處理中 | 該筆付款正在處理中 | 請(qǐng)稍后查詢付款結(jié)果 |