Payments

简体中文

English

简体中文

English

主题

订阅 ​

API 请求参数 ​

POST

订阅支付关键参数

在集成订阅支付时，相比常规的收银台支付，您需要调整两个关键参数：

  1. subProductType: 所有订阅交易必须设置为 SUBSCRIBE。

  2. subscription: JSON 格式字符串，包含订阅详情，所有订阅交易都需要此参数。

json
{
  // ...
  "subProductType": "SUBSCRIBE",
  "subscription": "参见下表"
  // ...
}

托管订阅 ​

初始订阅
订阅更新
NameTypeLengthRequiredDescription

requestType

String

1

Yes

Subscription request type, please refer to

RequestTypeEnum

merchantCustId

String

40

Yes

Unique identifier for the user in the merchant's system, used to associate the user with subscription information. This ID will be used for subscription creation, query, and management. Please ensure its uniqueness in your system.


productName

String

256

Conditional

Subscription product name, used to distinguish different subscription services or plans. If not provided, each user can only create one subscription; if provided, the same user can subscribe to multiple different products.


frequencyType

String

1

Conditional

Subscription cycle unit. See

FrequencyTypeEnum

frequencyPoint

String

2

Conditional

Subscription cycle value for managed subscriptizons.



cycleCount

int

256

Conditional

Number of cycles, supports 1-99. Either cycleCount or expireDate is required.


expireDate

String

10

Conditional

Subscription termination date, format is yyyy-MM-dd. Either cycleCount or expireDate is required.


mode

String

1

Conditional

Subscription authorization mode. See

SubscriptionModeEnum

selfExecute

String

1

Yes

Subscription billing mode. See

SubscriptionExecuteModeEnum

bindCard

String

300

No

Subscription credit card binding option. See

SubscriptionBindCardEnum

trialFromPlan

String

256

Conditional

Trial period billing mode. See

SubscriptionTrialModeEnum

trialDays

int

256

Conditional

Trial period days, supports range from 3-365 days. When setting a trial period, choose either this or trialEnd.


trialEnd

String

256

Conditional

Trial period end date, format is yyyy-MM-dd. When setting a trial period, choose either this or trialDays.


notificationEmail

String

256

No

Buyer's email address for subscription notifications (including successful subscription billing, subscription cancellation, and other notifications).


metaData

String

2048

No

Merchant custom information, used to store business data. Supports JSON format, returned as-is when querying subscriptions.


代码示例 ​

json
// 试用期初始购买 - 每天计费一次，持续30天，订阅计划中包含3天试用期，试用期结束后自动计费

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522000\",\"productName\":\"自动计费30天-试用3天(包含)-每日一次\",\"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天(不包含)-每日一次\",\"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天-无试用-每日一次-到期时间6\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\"}"
json
// 仅签约模式 - 每月计费一次，签署协议但不立即计费

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_1640247522100\",\"productName\":\"仅签约-每月一次\",\"frequencyType\":\"M\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-12-04\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"mode\":\"1\"}"

自主管理订阅 ​

初始订阅
续费订阅
NameTypeLengthRequiredDescription

requestType

String

1

Yes

Subscription request type: Fixed value 0 (initial purchase).


merchantCustId

String

40

Yes

Unique identifier for the user in the merchant's system, used to associate the user with subscription information. This ID will be used for subscription creation, query, and management. Please ensure its uniqueness in your system.


productName

String

256

Conditional

Subscription product name, used to distinguish different subscription services or plans. If not provided, each user can only create one subscription; if provided, the same user can subscribe to multiple different products.


frequencyType

String

1

Yes

Subscription cycle unit: self-managed subscription mode only supports D (day).


frequencyPoint

String

2

Yes

Suggested subscription cycle value, indicating how many days between billings.



expireDate

String

10

Yes

Subscription termination date, format is yyyy-MM-dd. After this date, the system will not allow any further subscription charges.


mode

String

1

Yes

Subscription authorization mode. See

SubscriptionModeEnum

selfExecute

String

1

Yes

Subscription billing mode. See

SubscriptionExecuteModeEnum

代码示例 ​

