訂閱支付
2026/10/9大約 9 分鐘
訂閱支付說明
訂閱支付基於銀行卡（VISA/Mastercard）支付，支持商戶按訂閱週期向用戶發起扣款，適用於會員訂閱、週期性繳費等場景。訂閱支付通過 wayCode=CARD_H5 發起，涉及 CIT 與 MIT 兩種交易模式：
| 交易模式 | 說明 | 發起方 | 用戶是否參與 | channelExtra 參數 |
|---|---|---|---|---|
| CIT（Customer Initiated Transaction，客戶發起交易） | 首次訂閱支付，用戶在支付頁面完成銀行卡支付，並授權商戶後續按訂閱週期扣款 | 用戶 | 是 | isRebilling=0 |
| MIT（Merchant Initiated Transaction，商戶發起交易） | 後續訂閱扣款，商戶基於首次訂閱支付返回的支付憑證發起扣款，無需用戶參與 | 商戶 | 否 | isRebilling=1 |
isRebilling 置空表示普通支付，不涉及訂閱支付。
訂閱支付支付方式：CARD_H5（VISA/MC 銀行卡 H5，支持 CIT/MIT 訂閱支付）
訂閱支付流程
下圖展示了訂閱支付的完整流程，包含首次訂閱支付（CIT）與後續訂閱扣款（MIT）兩個階段：
流程說明：
- 用戶在商戶系統發起首次訂閱，商戶系統調用統一下單接口發起首次訂閱支付（CIT）
- 支付網關向渠道發起首次訂閱支付，返回支付跳轉鏈接
- 商戶系統引導用戶跳轉支付頁面，用戶完成銀行卡支付並授權後續扣款
- 支付成功後，支付網關通過支付通知或查詢訂單接口向商戶系統返回支付結果及
channelUserPaymentOptionId - 商戶系統保存
channelUserPaymentOptionId與首次訂閱訂單的payOrderId，用於後續訂閱扣款 - 訂閱週期到期時，商戶系統調用統一下單接口發起後續訂閱扣款（MIT），無需用戶參與
- 支付網關向渠道發起扣款，並通過支付通知或查詢訂單接口返回扣款結果，商戶按訂閱週期重複執行
統一下單（訂閱支付）
商戶業務系統通過統一下單接口發起訂閱支付訂單，支付網關根據 channelExtra 中的訂閱參數區分首次訂閱支付（CIT）與後續訂閱扣款（MIT）。
接口說明
請求URL：/api/pay/unifiedOrder
請求方式：POST
請求類型：application/json 或 application/x-www-form-urlencoded
請求參數
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商戶號 | mchNo | 是 | String(30) | M1621873433953 | 商戶號 |
| 應用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 應用ID |
| 商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商戶生成的訂單號 |
| 支付方式 | wayCode | 是 | String(30) | CARD_H5 | 支付方式，訂閱支付固定：CARD_H5 |
| 支付金額 | amount | 是 | int | 100 | 支付金額, 單位分 |
| 貨幣代碼 | currency | 是 | String(3) | HKD | 三位貨幣代碼，港幣:HKD |
| 客戶端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客戶端IPV4地址 |
| 商品標題 | subject | 是 | String(64) | 商品標題測試 | 商品標題 |
| 商品描述 | body | 是 | String(256) | 商品描述測試 | 商品描述 |
| 異步通知地址 | notifyUrl | 否 | String(256) | https://www.gnete.com.hk/notify.htm | 支付結果異步回調URL，只有傳了該值才會發起回調 |
| 跳轉通知地址 | returnUrl | 否 | String(256) | https://www.gnete.com.hk/return.htm | 支付結果同步跳轉通知URL |
| 失效時間 | expiredTime | 否 | int | 3600 | 訂單失效時間, 單位秒, 默認2小時. 訂單在(創建時間+失效時間)後失效 |
| 渠道參數 | channelExtra | 否 | String(256) | {"userTokenId": "user_10001"} | 特定渠道發起的額外參數, json格式字符串. 訂閱支付參數見下方channelExtra訂閱參數說明 |
| 擴展參數 | extParam | 否 | String(512) | 134586944573118714 | 商戶擴展參數, 回調時會原樣返回 |
| 請求時間 | reqTime | 是 | long | 1622016572190 | 請求接口時間, 13位時間戳 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本號，固定：1.0 |
| 簽名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 簽名值，詳見簽名算法 |
| 簽名類型 | signType | 是 | String(32) | MD5 | 簽名類型，目前只支持MD5方式 |
請求示例數據（首次訂閱支付 CIT）
{
"amount": 100,
"extParam": "",
"mchOrderNo": "mho1624005107281",
"subject": "月度會員訂閱",
"wayCode": "CARD_H5",
"sign": "84F606FA25A6EC4783BECC08D4FDC681",
"reqTime": "1624005107",
"body": "月度會員訂閱",
"version": "1.0",
"channelExtra": "{\"userTokenId\":\"user_10001\",\"isRebilling\":\"0\",\"rebillExpiry\":\"20271231\",\"rebillFrequency\":\"30\"}",
"appId": "60cc09bce4b0f1c0b83761c9",
"clientIp": "192.166.1.132",
"notifyUrl": "https://www.gnete.com.hk/notify.html",
"signType": "MD5",
"currency": "HKD",
"returnUrl": "",
"mchNo": "M1623984572"
}請求示例數據（後續訂閱扣款 MIT）
{
"amount": 100,
"extParam": "",
"mchOrderNo": "mho1624005107282",
"subject": "月度會員訂閱",
"wayCode": "CARD_H5",
"sign": "84F606FA25A6EC4783BECC08D4FDC681",
"reqTime": "1624005107",
"body": "月度會員訂閱",
"version": "1.0",
"channelExtra": "{\"userTokenId\":\"user_10001\",\"isRebilling\":\"1\",\"userPaymentOptionId\":\"384902353\",\"relatedTargetOrderId\":\"P202106181104177050002\"}",
"appId": "60cc09bce4b0f1c0b83761c9",
"clientIp": "192.166.1.132",
"notifyUrl": "https://www.gnete.com.hk/notify.html",
"signType": "MD5",
"currency": "HKD",
"returnUrl": "",
"mchNo": "M1623984572"
}返回參數
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回狀態 | code | 是 | int | 0 | 0-處理成功，其他-處理有誤，詳見錯誤碼 |
| 返回信息 | msg | 否 | String(128) | 簽名失敗 | 具體錯誤原因，例如：簽名失敗、參數格式校驗錯誤 |
| 簽名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 對data內數據簽名, 如data為空則不返回 |
| 返回數據 | data | 否 | String(512) | {} | 返回下單數據, json格式數據 |
data數據格式
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 支付訂單號 | payOrderId | 是 | String(30) | U12021022311124442600 | 返回支付系統訂單號 |
| 商戶訂單號 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 返回商戶傳入的訂單號 |
| 訂單狀態 | orderState | 是 | int | 2 | 支付訂單狀態 0-訂單生成 1-支付中 2-支付成功 3-支付失敗 4-已撤銷 5-已退款 6-訂單關閉 |
| 支付數據類型 | payDataType | 是 | String | payUrl | 支付參數類型, 訂閱支付為： payUrl-跳轉鏈接的方式 |
| 支付數據 | payData | 否 | String | http://www.gnete.com.hk/pay.html | 發起支付用到的支付參數，首次訂閱支付(CIT)時引導用戶跳轉該鏈接完成支付 |
| 渠道錯誤碼 | errCode | 否 | String | ACQ.PAYMENT_AUTH_CODE_INVALID | 上游渠道返回的錯誤碼 |
| 渠道錯誤描述 | errMsg | 否 | String | Business Failed 失敗 | 上游渠道返回的錯誤描述 |
返回示例數據
{
"code": 0,
"data": {
"mchOrderNo": "mho1624005107281",
"orderState": 1,
"payDataType": "payUrl",
"payData": "http://www.gnete.com.hk/pay.html",
"payOrderId": "P202106181642329900002"
},
"msg": "SUCCESS",
"sign": "F4DA202C516D1F33A12F1E547C5004FD"
}channelExtra訂閱參數說明
當 wayCode=CARD_H5 時，channelExtra傳訂閱支付相關參數：
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 用戶標識ID | userTokenId | 否 | String(64) | user_10001 | 用戶標識ID，訂閱支付時涉及（暫時僅部分渠道支持） |
| 訂閱支付標識 | isRebilling | 否 | String(1) | 0 | 置空-不涉及訂閱支付；0-首次訂閱支付(CIT)；1-非首次訂閱支付(MIT) |
| 訂閱支付到期日 | rebillExpiry | 否 | String(8) | 20271231 | 訂閱支付到期日，格式：YYYYMMDD，當isRebilling=0時必填 |
| 訂閱支付頻率 | rebillFrequency | 否 | String | 30 | 訂閱支付(扣款)頻率，單位：天，如30表示每30天扣款一次，當isRebilling=0時必填 |
| 用戶支付選項ID | userPaymentOptionId | 否 | String(64) | 384902353 | 首次訂閱支付成功返回的channelUserPaymentOptionId，當isRebilling=1時必填 |
| 關聯交易訂單號 | relatedTargetOrderId | 否 | String(30) | P202106181104177050002 | 關聯首次訂閱支付(CIT)成功訂單的支付訂單號payOrderId，當isRebilling=1時必填 |
訂閱支付返回字段
首次訂閱支付（CIT）成功後，渠道會返回用戶支付選項ID。支付網關在查詢訂單接口（/api/pay/query）與支付通知中新增返回如下字段：
| 字段名 | 變量名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 渠道用戶支付選項ID | channelUserPaymentOptionId | 否 | String(64) | 384902353 | 訂閱支付成功後渠道返回的用戶支付選項ID（部分渠道返回），商戶需保存，後續訂閱扣款(MIT)時作為userPaymentOptionId傳入 |
查詢訂單返回示例數據
{
"code": 0,
"data": {
"amount": 100,
"appId": "60cc09bce4b0f1c0b83761c9",
"body": "月度會員訂閱",
"channelOrderNo": "2021061822001423031419593035",
"channelUserPaymentOptionId": "384902353",
"createdAt": 1623985457705,
"currency": "HKD",
"extParam": "",
"ifCode": "inetpay",
"mchNo": "M1623984572",
"mchOrderNo": "mho1624005107281",
"payOrderId": "P202106181104177050002",
"state": 2,
"subject": "月度會員訂閱",
"successTime": 1623985459000,
"wayCode": "CARD_H5"
},
"msg": "SUCCESS",
"sign": "9548145EA12D0CD8C1628BCF44E19E0D"
}CIT/MIT 使用說明
首次訂閱支付（CIT）
- 調用統一下單接口，
wayCode=CARD_H5，channelExtra傳isRebilling=0，並傳userTokenId、rebillExpiry、rebillFrequency - 獲取返回的
payData（支付跳轉鏈接），引導用戶跳轉支付頁面，用戶完成銀行卡支付並授權後續扣款 - 支付成功後，通過支付通知或查詢訂單接口獲取
channelUserPaymentOptionId與payOrderId，並妥善保存：channelUserPaymentOptionId：後續訂閱扣款(MIT)時作為userPaymentOptionId傳入payOrderId：後續訂閱扣款(MIT)時作為relatedTargetOrderId傳入
後續訂閱扣款（MIT）
- 訂閱週期到期時，調用統一下單接口，
wayCode=CARD_H5，channelExtra傳isRebilling=1，並傳userTokenId、userPaymentOptionId（首次訂閱支付返回的channelUserPaymentOptionId）、relatedTargetOrderId（首次訂閱支付訂單的payOrderId） - 無需用戶參與，支付網關直接向渠道發起扣款
- 通過支付通知或查詢訂單接口獲取扣款結果，之後按訂閱週期重複執行扣款
注意事項
isRebilling置空表示普通支付，不涉及訂閱支付isRebilling只能為空、0或1，其他值下單失敗isRebilling=0時rebillExpiry、rebillFrequency必填，rebillExpiry必須為YYYYMMDD格式的8位數字isRebilling=1時userPaymentOptionId、relatedTargetOrderId必填relatedTargetOrderId傳首次訂閱支付(CIT)成功訂單的支付訂單號(payOrderId)，支付網關據此關聯渠道交易訂單，未找到對應訂單時下單失敗- 每次訂閱扣款均為獨立的支付訂單，需分別處理支付通知與對賬
- 訂閱支付涉及的銀行卡扣款，退款請參考退款接口文檔