跳至主要內容

订阅支付

Easylink2026/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）两个阶段：

流程说明：

  1. 用户在商户系统发起首次订阅，商户系统调用统一下单接口发起首次订阅支付（CIT）
  2. 支付网关向渠道发起首次订阅支付，返回支付跳转链接
  3. 商户系统引导用户跳转支付页面，用户完成银行卡支付并授权后续扣款
  4. 支付成功后，支付网关通过支付通知或查询订单接口向商户系统返回支付结果及 channelUserPaymentOptionId
  5. 商户系统保存 channelUserPaymentOptionId 与首次订阅订单的 payOrderId，用于后续订阅扣款
  6. 订阅周期到期时，商户系统调用统一下单接口发起后续订阅扣款（MIT），无需用户参与
  7. 支付网关向渠道发起扣款，并通过支付通知或查询订单接口返回扣款结果，商户按订阅周期重复执行

统一下单（订阅支付）

商户业务系统通过统一下单接口发起订阅支付订单，支付网关根据 channelExtra 中的订阅参数区分首次订阅支付（CIT）与后续订阅扣款（MIT）。

接口说明

请求URL：/api/pay/unifiedOrder

请求方式：POST

请求类型：application/json 或 application/x-www-form-urlencoded

请求参数

字段名变量名必填类型示例值描述
商户号mchNo是String(30)M1621873433953商户号
应用IDappId是String(24)60cc09bce4b0f1c0b83761c9应用ID
商户订单号mchOrderNo是String(30)20160427210604000490商户生成的订单号
支付方式wayCode是String(30)CARD_H5支付方式，订阅支付固定：CARD_H5
支付金额amount是int100支付金额,单位分
货币代码currency是String(3)HKD三位货币代码,港币:HKD
客户端IPclientIp否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否int3600订单失效时间,单位秒,默认2小时.订单在(创建时间+失效时间)后失效
渠道参数channelExtra否String(256){"userTokenId": "user_10001"}特定渠道发起的额外参数,json格式字符串.订阅支付参数见下方channelExtra订阅参数说明
扩展参数extParam否String(512)134586944573118714商户扩展参数,回调时会原样返回
请求时间reqTime是long1622016572190请求接口时间,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是int00-处理成功，其他-处理有误，详见错误码
返回信息msg否String(128)签名失败具体错误原因，例如：签名失败、参数格式校验错误
签名信息sign否String(32)CCD9083A6DAD9A2DA9F668C3D4517A84对data内数据签名,如data为空则不返回
返回数据data否String(512){}返回下单数据,json格式数据

data数据格式

字段名变量名必填类型示例值描述
支付订单号payOrderId是String(30)U12021022311124442600返回支付系统订单号
商户订单号mchOrderNo是String(30)20160427210604000490返回商户传入的订单号
订单状态orderState是int2支付订单状态
0-订单生成
1-支付中
2-支付成功
3-支付失败
4-已撤销
5-已退款
6-订单关闭
支付数据类型payDataType是StringpayUrl支付参数类型,订阅支付为：
payUrl-跳转链接的方式
支付数据payData否Stringhttp://www.gnete.com.hk/pay.html发起支付用到的支付参数，首次订阅支付(CIT)时引导用户跳转该链接完成支付
渠道错误码errCode否StringACQ.PAYMENT_AUTH_CODE_INVALID上游渠道返回的错误码
渠道错误描述errMsg否StringBusiness 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传订阅支付相关参数：

字段名变量名必填类型示例值描述
用户标识IDuserTokenId否String(64)user_10001用户标识ID，订阅支付时涉及（暂时仅部分渠道支持）
订阅支付标识isRebilling否String(1)0置空-不涉及订阅支付；0-首次订阅支付(CIT)；1-非首次订阅支付(MIT)
订阅支付到期日rebillExpiry否String(8)20271231订阅支付到期日，格式：YYYYMMDD，当isRebilling=0时必填
订阅支付频率rebillFrequency否String30订阅支付(扣款)频率，单位：天，如30表示每30天扣款一次，当isRebilling=0时必填
用户支付选项IDuserPaymentOptionId否String(64)384902353首次订阅支付成功返回的channelUserPaymentOptionId，当isRebilling=1时必填
关联交易订单号relatedTargetOrderId否String(30)P202106181104177050002关联首次订阅支付(CIT)成功订单的支付订单号payOrderId，当isRebilling=1时必填

订阅支付返回字段

首次订阅支付（CIT）成功后，渠道会返回用户支付选项ID。支付网关在查询订单接口（/api/pay/query）与支付通知中新增返回如下字段：

字段名变量名必填类型示例值描述
渠道用户支付选项IDchannelUserPaymentOptionId否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）

  1. 调用统一下单接口，wayCode=CARD_H5，channelExtra传 isRebilling=0，并传 userTokenId、rebillExpiry、rebillFrequency
  2. 获取返回的 payData（支付跳转链接），引导用户跳转支付页面，用户完成银行卡支付并授权后续扣款
  3. 支付成功后，通过支付通知或查询订单接口获取 channelUserPaymentOptionId 与 payOrderId，并妥善保存：
    • channelUserPaymentOptionId：后续订阅扣款(MIT)时作为 userPaymentOptionId 传入
    • payOrderId：后续订阅扣款(MIT)时作为 relatedTargetOrderId 传入

后续订阅扣款（MIT）

  1. 订阅周期到期时，调用统一下单接口，wayCode=CARD_H5，channelExtra传 isRebilling=1，并传 userTokenId、userPaymentOptionId（首次订阅支付返回的channelUserPaymentOptionId）、relatedTargetOrderId（首次订阅支付订单的payOrderId）
  2. 无需用户参与，支付网关直接向渠道发起扣款
  3. 通过支付通知或查询订单接口获取扣款结果，之后按订阅周期重复执行扣款

注意事项

  • isRebilling 置空表示普通支付，不涉及订阅支付
  • isRebilling 只能为空、0或1，其他值下单失败
  • isRebilling=0 时 rebillExpiry、rebillFrequency 必填，rebillExpiry 必须为YYYYMMDD格式的8位数字
  • isRebilling=1 时 userPaymentOptionId、relatedTargetOrderId 必填
  • relatedTargetOrderId 传首次订阅支付(CIT)成功订单的支付订单号(payOrderId)，支付网关据此关联渠道交易订单，未找到对应订单时下单失败
  • 每次订阅扣款均为独立的支付订单，需分别处理支付通知与对账
  • 订阅支付涉及的银行卡扣款，退款请参考退款接口文档
最近更新:
贡献者: CN
默认页脚
Copyright © 2026 Easylink