json
// 自主管理订阅 - 仅签约模式，不立即计费
// 适用于本地支付方式如微信、DANA、GCash或TOUCH_GO_EWALLET

"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
// 自主管理订阅 - 续费计费，使用现有订阅合约发起新的计费周期
// 使用初始订阅webhook收到的contractId和tokenId

"subscription": "{\"requestType\":\"1\",\"contractId\":\"contractId_xxx\",\"tokenId\":\"tokenId_xxx\",\"merchantCustId\":\"custId_xxx\"}"
json
// DANA、微信、GCash或TOUCH_GO_EWALLET订阅示例
// 零金额初始交易以建立合约

"lpmsInfo": "{\"lpmsType\":\"DANA\",\"iBan\":\"DE89370400440532013000\"}",
"productType": "LPMS",
"subProductType": "SUBSCRIBE",
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

订阅集成流程 ​

Onerway 订阅流程包含三个主要阶段，如下所示：

1. 订阅发起 ​

在此阶段：

  • 商户系统向 收银台 API 发送订阅请求，包含 subProductType=SUBSCRIBE 和订阅详情
  • subscription 参数必须包含频率信息、产品详情和可选的试用期设置
  • Onerway 创建交易记录和订阅合约
  • 初始订阅状态为 Unfinished (U)

2. 收银台流程 ​

在此阶段：

  • 商户使用 redirectUrl 将客户浏览器重定向到 Onerway 收银台页面
  • 客户选择支付方式并输入支付信息
  • 如果需要3DS验证，客户在建立订阅之前完成此步骤
  • 支付信息被安全存储用于未来的续费扣款（如果使用托管订阅）

3. 订阅确认 ​

在此阶段：

  • 同步通知: 客户通过 returnUrl 被重定向回商户网站
  • 异步通知 (webhook): Onerway 向 notifyUrl 发送详细的订阅结果数据
  • 订阅邮件（仅托管订阅）: 向 notificationEmail 发送确认邮件，包含订阅详情和管理URL
  • webhook 包含完整的订阅信息，包括 transactionId、contractId、tokenId 和 subscriptionStatus
  • 商户系统必须响应 transactionId 以确认收到webhook
  • 如果没有收到成功响应，Onerway 将重试发送webhook 3 次

有关订阅交易期间收到的所有webhook通知字段的完整描述，包括订阅特定字段如 contractId、tokenId、subscriptionStatus 和 scenarios，请参考 Webhook 通知文档。

支付完成示例 ​

plaintext
https://www.merchant-store-website.com/?transactionId=1853980684692361216&merchantTxnId=1730858419000&merchantNo=800209&responseTime=2024-11-06%2010%3A22%3A47&txnTime=2024-11-06%2010%3A22%3A06&txnTimeZone=%2008%3A00&orderAmount=0.00&orderCurrency=USD&txnAmount=0.00&txnCurrency=USD&status=S&reason=Payment%20successful&contractId=1853980684755275776&tokenId=2a262447389a33cbab0a1221fd6a0f36fd7cab70d0abf1b0a34bae3aae67ba19
json
{
  "notifyType": "TXN",
  "transactionId": "1919772912060342272",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "ec91ee2b-7ba9-444f-8875-955fe94fadf3",
  "responseTime": "2025-05-06 23:15:33",
  "txnTime": "2025-05-06 23:15:20",
  "txnTimeZone": "+08:00",
  "orderAmount": "2.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919772912228114432", 
  "tokenId": "195f7e75785863a66d3801ae02c12e24ea16abe164303cf3e3fd10e04d5e4188", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "6e8bd132b805c6ad530857331bef43c25e4c4a544dc2e0494cfd1ad94a7f55dc",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5NzcyOTEyMjI4MTE0NDMyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUtYUlAtMzcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", 
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"currant\",\"num\":\"78\",\"price\":\"620.39\",\"type\":\"ullamco et do commodo ut\"},{\"currency\":\"USD\",\"name\":\"strawberry\",\"num\":\"63\",\"price\":\"289.61\",\"type\":\"labore cupidatat Duis elit\"},{\"currency\":\"USD\",\"name\":\"grapefruit\",\"num\":\"24\",\"price\":\"989.09\",\"type\":\"ullamco non\"}]",
  "metaData": "eventually",
  "channelRequestId": "8002091919772982323052544",
  "scenarios": "SUBSCRIPTION_INITIAL"
}
json
{
  "notifyType": "TXN",
  "transactionId": "1914230281599320064",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "8a4e276e-86c2-4753-b91a-0cc8881e4d0d",
  "responseTime": "2025-04-21 16:10:58",
  "txnTime": "2025-04-21 16:10:38",
  "txnTimeZone": "+08:00",
  "orderAmount": "33.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1914230281792258048", 
  "tokenId": "7a83c22d55ca1e383fefbf1537c90b065a7324aee29a36d4b39c66da377a9b57", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "432894a2c697e01e4fe86eaa4f2564fb13ea97d0b4662a45fc83d1aa076985d1",
  "paymentMethod": "VISA",
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"mandarin\",\"num\":\"47\",\"price\":\"234.19\",\"type\":\"eu dolore in\"}]",
  "metaData": "pfft",
  "channelRequestId": "8002091914230287013908481",
  "scenarios": "SUBSCRIPTION_INITIAL"
}

