Cancel Subscription

The Cancel Subscription API allows merchants to cancel an existing subscription contract. The cancellation can be immediate, scheduled for a specific date, or set to expire at the end of the current billing period.

API Request Parameters

POST

Key Parameters

• contractId - The unique identifier of the subscription contract to be cancelled
• expireMode - Determines when the subscription should be cancelled:
  • 1 - Cancel immediately
  • 2 - Cancel at the end of current period
  • 3 - Cancel on specified date (requires expireDate)

Note

• All JSON fields must be stringified before submission
• Nested objects must be serialized to JSON string format
• JSON fields must not contain unescaped special characters
• Arrays in JSON should be properly formatted
• Example of JSON string field:

{
    "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
    "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
contractId	String	/	Required	Yes	Subscription contract ID
expireDate	String	10	Conditional	Yes	Subscription expiration date. Format: yyyy-MM-dd
expireMode	String	10	Conditional	Yes	Expiration mode for subscription cancellation. See ExpireModeEnum
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.

Response

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

Name	Type	Description
data	String	Contract status. See ContractStatusEnum

Integration Process

The subscription cancellation process consists of the following steps:

In this process:

• Merchant system sends a cancellation request with the contract ID and desired cancellation mode
• Onerway processes the request and updates the subscription status
• Onerway returns the updated contract status
• For immediate cancellation:
  • Onerway sends a webhook notification immediately
  • For managed subscriptions, Onerway sends an email notification to the customer
• For scheduled cancellation:
  • No immediate webhook notification is sent
  • The webhook will be sent when the cancellation takes effect on the scheduled date

API Usage Examples

Cancel at Period End

Use this method to cancel the subscription at the end of the current billing period:

Request

{
    "contractId": "1905524192011747328",
    "expireDate": "",
    "expireMode": "2",
    "merchantNo": "800209",
    "sign": "d96808f6335547944c3567b9a7f1d8ae09c5f9971b7912a132facb1927ad75f3"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": "3" // 3: Canceled
}

Webhook Notification

{
    "notifyType": "SUBSCRIPTION_CANCELED", 
    "merchantNo": "800209",
    "responseDate": "2025-05-19 11:22:14",
    "txnDate": "2025-05-19 11:22:14",
    "txnTimeZone": "+08:00",
    "status": "S",
    "appId": "1727880846378401792",
    "contractId": "1905524192011747328", 
    "productType": "SUBSCRIBE",
    "notifyUrl": "https://docs.onerway.com/apis",
    "subscriptionExpireDate": "2025-06-22", // current billing period
    "subscriptionStatus": "canceled", // current billing period
    "dataStatus": "3", // subscription contract status
    "products": "[{\"currency\":\"USD\",\"name\":\"kiwiberry\",\"num\":\"33\",\"price\":\"692.19\",\"type\":\"Duis\"}]",
    "scenarios": "SUBSCRIPTION_CANCELED"
}

Cancel Immediately

Use this method to cancel the subscription immediately. For managed subscriptions, this will trigger both a webhook notification and an email to the customer:

Request

{
    "contractId": "1924336388879552512",
    "expireDate": "",
    "expireMode": "1",
    "merchantNo": "800209",
    "sign": "72c6f8f3f469e56aef4399c2a43356352e6f7f72c2ba01304eaa83d2b2b77527"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": "3" // 3: Canceled
}

Webhook Notification

{
    "notifyType": "SUBSCRIPTION_CANCELED", 
    "merchantNo": "800209",
    "responseTime": "2025-05-19 13:30:34",
    "txnTime": "2025-05-19 13:30:34",
    "txnTimeZone": "+08:00",
    "status": "S",
    "contractId": "1924336388879552512", 
    "sign": "dd28656198f587cb67a53e435bb820a684c984677cdd576bd3356c117322fa92",
    "subscriptionExpireDate": "2025-05-19", // immediate cancellation date
    "subscriptionStatus": "canceled", // subscription status
    "dataStatus": "3", // subscription contract status
    "products": "[{\"currency\":\"USD\",\"name\":\"pomegranate\",\"num\":\"49\",\"price\":\"918.25\",\"type\":\"ut in nostrud\"},{\"currency\":\"USD\",\"name\":\"snowpea\",\"num\":\"60\",\"price\":\"905.00\",\"type\":\"irure laboris\"}]",
    "metaData": "irure",
    "scenarios": "SUBSCRIPTION_CANCELED"
}

Cancel on Specific Date

Use this method to schedule the subscription cancellation for a specific date. Note that no webhook notification will be sent until the cancellation takes effect on the scheduled date:

Request

{
    "contractId": "1924338679510601728",
    "expireDate": "2025-05-20",
    "expireMode": "3",
    "merchantNo": "800209",
    "sign": "ce661df1678dc37680356968fe14c5ad7bd57542a97c5635b723291ec35ed953"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": "3" // 3: Canceled
}

Important Notes

1. If neither expireDate nor expireMode is provided, the subscription will be cancelled at the end of the current period
2. When using expireMode=3, you must provide a valid expireDate in the format yyyy-MM-dd
3. For immediate cancellation:
   • A webhook notification will be sent immediately
   • For managed subscriptions, customers will receive an email notification
4. For scheduled cancellation:
   • No immediate webhook notification will be sent
   • The webhook notification will be sent when the cancellation takes effect on the scheduled date

Common Error Scenarios and Solutions

1. Missing Required Parameters
   • When using expireMode=3, make sure to include the expireDate
   • Always include the required contractId and merchantNo

Implementation Best Practices

1. Cancellation Timing

   • Choose the appropriate cancellation mode based on your business needs:
     • Use immediate cancellation for urgent situations (triggers immediate webhook and customer email for managed subscriptions)
     • Use end-of-period cancellation for standard subscription management
     • Use scheduled cancellation for planned terminations (webhook sent on cancellation date)

2. Webhook Handling

   • Implement robust webhook handling to process cancellation notifications
   • Store the webhook data for audit and reconciliation purposes
   • Implement proper error handling and retry logic for webhook processing

3. User Communication

   • Notify users when their subscription cancellation is processed
   • Clearly communicate the final billing date and service end date
   • Provide options to reactivate the subscription if needed

4. Data Management

   • Keep records of cancelled subscriptions for reporting and analysis
   • Track cancellation reasons for business intelligence
   • Maintain audit logs of all cancellation-related actions

Merchant Integration Checklist

Before implementing the Cancel Subscription API in your production environment, ensure you have:

• Proper handling of different cancellation modes
• Webhook endpoint for receiving cancellation notifications
• User notification system for cancellation status updates
• Error handling and retry mechanisms
• Logging and auditing system
• Testing completed in sandbox environment