小程序簽約API
最新更新時(shí)間：2023.11.07 版本說(shuō)明
商戶(hù)后臺(tái)通過(guò)請(qǐng)求此接口獲取到簽約會(huì)話(huà)id，然后再通過(guò)小程序簽約接口喚起小程序委托代扣的簽約頁(yè)面。
注意： ? 小程序簽約分為兩個(gè)步驟，步驟1通過(guò)預(yù)簽約接口獲得session_id，再通過(guò)步驟2調(diào)起簽約
注意： 步驟1：預(yù)簽約API
1. 接口說(shuō)明
適用對(duì)象： 直連模式 機(jī)構(gòu)模式
請(qǐng)求URL：https://apihk.mch.weixin.qq.com/v3/global/papay/contracts/miniprogram-pre-entrust-sign
請(qǐng)求方式：POST
Path指該參數(shù)為路徑參數(shù)
Query指該參數(shù)為URL參數(shù)
Body指該參數(shù)需在請(qǐng)求JSON傳參
時(shí)序圖
2. 請(qǐng)求參數(shù)
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 應(yīng)用ID | appid | string[1, 32] | 是 | Body商戶(hù)號(hào)綁定的appid 注意：僅適用于直連模式 示例值：wxcbda96de0b165486 |
| 子商戶(hù)號(hào) | sub_mchid | string[1, 32] | 是 | Body微信支付分配的子商戶(hù)號(hào) 注意：僅適用于機(jī)構(gòu)模式 示例值：10000097 |
| 服務(wù)商應(yīng)用ID | sp_appid | string[1, 32] | 是 | Body服務(wù)商綁定的appid 注意：僅適用于機(jī)構(gòu)模式 示例值：wxcbda96de0b165486 |
| 子商戶(hù)應(yīng)用ID | sub_appid | string[1, 32] | 否 | Body發(fā)起簽約的子商戶(hù)號(hào)綁定的appid 注意：僅適用于機(jī)構(gòu)模式 示例值：wxcbda96de0b165484 |
| 模板ID | plan_id | int | 是 | Body協(xié)議模板id，該模板ID是商戶(hù)在向微信支付提交代扣權(quán)限申請(qǐng)時(shí)由微信支付生成 示例值：123 |
| 商戶(hù)側(cè)簽約協(xié)議號(hào) | out_contract_code | string[1, 32] | 是 | Body商戶(hù)側(cè)的簽約協(xié)議號(hào)，由商戶(hù)生成，商戶(hù)側(cè)須唯一 示例值：100001256 |
| 用戶(hù)賬戶(hù)展示名稱(chēng) | user_display_name | string[1, 32] | 是 | Body簽約用戶(hù)的名稱(chēng)，用于頁(yè)面展示,不需要對(duì)值進(jìn)行urlencode，參數(shù)值不支持UTF8非3字節(jié)編碼的字符，例如表情符號(hào)，所以請(qǐng)勿傳微信昵稱(chēng)到該字段 示例值：張三 |
| 簽約成功通知url | success_notify_url | string[1, 256] | 是 | BodyHTTPS開(kāi)頭的回調(diào)通知url ,不需要對(duì)值進(jìn)行urlencode 示例值：https://yoursite.com |
| 商戶(hù)appid下的用戶(hù)標(biāo)識(shí) | openid | string[1, 128] | 是 | Body用戶(hù)在商戶(hù)appid下的openid，服務(wù)商模式為子商戶(hù)下的用戶(hù)openid，可詳見(jiàn)獲取openid 示例值：ouFhd5X9s9WteC3eWRjXV3lea123 |
| 用戶(hù)客戶(hù)端IP | user_client_ip | string[1, 32] | 否 | Body該字段要求填入用戶(hù)客戶(hù)端的IP，用戶(hù)簽約時(shí)會(huì)校驗(yàn)用戶(hù)客戶(hù)端IP與商戶(hù)傳的用戶(hù)客戶(hù)端IP一致，若不一致則視為商戶(hù)引導(dǎo)的用戶(hù)和實(shí)際訪(fǎng)問(wèn)用戶(hù)不一致，會(huì)拒絕該簽約請(qǐng)求。 示例值：119.145.83.6 |
| 過(guò)期時(shí)間 | expired_time | string[1, 64] | 否 | Body境外代扣簽約會(huì)話(huà)ID過(guò)期時(shí)間，遵循rfc3339標(biāo)準(zhǔn)格式，格式為YYYY-MM-DDTHH:mm:ss+TIMEZONE，YYYY-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開(kāi)頭，HH:mm:ss表示時(shí)分秒，TIMEZONE表示時(shí)區(qū)（+08:00表示東八區(qū)時(shí)間，領(lǐng)先UTC 8小時(shí)，即北京時(shí)間）。例如：2021-11-20T13:29:35+08:00表示，北京時(shí)間2021年11月20日 13點(diǎn)29分35秒。 示例值：2021-11-20T13:29:35+08:00 |
請(qǐng)求示例
{
"appid": "wxcbda96de0b165486",
"expired_time": "2021-11-20T13:29:35+08:00",
"openid": "ouFhd5X9s9WteC3eWRjXV3lea123",
"out_contract_code": "100001256",
"plan_id": 123,
"success_notify_url": "https://yoursite.com",
"user_client_ip": "119.145.83.6",
"user_display_name": "張三"
}
3. 返回參數(shù)
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 委托代扣簽約會(huì)話(huà)id | session_id | string[1,128] | 是 | 微信返回的委托代扣簽約會(huì)話(huà)id 示例值：201710180325670965 |
返回示例
{
"session_id": "201710180325670965"
}
4. 錯(cuò)誤碼
| 狀態(tài)碼 | 錯(cuò)誤碼 | 描述 | 解決方案 |
|---|---|---|---|
| 403 | CONTRACT_NOT_EXIST | Result Empty | 查詢(xún)的簽約協(xié)議不存在，或者傳入正確查詢(xún)參數(shù)重試 |
| 403 | CONTRACT_EXISTED | 已開(kāi)通自動(dòng)扣費(fèi)服務(wù)功能，無(wú)需重復(fù)開(kāi)通 | 已開(kāi)通自動(dòng)扣費(fèi)服務(wù)功能，無(wú)需重復(fù)開(kāi)通；如需重新簽約，需解約后再發(fā)起簽約 |
| 400 | PARAM_ERROR | 參數(shù)錯(cuò)誤 | 傳入正確查詢(xún)參數(shù) |
| 500 | SYSTEM_ERROR | 系統(tǒng)錯(cuò)誤 | 請(qǐng)稍等重試 |
步驟2：小程序簽約API
wx.navigateToMiniProgram
適用對(duì)象：直連模式 機(jī)構(gòu)模式
接口名稱(chēng)：wx.navigateToMiniProgram(OBJECT)接口，詳見(jiàn)小程序API文檔
接口說(shuō)明：iOS 微信客戶(hù)端 6.5.9 版本開(kāi)始支持，Android 客戶(hù)端在 6.5.10 版本開(kāi)始支持
請(qǐng)求參數(shù)
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信簽約小程序appid | appId | string[1,32] | 是 | 固定值：wxbd687630cd02ce1d 請(qǐng)?jiān)谛〕绦蚺渲梦募pp.json的配置項(xiàng)navigateToMiniProgramAppIdList中增加此appid 示例值：wxbd687630cd02ce1d |
| 場(chǎng)景信息傳遞給小程序的數(shù)據(jù) | extraData | object | 是 | Body將詳情見(jiàn)extraData字段詳細(xì)說(shuō)明 |
請(qǐng)求示例
wx.navigateToMiniProgram({
appId: wxbd687630cd02ce1d,
path: 'pages/Oversea/walletSelect?sessionId=201710180325670965',
extraData: {},
success(res) {
// 成功跳轉(zhuǎn)到簽約小程序
},
fail(res) {
// 未成功跳轉(zhuǎn)到簽約小程序
}
})
返回參數(shù)
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 委托代扣協(xié)議id | contract_id | string(64) | 是 | 簽約成功后微信返回的委托代扣協(xié)議id 示例值：201710180325670965 |
返回示例
App({
onShow(res) {
if (res.scene === 1038) { // 場(chǎng)景值1038：從被打開(kāi)的小程序返回
const { appId, extraData } = res.referrerInfo
if (appId == 'wxbd687630cd02ce1d') { // appId為wxbd687630cd02ce1d：從簽約小程序跳轉(zhuǎn)回來(lái)
if (typeof extraData == 'undefined'){
// TODO
// 客戶(hù)端小程序不確定簽約結(jié)果，需要向商戶(hù)側(cè)后臺(tái)請(qǐng)求確定簽約結(jié)果
return;
}
if(extraData.return_code == 'SUCCESS'){
// TODO
// 客戶(hù)端小程序簽約成功，需要向商戶(hù)側(cè)后臺(tái)請(qǐng)求確認(rèn)簽約結(jié)果
var contract_id = extraData.contract_id
return;
} else {
// TODO
// 簽約失敗
return;
}
}
}
}
})
頁(yè)面導(dǎo)航