4. 续费计费流程 ​

托管订阅
自主管理订阅

在托管订阅中：

  • Onerway 根据订阅计划自动处理所有续费扣款
  • 每次续费付款都会向商户生成webhook通知
  • 客户可以通过确认邮件中提供的 subscriptionManageUrl 管理订阅
  • 管理门户允许客户查看订阅历史、更新付款方式或取消订阅

重要注意事项 ​

  • 对于自主管理订阅: 商户必须使用 订阅管理 API 发起续费付款
  • 必须保存订阅合约（contractId）和付款令牌（tokenId）用于未来的续费交易
  • 始终依赖webhook通知作为订阅状态的权威来源
  • 可能会收到多个webhook通知；建议基于交易ID进行去重
  • 交易状态 S 表示成功，F 表示失败；其他状态代码请参考 TxnStatusEnum

API 使用示例 ​

Onerway 会将所有订阅事件的 webhook 通知发送到原始订阅请求中指定的 notifyUrl。这些通知提供订阅状态变更的实时更新。

Webhook 场景

webhook 通知中的 scenarios 字段表示触发通知的特定订阅事件。

订阅场景枚举：

ValueDescription

SUBSCRIPTION_INITIAL

Initial subscription purchase - Customer signs up and makes first payment to activate new subscription

SUBSCRIPTION_RENEWAL

Recurring subscription payment - Billing for ongoing subscription service according to billing cycle

SUBSCRIPTION_CARD_REPLACEMENT

Payment method update - Customer updates expired or invalid card information for existing subscription

SUBSCRIPTION_CHANGED

Subscription modification - Customer upgrades, downgrades, or changes subscription plan terms

SUBSCRIPTION_CANCELED

Subscription termination - Customer or merchant initiates cancellation, stopping future billing

SUBSCRIPTION_ENDED

Subscription expiration - Natural conclusion when subscription reaches its predetermined end date

这些场景值帮助您准确识别订阅的不同生命周期阶段，便于实施相应的业务逻辑处理。

订阅状态参考

响应和 Webhook 中的 subscriptionStatus 字段表示订阅的当前状态。

订阅状态枚举：

CodeDescription

trialing

In trial period


paymentdue

Payment pending


active

Active subscription


pastdue

Payment overdue


paused

Temporarily suspended


canceled

Canceled by user or merchant


ended

Completed subscription term


这些状态值帮助您理解订阅生命周期，并为每个状态实施适当的业务逻辑。

初始订阅请求 ​

这些示例展示如何创建带有和不带有试用期的订阅请求。

