简体中文

English

简体中文

English

主题

订阅下单 ​

订阅支付：客户与商家之间建立的一种协议，允许商家根据预先设定的时间自动从客户账户扣款。

请求参数 ​

POST
名称类型长度必填签名描述
subProductTypeString16YesYes订阅支付 subProductType 使用 SUBSCRIBE
subscriptionString1024YesYes订阅付款所需的订阅信息。 格式为 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\":\"test.test@qq.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"717.628.937-97\"}",
    "merchantCustId": "1728463902000",
    "merchantNo": "800209",
    "merchantTxnId": "1728463902000",
    "merchantTxnTime": "2024-10-09 16:51:42",
    "merchantTxnTimeZone": "+08:00",
    "orderAmount": "20",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"country\":\"US\",\"email\":\"test.test@qq.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"717.628.937-97\"}",
    "sign": "17c45492bc246884c618a8c8ca7aad7dc8b135ab31f9d685962d9befd5889b03",
    "subProductType": "SUBSCRIBE", 订阅类型
    "subscription": "{\"merchantCustId\":\"1728463902000\",\"requestType\":0,\"expireDate\":\"2030-11-11\",\"frequencyType\":\"D\",\"frequencyPoint\":1,\"bindCard\":\"true\",\"tokenId\":\"\",\"contractId\":\"\"}", 订阅支付参数
    "txnOrderMsg": "{\"returnUrl\":\"https://www.merchant-store-website.com/\",\"appId\":\"1739545982264549376\",\"notifyUrl\":\"https://www.feishu.cn/flow/api/trigger-webhook/3ce1bac4efb3f07ce53b515e7e760996\",\"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": "1843937371947925504",  交易流水号, 用于拉起SDK
        "responseTime": "2024-10-09 16:51:42",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "U",
        "redirectUrl": null,
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "sign": "05c06fd89b66f6f542433a1b3ddf658cec1d0bebec20c086fc4ca1fd9aed5dc2"
    }
}

订阅首购异步通知 ​

json
{
    "notifyType": "TXN",
    "transactionId": "1843937371947925504",
    "txnType": "SALE",
    "merchantNo": "800209",
    "merchantTxnId": "1728463902000",
    "responseTime": "2024-10-09 16:54:13",
    "txnTime": "2024-10-09 16:51:42",
    "txnTimeZone": "+08:00",
    "orderAmount": "20.00",
    "orderCurrency": "USD",
    "status": "S",
    "contractId": "1843937372027617280", 订阅合同号
    "tokenId": "77baa8f0b02af1cea0089b43823b44121d71223e74607b89d7613ae8ab2bd47e",订阅token
    "cardTokenId": "8c8143bd95015eece6b5bea380e6c44596efd33b0fc36126a45c47408de9d3da",绑卡token
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "c91a0fc5eb63e0996f618a6f2e470753c1fcfa579abd9f8e78cc9a6f7818b456",
    "paymentMethod": "VISA"
}

订阅复购 ​

注意

  • 目前Onerway的订阅复购需要商户来发起
  • 买家首购完成后，商户需要保存异步通知中的contractId和tokenId，在下次订阅复购时，将contractId和tokenId包含在请求参数中。详情请查看订阅复购接口