简体中文

English

简体中文

English

主题

订阅支付 ​

订阅支付是指客户与商家之间建立的一种协议，允许商家根据预先设定的时间表自动收取客户的付款。

请求参数 ​

POST
名称类型长度必填签名描述
subProductTypeString16YesYes订阅支付 subProductType 使用 SUBSCRIBE
subscriptionString/YesYes订阅支付所需的订阅信息。 格式为 json 字符串。 请参阅对象 Subscription

Subscription ​

托管订阅（自动扣款） ​
订阅测试卡
json
卡号：4000000000002701
有效期：05/26
CVV：123
持卡人姓名：CL BRW2
json
卡号：5200000000001013
有效期：05/26
CVV：123
持卡人姓名：CL BRW2
json
卡号：4000000000001091
有效期：05/26
CVV：123
持卡人姓名：CL BRW2
json
卡号：4000000000001109
有效期：05/26
CVV：123
持卡人姓名：CL BRW2
json
卡号：5200000000001039
有效期：05/26
CVV：123
持卡人姓名：CL BRW2
订阅首购
升降级
名称类型长度必填描述
requestTypeString1Yes订阅请求类型，请参阅
merchantCustIdString40Yes商户系统中的用户唯一标识，用于关联用户与订阅信息。此ID将用于订阅的创建、查询和管理，请确保其在商户系统中的唯一性。
productNameString256No订阅产品名称，用于区分不同的订阅服务或套餐。不传入时，每个用户仅能创建一个订阅；传入时，同一用户可订阅多个不同产品。
frequencyTypeString1No订阅周期单位：
D-天
M-月
Y-年
决定账单周期的基本时间单位。
frequencyPointString2Yes建议的订阅周期值。

cycleCountint256No循环期数，支持1-100。
expireDateString10Yes订阅终止日期，格式为yyyy-MM-dd。超过此日期后，托管系统将不再触发扣款。
modeString1Yes签约模式：
1 - 先签约后扣款，需分两步完成
2 - 签约并立即扣款，一步完成（默认值）
selfExecuteString1Yes订阅扣款模式：
1 - 系统自动扣款（推荐）：由支付系统按照设定的频率自动执行周期性扣款
2 - 商户触发扣款：需要商户系统主动调用API发起每期扣款
非托管订阅
bindCardString300No订阅信用卡绑定选项：
true - 完成订阅并将卡信息绑定到用户ID
false - 仅完成订阅但不绑定卡信息
trialFromPlanString256No试用期计费模式:
0 - 试用期不计入订阅计划（不收费）
1 - 试用期计入订阅计划（收费）
trialDaysint256No试用期天数，支持范围 3-365 天。当设置试用期时，与 trialEnd 二选一。
trialEndString256No试用期结束日期，格式为yyyy-MM-dd。当设置试用期时，与trialDays二选一。
notificationEmailString256No买家订阅后邮件通知地址（含订阅扣款成功、取消订阅等其他邮件通知）。
metaDataString2048No商户自定义信息，用于存储业务数据。支持JSON格式，在查询订阅时原样返回。
json
// 试用首购 - 每天扣款一次，共30天，前3天为试用期且包含在订阅计划内，试用结束后自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"自动扣30天-试用3天（含）-1天1次\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"1\",\"trialDays\":3,\"notificationEmail\":\"abel.wang@onerway.com\"}"
json
// 试用首购 - 每天扣款一次，共33天，前3天为试用期且不包含在订阅计划内，试用结束后自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"自动扣30天-试用1天（不含）-1天1次\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"cycleCount\":30,\"selfExecute\":\"1\",\"trialFromPlan\":\"0\",\"trialEnd\":\"2024-11-07\",\"notificationEmail\":\"abel.wang@onerway.com\"}"
json
// 非试用首购 - 每天扣款一次直到指定过期日期（2024-12-04），无试用期，立即开始自动扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522099\",\"productName\":\"自动扣30天-无试用-1天1次-到期时间6\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\"}"
json
// 仅签约模式 - 每月扣款一次，签约但不立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522100\",\"productName\":\"仅签约-1月1次\",\"frequencyType\":\"M\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"mode\":\"1\"}"
json
// 升降级 - 每天扣款一次，共30天，立即升级, 补差价30
"subscription": "{\"requestType\":\"2\",\"tokenId\":\"tokenId_xxx\",\"contractId\":\"contractId_xxx\",\"productName\":\"订阅升级-立即生效并补差价\",\"proration\":\"30\",\"merchantCustId\":\"custId_xxx\"}"
非托管订阅（商户发起扣款） ​

注意

  • 商户需自行管理订阅周期和发起扣款操作
  • 不支持升降级、邮件通知、订阅管理页面
  • 订阅频率由商户控制，仅支持按天
首次订阅
续期订阅
名称类型长度必填描述
requestTypeString1Yes订阅请求类型：固定值为0（首购）。
merchantCustIdString40Yes商户系统中的用户唯一标识，用于关联用户与订阅信息。此ID将用于订阅的创建、查询和管理，请确保其在商户系统中的唯一性。
productNameString256No订阅产品名称，用于区分不同的订阅服务或套餐。不传入时，每个用户仅能创建一个订阅；传入时，同一用户可订阅多个不同产品。
frequencyTypeString1No订阅周期单位：非托管订阅模式下仅支持D（天）。
frequencyPointString2Yes建议的订阅周期值，表示每隔多少天。