json
{
  "billingInformation": "{\"address\":\"922 N Pearl Street\",\"city\":\"Everardoport\",\"country\":\"US\",\"email\":\"Mozell.Bode@hotmail.com\",\"firstName\":\"Brittany\",\"identityNumber\":\"51235988984\",\"lastName\":\"Blanda\",\"phone\":\"14237418013\",\"postalCode\":\"78100\",\"province\":\"CO\"}",
  "cardInfo": "{\"holderName\":\"CL BRW2\",\"cardNumber\":\"4000000000002701\",\"month\":\"05\",\"year\":\"26\",\"cvv\":\"123\"}",
  "merchantCustId": "CustId-B2T2-16U1",
  "merchantNo": "800209",
  "merchantTxnId": "a8d5e39d-c7bb-41bf-b619-296178049b74",
  "merchantTxnTime": "2025-04-21 16:24:36",
  "orderAmount": "2",
  "orderCurrency": "USD",
  "productType": "CARD",
  "shippingInformation": "{\"address\":\"273 Chestnut Street\",\"city\":\"Germanview\",\"country\":\"US\",\"email\":\"Jared_Rice89@yahoo.com\",\"firstName\":\"Fermin\",\"identityNumber\":\"69178649516\",\"lastName\":\"Bernier\",\"phone\":\"19742024658\",\"postalCode\":\"12485-1655\",\"province\":\"CO\"}",
  "sign": "45ab55d0a94ba1a305a9a4d7a346b2b0eb89daa460cc02772cff23e864b368da",
  "subProductType": "SUBSCRIBE", 
  "subscription": "{\"requestType\":\"0\",\"selfExecute\":\"1\",\"productName\":\"Elegant Concrete Car\",\"frequencyType\":\"D\",\"bindCard\":true,\"merchantCustId\":\"CustId-230Y-D1LZ\",\"frequencyPoint\":\"24\",\"notificationEmail\":\"Dulce_Veum87@yahoo.com\",\"metaData\":\"culpa ullamco aliqua\",\"trialFromPlan\":\"1\",\"cycleCount\":28,\"trialEnd\":\"2026-02-13\"}", 
  "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"1024\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"apricot\\\",\\\"num\\\":\\\"39\\\",\\\"price\\\":\\\"128.29\\\",\\\"type\\\":\\\"laborum sint magna\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"896\",\"screenWidth\":\"414\",\"timeZoneOffset\":\"-420\",\"transactionIp\":\"30.35.165.176\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
  "txnType": "SALE"
}
json
{
  "billingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"Akşehir\"}",
  "merchantCustId": "1731380698000",
  "merchantNo": "800209",
  "merchantTxnId": "1731380698000",
  "merchantTxnTime": "2024-11-12 11:04:58",
  "merchantTxnTimeZone": "+08:00",
  "orderAmount": "20",
  "orderCurrency": "USD",
  "productType": "CARD",
  "shippingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"Akşehir\"}",
  "sign": "d2f4ecc82ccb9aded60d500b603a89342ef260f2c5d04bcc82fde6949502e8ad",
  "subProductType": "SUBSCRIBE", 
  "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"1731380698000\",\"productName\":\"Daily Auto Debit Until Nov 15 - No Trial\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2024-11-15\",\"selfExecute\":\"1\",\"notificationEmail\":\"abel.wang@onerway.com\",\"tokenId\":\"\",\"contractId\":\"\"}", 
  "txnOrderMsg": "{\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://www.merchant-store-notify.com\",\"products\":\"[{\\\"price\\\":\\\"20.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"Daily Auto Debit Until Nov 15 - No Trial\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"1727880846378401792\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
  "txnType": "SALE"
}
json
{
    "billingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"CO\"}",
    "merchantCustId": "1745215352000",
    "merchantNo": "800209",
    "merchantTxnId": "1745215352000",
    "merchantTxnTime": "2025-04-21 14:02:32",
    "merchantTxnTimeZone": "+08:00",
    "orderAmount": "20",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"country\":\"US\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"şş\",\"lastName\":\"café\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Akşehir\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\",\"province\":\"CO\"}",
    "sign": "e5e70fc1b23a67655c03e12eb9f9cc8b059f8c4e9eb9745af4bc4966e41f3c80",
    "subProductType": "SUBSCRIBE", 
    "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"1745215352000\",\"productName\":\"Self-managed-30days-Once daily\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2099-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}", 
    "txnOrderMsg": "{\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://www.merchant-store-website.com/\",\"products\":\"[{\\\"price\\\":\\\"20.00\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"Self-managed-30days-Once daily\\\",\\\"currency\\\":\\\"USD\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"1727880846378401792\",\"javaEnabled\":false,\"colorDepth\":\"24\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"timeZoneOffset\":\"-480\",\"accept\":\"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\"contentLength\":\"340\",\"language\":\"zh-CN\"}",
    "txnType": "SALE"
}

