Getting Started

Environment Setup

Before you begin, make sure you have completed the Set Up Test Environment step.

Test	https://pay-gate-uat.checus.com/aggregate-pay/api/gateway/<PATH>
Production	https://pay-gate-hk-prod.checus.com/aggregate-pay/api/gateway/<PATH>

Interaction Flow

Used to support users in making automatic payments on a fixed cycle (e.g., monthly, quarterly, yearly). The flow is divided into three phases: subscription plan configuration, first payment authorization, and subsequent periodic charges:

Phase 1: Subscription Plan Configuration (Merchant Side)

• Create a subscription plan and define amount, cycle (e.g., 30 days), trial/discount strategy, etc.
• This plan will be used for frontend display to users for selection

Phase 2: First Payment Authorization (User Side)

• Merchant calls /subscriptionCreate to create a subscription instance
• Checus returns subscriptionNo
• Merchant calls payment interface (Checkout / Drop-in / API)
• User completes first payment → Checus activates subscription → Status becomes ACTIVE

Phase 3: Subsequent Periodic Charges (System Automatic)

• Checus automatically initiates charges each cycle; users need not take action
• Merchant receives charge result callbacks:
  • Success → Subscription plan status remains ACTIVE, order charge status is SUCCESS
  • Failure → That order charge status is FAILED
• Automatic retry mechanism:
  • Retry up to 5 times (24h intervals)
  • If automatic charge succeeds, the subscription plan status remains ACTIVE; if all 5 charges fail, it updates to TERMINATE and notifies the merchant

We will use the Checkout mode as an example to show the overall subscription payment flow

Key APIs

Interaction	Direction	API / Method
Create Subscription Plan	Merchant → Checus	/subscriptionCreate
Activate Subscription Authorization	Merchant → Checus	/orderAndPay
Initiate First Authorization Payment	Merchant/Frontend → Checus	Frontend Component or Checkout
Merchant Query Subscription Status	Merchant → Checus	/subscriptionQuery
Cancel Subscription Plan	Merchant → Checus	/subscriptionCancel

Integration Steps

Create Subscription Plan

Merchants can initiate a subscription plan through the create subscription plan interface. Checus supports multiple types of subscriptions: standard subscriptions, n-day trial subscriptions, and first n-period discount subscriptions.

1. Standard Subscription

A standard subscription is a standard subscription plan that charges on a set cycle.

• Required Parameters
  • subscriptionRequestId: Unique order number for the merchant creating the subscription plan
  • userId: User identifier
  • callbackUrl: Notification address for receiving subscription results and charge results
  • subscriptionPlan: Subscription plan information, including
    • subject: Title
    • description: Description (optional)
    • totalPeriods: Total number of periods
    • periodRule: Charge rule, including
      • periodUnit: Period unit, charged by month (M), day (D), week (W), year (Y)
      • periodCount: Period interval
    • periodAmount: Charge amount per period, including amount and currency
    • firstPeriodStartDate: First period charge start time, must be less than 24 hours from request time

2. n-Day Trial Subscription

An n-day trial subscription delays n days before the first charge; the first n days are a trial period with no charge.

• Required Parameters
  • Same as standard subscription
  • firstPeriodStartDate: Set the first charge time to the end of the trial period
• Description
  • Set a delay of n days on firstPeriodStartDate to indicate the trial period length
  • No need to configure trialPeriodConfig separately; the first charge is executed by default at the end of the trial

3. First n-Period Discount Subscription

A first n-period discount subscription means that the first several periods are charged at a discount or free at the start of the subscription plan.

• Required Parameters
  • Same as standard subscription
  • firstPeriodStartDate: First period charge time
  • trialPeriodConfig: First n-period discount configuration, including
    • trialPeriodCount: Number of discount periods
    • trialPeriodAmount: Discount amount and currency; can be 0 to indicate free

Return Content Example:

• subscriptionNo: Subscription plan number assigned by Checus
• subscriptionStatus: Subscription plan status, usually INACTIVE after creation, waiting for first payment activation
• subscriptionRequestId: Order number for the merchant creating the subscription plan

After receiving a successful response, the merchant can wait for subscription activation results or periodic charge result notifications.

Activate Subscription Plan

Mode Type	Initiator	Description	Flow
Frontend Component Activation	Merchant Page + Checus Checkout	In Frontend Component mode, the merchant page loads Checus Frontend Component, which handles card information collection and payment flow. The merchant server needs to call two interfaces to complete activation: 1. Apply for Drop-in Session 2. Initiate Frontend Component payment	User clicks subscribe on merchant page → Merchant page loads Checus Frontend Component → Complete first payment to complete activation
Checkout Activation	Checus Checkout	In Checkout mode, the merchant server calls Payment Creation Interface API to create a payment order, obtain the checkout address, then the merchant page redirects to Checus Checkout for the user to complete the first payment. After successful payment, the subscription plan is activated.	User clicks subscribe on merchant page → Redirect to Checus Checkout → Complete first payment to complete activation
API Activation	Merchant Server calls Checus API	In API mode, the merchant page directly collects user card information, and the merchant server calls API Payment/orderAndPay API to initiate payment and complete activation. During payment, the user may be redirected to a 3DS verification page.	User clicks subscribe on merchant page → Merchant checkout → Complete first payment to complete activation