expireDateString10Yes建议的订阅终止日期，格式为yyyy-MM-dd。
modeString1Yes签约模式：
1 - 先签约后扣款，需分两步完成
2 - 签约并立即扣款，一步完成（默认值）
selfExecuteString1Yes订阅扣款模式：
非托管订阅固定为2 - 商户触发扣款：由商户系统负责计算扣款时间并主动调用API发起每期扣款

订阅支付请求参数说明

进行订阅支付时，请参考标准收银台支付或SDK下单请求中的信用卡支付，并注意以下修改：

  1. 将 subProductType 参数值由 DIRECT 修改为 SUBSCRIBE
  2. 添加 subscription 参数包含订阅详情
json
{
  // 关键参数示例
  "subProductType": "SUBSCRIBE",  // 必须设置为SUBSCRIBE
  "subscription": "..."           // json格式订阅请求参数
}
json
// 非托管订阅 - 仅签约模式，不立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"非托管-仅签约\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"
json
// 非托管订阅 - 立即扣款模式，立即扣款
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"非托管-立即扣款\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}"
json
// 非托管订阅 - 续期扣款，使用已有订阅合同发起新一期扣款
"subscription": "{\"requestType\":\"1\",\"contractId\":\"contractId_xxx\",\"tokenId\":\"tokenId_xxx\",\"merchantCustId\":\"custId_xxx\"}"

订阅支付请求响应示例 ​

POST

订阅首购 ​

json
{
   "//": "订阅首购",
   "billingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\"}",
   "cardInfo": "{\"cardNumber\":\"4000020951595032\",\"cvv\":\"789\",\"month\":\"12\",\"year\":\"2030\",\"holderName\":\"CL BRW2\"}",
   "merchantCustId": "1721287451000",
   "merchantNo": "800209",
   "merchantTxnId": "1721287451000",
   "merchantTxnTime": "2024-07-18 15:24:11",
   "merchantTxnTimeZone": "+08:00",
   "orderAmount": "10",
   "orderCurrency": "USD",
   "productType": "CARD",
   "shippingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\"}",
   "sign": "93a3289383e3111b37bf3a9d41a5579acdfee43730b3dc5e36e2d0ea0e2fb02f",
   "subProductType": "SUBSCRIBE",  
   "subscription": "{\"merchantCustId\":\"1721287451000\",\"requestType\":0,\"expireDate\":\"2030-11-11\",\"frequencyType\":\"D\",\"frequencyPoint\":1,\"tokenId\":\"\",\"contractId\":\"\"}", 
   "txnOrderMsg": "{\"returnUrl\":\"https://www.merchant-store-website.com/\",\"appId\":\"1739545982264549376\",\"notifyUrl\":\"https://www.merchant-store-notify.com/\",\"products\":\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\",\"transactionIp\":\"127.0.0.1\"}",
   "txnType": "SALE"
}
json
{
    "//": "订阅首购",
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1813839291336761344",
        "responseTime": "2024-07-18 15:32:48",
        "txnTime": "2024-07-18 15:32:41",
        "txnTimeZone": "+08:00",
        "orderAmount": "10.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "S",
        "redirectUrl": null,
        "contractId": "1813839291387092992",  
        "tokenId": "42e76067938dd5d4250e475f376648cd8274c559c9a3484dffc094a996f4b02e",  
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "sign": "b6194118ac1f707cf4a6138b22c58296501a8ac0d011ae0d33e9e12265393471"
    }
}

商户需要保存首购响应中的 contractId 和 tokenId 用于后续的订阅复购请求。

订阅复购 ​

json
{
    "//": "订阅复购",
    "merchantCustId": "1721287886000",
    "merchantNo": "800209",
    "merchantTxnId": "1721287886000",
    "merchantTxnTime": "2024-07-18 15:31:26",
    "merchantTxnTimeZone": "+08:00",
    "orderAmount": "10",
    "orderCurrency": "USD",
    "productType": "CARD",
    "sign": "f752bdee4e1842787ce4fe1cb1cbb98e6acebfcc5bb199a8a605ae3b1bbc3fef",
    "subProductType": "SUBSCRIBE",  
    "subscription": "{\"requestType\":\"1\",\"tokenId\":\"822ba14cc565ab56887029673e244c57daf3eb2373a70a6bfd4132f1d8ad059c\",\"contractId\":\"1813837154846384128\",\"merchantCustId\":\"1721287886000\"}",  
    "txnOrderMsg": "{\"products\":\"[{\\\"price\\\":\\\"110.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"appId\":\"1739545982264549376\"}",
    "txnType": "SALE"
}
json
{
    "//": "订阅复购",
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1813838978852724736",
        "responseTime": "2024-07-18 15:31:29",
        "txnTime": "2024-07-18 15:31:26",
        "txnTimeZone": "+08:00",
        "orderAmount": "10.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "S",
        "redirectUrl": null,
        "contractId": "1813837154846384128",
        "tokenId": "822ba14cc565ab56887029673e244c57daf3eb2373a70a6bfd4132f1d8ad059c",  
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "sign": "2a07b1cd9fc2e8f52ab648fd398407f305fd2f4e67088641e9b51cf517ce1e74"
    }
}

此示例仅限参考 请勿拿此示例直接请求。