订阅响应示例 ​

发送订阅请求后，您将收到包含重定向客户完成付款所需重要信息的响应。

付款重定向

如果请求成功，商户需要从响应参数中提取 redirectUrl 并将用户重定向到该URL。

json
{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1853980684692361216",
        "merchantTxnId": "1730858419000",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "20.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null,
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=864c30107b6445459303bfae4f1514da", 
        "sign": "bd1290c1c8eb0a4cd482b82506c525999ff430c671cf7b83c8fb335a115b4347",
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxODUzOTgwNjg0NzU1Mjc1Nzc2LCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiMTczMDg1ODQxOTAwMCIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE4MzE5NDQ2OTEwMjcxNTI4OTYifQ=="
    }
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1856171302189404160",
    "merchantTxnId": "1731380698000",
    "merchantNo": "800209",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "20.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "txnTimeZone": null,
    "status": "U",
    "reason": null,
    "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=3defb10ddc42412290106d5b87705ae8&checkoutDetail=H4sIAAAAAAAAAL1WTW8cNRj%2BK9VcSTbj%2BfTsic0kESs1bZRNiwD14PF4dt147cH2ZLOKci5wBvWCFBAcWoQEB8QfQP0pDeVfYM%2FXzpYgUA89%2BvH7vvN%2BPO%2FjuXJQWU5zZ%2ByA2IshdGEQ%2BTEMXBAnnrPjLInEC8T1A%2BGMoet6bjLA0JIYx0lG2MDy7JK38XzgQzdKjJu7fX9Ga0fP9YJdAHaBdw%2BAsRuMQ%2FhPu08Ft7YfuHBch9EGXpcWmk3uHzbAZCkqruuIo84oraQkHK8N%2Bmh2YDBVZSdS5BXWnf%2Bj%2FVl6Ot23QTCSuYWnvDCFfnblUFMCCKAfeV7oeUkSRzDyYm9jaQIcT2Znh6fp5NSGL7dityATc3GC9MIgC61LNd7bKxFel2idUzQfZUxkIywkGa0oz8VKjTjRnYVnb%2Fe6z903kfbCIvRBiOMkxi6JIhwkwA%2ByCGQwQVkYotHTcj4opp3PIM3rnWFlvuuHoetDGPl%2BtFXZwXSWPnx8ePqe6oJ%2BUMDcxTDGHiSJS2IQRzmC2IsLU617d119kttVeVGcwCiIwhC%2BNa%2FH09nkPVXk5SBMiihDMMsLlPk4LyLXz8PQywtMgn%2BZVJ3g9ZMdZ0UyRbWFmMCILYTSxjqjjFE%2Bn%2BS5JEqZy9VqNdJEaZPZso3WEJhXjO04pCgI1vSCHFNeGTtn7Lv1bjyUOZHHat4ZtoGtr1wiTQV3xldOQaXqdvzVzasb2yXUIxgVf7y03Vw0Cwri2HWDxEuglQ2yRJQZFBltGK0Qn39orOQKrdtUS1MRYqnIrWsUJXFsQNQXNin16B6M7Spju9qyWeNmeBeU41p3zl%2FdkAWV1ojq9TaitCREdwXyapkR2Z1oTrg2Hg9a1AGeH4RRDOseS704QLb3jfHT8mjThw66j4bIdS0uCktadr3DwiSNsLZKCGAYgRj4rueHtj0uiDYql1ZK3ymXLUvbbr959tPrr17cfvmD777%2B8eXu7fPv3vzyzZ9fv9gF5ghuf%2F5%2B9%2FUXv95%2Be3P7%2FPe%2Fnv8WGX9JPq8MNRqWm7GTy5JK0lS2Ud7Qtoqw4vCS4Kq%2BAgYpamcjnp0cDLETQWutBRtGpmvMyITjheh7jC2UNrLcIFqck%2BZlsCJfT74djtC0oLjm3eF%2F8EZLitiRFMsThngf2YIHaK22gEOed2fTS9nSuiM8z1OzLd1Z2IXoXpEBtHlEOpDOKUdsNhj3TCNdqZ4JkuSmz1g%2FkqzzUq2FM6ufN6XQvC9eiUpikhoqcGILxwuCz0Wlm0esYUbPHwCTwA1A5Nbz1ZXk9Vd6xcoFVqNBw%2FZqUTDbwgbZGF5yZahpUq914EGvF0bKlmYz0u2N6zI6NiNjfYsLSlieCl7QebXdW1PtnKgtLWnnTFZpV93bXxzEObKRVf0I805qZP6RYDZXCzTcNk02V5%2BY0wViFWlolVNVMrSuL%2ByrMAhglv1dPC8u3sGrF9563f6v%2F5Nmn%2B5uhrlcGN3av0OpC8QUaa4%2F7t6NFjPDn3KrtMy2uYczQ4F2eFas6mM3EvsQTpcDhmZIkSiwr1q%2F24JtFv2CklX7y7cB0pp0%2B5pvgQ2vevT6%2Bm%2FzXE6DfQoAAA%3D%3D", 
    "sign": "10fc4e19ead644c8d36207388cc370e698613a58cef7933ac9def18469b40af5",
    "contractId": "",
    "tokenId": null,
    "eci": null,
    "transactionOrderNo": null,
    "periodValue": null,
    "lpmsType": null,
    "qrCode": null,
    "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxODU2MTcxMzAyMzUyOTgyMDE2LCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiMTczMTM4MDY5ODAwMCIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ=="
  }
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1914198045307043842",
    "merchantTxnId": "1745215352000",
    "merchantNo": "800209",
    "responseTime": "",
    "txnTime": "",
    "orderAmount": "20.00",
    "orderCurrency": "USD",
    "txnAmount": "",
    "txnCurrency": null,
    "txnTimeZone": null,
    "status": "U",
    "reason": null,
    "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=e3257f9fa9f34fdc8a0d683fc6e2897e&checkoutDetail=H4sIAAAAAAAAAMVW247bNhD9lUCvXXslWdbFT%2FVqN%2BgC2WQRJy3aIg8UObLZ0KRKUvYaQb4lz%2F2OIv%2FVIXWxnO5DkZcCiwV05kLOzJlDfwpI09yzYBVEWZzleZgn6SLLkzDKizi4Cvag6Y5I%2B1oFqzwM47CYYGQPGLiuQEw83z3JPl%2ByjKPlYhmHYXhpf8d9YBzGy1mYzOLoRZSswni1iP%2Ft95uSzveHMF%2F5NBbhU%2BOgzfrVXQes96qV1mecD05lqzVIekL0%2FeYWMdNWj1qxltoh%2Fv3Npnx7f%2BOSUKKZg%2B9ljYX%2B%2FingWEKU5Is0jtOsyNMkXS7zLD57YoKf7zdrjG0uspbrt%2B40obbqkdgdIjtrG7O6vtZKYl0MDqoxjJPtvBKqmlOlYX7kkqmjmUuw1%2BoAGv83oInlSs6OUM0Mq56uh5NfYerrLKohITSvIaWwoFlSJXEEWV7HVZ6yOJ83cjupqx9Vf2NsRdkbTLCSrRCfry5KXsZxUWRpnsbflPyw3ry7e9vX%2BL8Untd1GIWLlBAGFJYFxKxmUYHsreo6yrPnC7%2B49zPlf7gK8DjDrXMWihKxU8aib8WF4HK7ZkyDQe%2FgeDzOLRiL99%2F353SkcXmuAqhroJYf4IHL1rr8i9Dz8Y1moB%2FMdnDsE7tYvfcFB6tPQc21Gfbq65evX1xDyYhQUv%2F9l2v8rluKKMvCMCniIneLA3vCBaIE93F%2BJHL7I3rpIzn1V22wIiJKxVxomhZZhiAZC1s3dv4iz9z6ULdOuludbs4HLqkf8htn5tbZ1h%2B%2FfoEd166jVgPYoTTZ7ivQwxdnIC1GvO7RIIoXyTLNct9dbXe3xHW9c%2F6jeXnuwAC9IlPksx%2BgoZo3Q9eowusSap3uIBWSqMjDZLmM0mxZhEl81pSyNfZZceqp3Pd5A6Ke7YkkW2CzRcjIyczeYANeMOzwCd01%2FNkiBzrm43zhqeEaukJQhIpiFkb45zqDqe6egLadCZHaB6My9XtzO8UeFfdCFp2pV56ogLWkOzW2lDqo7DSvQ6z6CJ3sOgXtRuwOk8rymlPPr7uOH32A5kS81Gr%2FKIi8AG%2Bx2gvgTrLhG9uke65%2BAzz4MwdqS%2BYWbPhWjvqDRk%2Bgs0T3ZeGItjDNtAdLsKvkHMa3XBKxmRBgY4ltRxnD0TAcBbXv9Vir6T2CjX9ejMG5jjbVagolnizBLQ%2FdAf2oWts9Ih1XRkYtwixMFnkSewrYVkt%2Fyih0TFEznyzdtRcIJI6Y3AaZKg2SFa%2FuNeH1qB0NOe1xV8rL7Rtu5PoixsnUHAQrlaz5tr0cCVa7BXOhK%2F1awrEcqvv2xEmely6z8Y%2BgHGRHs5%2BUcHd1QEd%2FbDKafsWvAxEtdMxj3DSCnLzBPSmTBLj%2B3xN5OHxH1CjCfiP%2Fa%2FyHbuWebwYad6hkN8%2Bodk2Egc78y%2FCG9BgO%2F1461RWuzSNcIQX64Tn58p%2FDSNz7eb%2BfMLQiBtLEvX3jnihx1oIDh2P%2Fk%2BsMlJ50N1ZegB2vRtQviyda5%2BM%2F1uzA6aC0%2FwDvkAvNHQoAAA%3D%3D", 
    "sign": "4b81b903d060b0773e734acb1b960b2886c9cc9330085817c447ac6b894e9cc5",
    "contractId": "",
    "tokenId": null,
    "eci": null,
    "transactionOrderNo": null,
    "periodValue": null,
    "lpmsType": null,
    "qrCode": null,
    "subscriptionManageUrl": null
  }
}

