Subscription Query

The Subscription Query API allows merchants to retrieve detailed information about a customer's subscription contract, including billing amounts, frequency, status, and related payment token information.

API Request Parameters

POST

Key Parameters

• contractId - Subscription contract ID that uniquely identifies the subscription
• merchantNo - Merchant number assigned by Onerway

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
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
contractId	String	/	No	Yes	Subscription contract ID, required for subscription-related queries
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
contractId	String	Subscription contract ID
merchantNo	String	Merchant number assigned by Onerway
merchantCustomerId	String	Unique customer identifier in merchant system
products	String	Product information in JSON format
orderAmount	String	Total amount per billing cycle
orderCurrency	String	Currency for the order amount
expireDate	String	Subscription expiration date
frequencyType	String	Frequency type. See FrequencyTypeEnum
frequencyPoint	String	Frequency value (interval between billing cycles)
cycleCount	String	Number of subscription cycles (null for unlimited)
notificationEmail	String	Email address for subscription notifications
billingCycleAnchor	String	Next billing cycle time
dataStatus	String	Contract data status. See DataStatusEnum
subscriptionStatus	String	Subscription status. See SubscriptionStatusEnum
createTime	String	Time when the subscription was initially created
tokenId	String	Subscription token ID

Integration Process

The Subscription Query integration process consists of a simple request-response flow:

In this process:

• Merchant system sends a query request with the subscription contract ID
• Onerway processes the request and retrieves the subscription details
• Onerway returns the subscription information to the merchant
• Merchant processes the subscription data for display or management purposes

API Usage Examples

Query Subscription Contract

Use this method to retrieve detailed information about a specific subscription contract:

Request

{
    "contractId": "1905524192011747328",
    "merchantNo": "800209",
    "sign": "b8401d4730cb987c5c374ae366ce1cc324ea860f93bb33c924bebbdf764c4fc7"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "contractId": "1905524192011747328",
        "merchantNo": "800209",
        "merchantCustomerId": "CustId-16R2-4A86",
        "products": "[{\"currency\":\"USD\",\"name\":\"kiwiberry\",\"num\":\"33\",\"price\":\"692.19\",\"type\":\"Duis\"}]",
        "orderAmount": "6.00",
        "orderCurrency": "USD",
        "expireDate": "2025-06-22",
        "frequencyType": "D",
        "frequencyPoint": 103,
        "cycleCount": null,
        "notificationEmail": null,
        "billingCycleAnchor": null,
        "dataStatus": "1",
        "subscriptionStatus": "active",
        "metaData": null,
        "createTime": "2025-03-28 15:35:45",
        "tokenId": "f1ec0211977afb3cf220ddc04411f46a8b5f8cdd34678efd2049523e3599740b"
    }
}

Important

• The contractId must be obtained from a successful subscription creation operation

Common Error Scenarios and Solutions

Common Error Codes

Implementation Best Practices

1. Data Validation: Always validate the subscription data returned, especially the subscription status, expiration date, and billing cycle information

2. Subscription Management: Use this API to retrieve current subscription details before performing operations like cancellation, pausing, or updating subscription details

3. Customer Support: Implement this API in customer support interfaces to quickly access subscription details when handling customer inquiries

4. Secure Access: Ensure that subscription data is only accessible to authenticated and authorized users in your system

5. Regular Synchronization: Implement a process to periodically synchronize subscription status and details between your system and Onerway

6. Display Formatting: When displaying subscription information to customers, format the product information and billing details in a user-friendly manner

Merchant Integration Checklist

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

• Secure storage for subscription contract IDs
• Proper error handling for query operations
• User interface to display subscription details (if applicable)
• Integration with subscription management operations
• Thorough testing in sandbox environment