Important Notes

• The activation request must carry subscriptionNo, i.e., the subscription plan number returned by Checus after creating the subscription plan;
• The currency and userId during activation must match those in the subscription plan;
• The subject during activation must match that in the subscription plan;
• Rules for totalAmount:
  • [n-day trial]: Activation amount is 0;
  • [First n-period discount]: Activation amount is the discount period amount;
  • [Standard subscription]: Activation amount is the fixed charge amount per period.

Get Subscription Plan Status Results

When the subscription plan status changes, Checus will push notifications to the merchant. Statuses may include activation success, activation failure, subscription termination, etc. Merchants can obtain activation results in two ways: callback notification or active query.

Method 1. Subscription Plan Result Callback Notification

After the user completes the first payment, Checus will send a payment result notification to the merchant through the callback interface (i.e., the notifyUrl sent when creating the order or subscription plan), which includes the subscription activation status.

• Callback Address Configuration Method
  • Interface input: Sent through the notifyUrl parameter when creating an order or subscription plan, only effective for the current order
  • Platform setting: Configure a global callback address in the merchant management platform, applicable to all orders
• Notification Content
  • subscriptionNo: Unique identifier for the subscription plan
  • userId: User identifier
  • subscriptionStatus: Subscription status, including activation success (ACTIVE), activation failure (ACTIVE_FAILED), termination (TERMINATE), etc.
• Retry Strategy
  • If HTTP 200 is not returned, Checus will retry multiple times within 24 hours, with retry intervals from immediate, 30 seconds, 5 minutes, 10 minutes, 1 hour to 12 hours

Method 2. Active Query Subscription Status

If the activation result notification is not received within the set time, or the order status is unclear, the merchant can actively call the subscription status query interface to get the status.

• Interface Name: Subscription Status Query
• Request Interface: /subscriptionQuery
• Request Parameters:
  • subscriptionNo or subscriptionRequestId, one of the two must be passed
• Return Content
  • Subscription plan status
  • Charge status and amount for each period
  • Latest charge result and payment time
  • Error code and reason when charge fails

Get Subscription Plan Status Change Results

After the subscription plan is activated, merchants can obtain activation and charge results through callbacks or queries.

Get Subscription Plan Activation Results

Merchants can receive activation request results through the notifyUrl sent when creating the subscription plan or activating the subscription plan.

• Notification Content
  • status: Activation request status, success (SUCCESS) or failure (FAILED)
  • tradeToken: Payment order number
  • totalAmount: Total activation amount
  • completeTime: Completion time
  • paymentDetails: Payment method and card information

After receiving the notification, merchants should update the subscription plan status in their system based on the status.

Get First Period Charge Results

Standard subscriptions or first n-period discount subscriptions will perform a first period charge when activated. After the charge is completed, Checus will notify the merchant:

• Notification Content
  • subscriptionNo: Subscription plan number
  • subscriptionIndex: Charge period number
  • paymentStatus: Charge status, success (SUCCESS) or failure (FAILED)
  • payAmount: Charge amount and currency
  • paymentMethodType: Payment method
  • cardOrg: Card organization
  • tradeToken: Payment order number, used for refunds
  • payTime: Payment time
  • errorCode, errorMsg: Error information provided when charge fails

Merchants must return HTTP 200 to confirm receipt of the notification.

Subsequent Periodic Charges

After the subscription plan is activated, Checus will perform subsequent charges according to the advance charge days set when creating the subscription plan. If not specified, it will execute according to default rules.

• Charge result notifications are the same as first period charges, including each period's charge number, amount, status, payment method, and failure reason
• If a period's charge retry fails, Checus will terminate the subscription plan and notify the merchant

Manage Subscriptions

After the subscription plan is activated, merchants can perform management operations, such as querying charge results or canceling the subscription plan.

Subscription Status Change Notification

Merchants can receive status change notifications through the callbackUrl sent when creating the subscription plan:

• Notification content includes subscriptionNo, subscriptionStatus, and userId
• Statuses include activation, failure, termination, cancellation, etc.

Merchants can update their system and trigger subsequent business logic based on the status.

Cancel Subscription Plan

Merchants can cancel the subscription plan. If the current period is being charged, they need to wait for that period to complete before canceling.

• Interface Name: Cancel Subscription Plan
• Request Method: POST
• Request Parameters: subscriptionNo: Checus subscription plan number
• Request Interface: /subscriptionCancel
• Status After Cancellation: CANCEL

Query Subscription Charge Results

Merchants can obtain subscription plan charge results for each period through the query interface:

• Interface Name: Subscription Charge Result Query
• Request Method: POST
• Request Parameters: subscriptionNo or subscriptionRequestId, one of the two must be passed
• Request Interface: subscriptionQuery

Return Content:

• Charge status, amount, payment method, payment time for each period
• Charge failure reason and error code