实施最佳实践 ​

  1. 订阅配置:

    • 订阅操作始终使用 subProductType: 'SUBSCRIBE'
    • 选择 selfExecute: 1 用于托管订阅或 selfExecute: 2 用于自主管理订阅
    • 对于循环卡支付，考虑启用 bindCard: true 进行单独的卡令牌化

  2. 数据存储:

    • 安全存储成功订阅响应中的 contractId 和 tokenId
    • 对于自主管理订阅，维护您自己的计费计划系统
    • 保存 subscriptionManageUrl 以便为客户提供订阅管理访问

  3. Webhook 处理:

    • 处理所有订阅webhook通知以跟踪订阅状态变更
    • 使用 bindCard: true 时，处理绑定和订阅两种webhook
    • 实施幂等webhook处理以处理潜在的重复通知
    • 验证webhook签名以确保通知的真实性

  4. 3DS 身份验证处理:

    • 为初始订阅交易正确实施3DS重定向流程
    • 在重定向客户到3DS验证URL之前存储 transactionId
    • 在请求中配置有效的 returnUrl 以处理3DS验证后的客户返回
    • 设计返回页面以处理成功和失败的3DS验证
    • 等待webhook通知以确认最终交易状态

  5. 用户体验考虑:

    • 对于自主管理订阅:
      • 开发自定义订阅管理界面
      • 实施自定义邮件通知系统，提醒即将到来的扣费
      • 提供关于订阅条款和计费周期的清晰信息
      • 设计直观的界面供客户更新支付方式或取消订阅

  6. 试用期:

    • 使用 trialFromPlan 或 trialEnd 参数配置试用期
    • 通过webhook通知监控试用期到期
    • 对于托管订阅，从试用期到付费的过渡是自动的

  7. 订阅管理:

    • 对于托管订阅，使用 订阅计费 API 进行计划更新
    • 对于自主管理订阅，跟踪计费周期并使用订阅计费API进行续费
    • 为失败的续费尝试实施适当的错误处理和重试逻辑