> ## Documentation Index
> Fetch the complete documentation index at: https://doc.haipay.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Payment Flowchart

> Understand the full HaiPay subscription lifecycle with clearer stage-based guidance for subscription creation, recurring deductions, cancellation, and retry logic.

This page outlines the full HaiPay subscription flow from creation to termination. Start with the summary below, then review each stage diagram. For implementation details, refer to the [Subscription Payment API](/docs/en/V20260628/api/version2/Subscription) and API Reference.

<Columns cols={3}>
  <Card title="Create Subscription" icon="circle-plus" href="#create-subscription">
    The user authorizes the subscription, completes the first payment, and a platform subscription number is created.
  </Card>

  <Card title="Recurring Billing" icon="arrows-rotate" href="#recurring-charge">
    HaiPay charges automatically on schedule and sends the result to the merchant asynchronously.
  </Card>

  <Card title="Cancel and End" icon="ban" href="#cancel-subscription">
    The subscription ends when the user cancels, the max cycle count is reached, or failure rules terminate it.
  </Card>
</Columns>

## Flow Summary

<Steps>
  <Step title="User starts a subscription">
    The merchant calls the subscription-create API, HaiPay returns an authorization URL or frontend payment capability, and the user completes authorization plus the first charge.
  </Step>

  <Step title="Subscription becomes active">
    After the first successful payment, the platform generates a `subscriptionNo`. All future recurring charges are tied to that subscription number.
  </Step>

  <Step title="HaiPay charges on schedule">
    When the billing cycle arrives, HaiPay automatically initiates the recurring deduction and sends the result to the merchant through asynchronous notifications.
  </Step>

  <Step title="The subscription stops when an end condition is met">
    The subscription ends when the user cancels, the maximum cycle count is reached, or repeated failures hit the termination condition.
  </Step>
</Steps>

## Key Status Interpretation

| Stage                 | What you should pay attention to                                                                |
| :-------------------- | :---------------------------------------------------------------------------------------------- |
| Subscription creation | Whether authorization can be launched and whether the user completes the first payment          |
| Active subscription   | Whether `subscriptionNo` is stored correctly in your system                                     |
| Recurring charges     | Whether every asynchronous deduction callback is received and processed correctly               |
| Cancellation          | Whether the user has a clear cancellation entry and the cancellation result is synced locally   |
| Retry and failure     | Whether your business has clear handling for failed charges, risk control, and service fallback |

<Tip title="Implementation guidance">
  * Save the relationship between `subscriptionNo`, merchant subscription ID, and user identity immediately after the first successful payment.
  * Do not rely only on the frontend result page. Subscription and recurring-charge status should be confirmed by server-side notifications and query APIs.
  * Always show the billing cycle, amount, cancellation method, and service agreement to the user.
</Tip>

<a id="create-subscription" />

## Create Subscription

**Goal**: complete user authorization, charge the first payment, and establish the subscription relationship.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Merchant
    participant HaiPay

    User->>Merchant: 1. Choose a subscription service
    Merchant->>HaiPay: 2. Call apply API to create the subscription
    HaiPay-->>Merchant: 3. Return authorization URL / frontend payment capability
    Merchant-->>User: 4. Guide the user to the authorization page
    User->>HaiPay: 5. Complete payment authentication and authorization
    HaiPay->>HaiPay: 6. Verify authorization status
    HaiPay->>HaiPay: 7. Initiate the first subscription charge
    HaiPay-->>Merchant: 8. Notify the subscription result
    Merchant-->>User: 9. Show the activation result
```

**Implementation focus for this stage**

* Store the mapping between merchant subscription ID and platform subscription number
* Do not trust the frontend result page alone; confirm the result through callbacks or query APIs
* Make sure the user can clearly understand the amount, cycle, and cancellation method

<a id="recurring-charge" />

## Recurring Charges

**Goal**: renew the subscription automatically while it remains active.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Merchant
    participant HaiPay

    HaiPay->>HaiPay: 1. Automatically initiate the recurring charge at cycle time
    HaiPay-->>Merchant: 2. Send the deduction result asynchronously
    Merchant-->>User: 3. Update subscription entitlement or send a renewal notice
```

**Implementation focus for this stage**

* Your server must handle the callback and return uppercase `SUCCESS`
* It is strongly recommended to notify users outside the platform before and after each charge
* If a charge fails, define a clear retry, downgrade, or service-suspension policy

<Warning title="Do not ignore callback processing">
  If you rely only on whether the user opens a result page, you will miss the real recurring-charge outcome. Subscription renewals should always be confirmed by server-side callbacks and query APIs.
</Warning>

<a id="cancel-subscription" />

## Cancel Subscription

**Goal**: stop future recurring charges when the user cancels or the business ends the subscription.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Merchant
    participant HaiPay

    User->>Merchant: 1. Request subscription cancellation
    Merchant->>HaiPay: 2. Call the cancel API
    HaiPay-->>Merchant: 3. Return the cancellation result
    Merchant-->>User: 4. Display the cancellation status
```

**Implementation focus for this stage**

* The user-facing product must include a clear and accessible cancellation entry
* Update your local subscription state immediately after cancellation succeeds
* If charges are still pending around cancellation time, define the entitlement boundary clearly in your business logic

## Full Lifecycle Diagram

```mermaid theme={null}
graph TD
  A[Create Subscription] --> B[First Payment]
  B --> C[Payment Success]
  B --> D[Payment Failure]
  D --> E[Subscription Failed]
  E --> A
  C --> F[Subscription Active]
  F --> G[Billing cycle arrives, check max cycles]
  G --> N[Max cycles exceeded]
  N --> M[Cancel Subscription]
  G --> L[Within cycle limit]
  L --> O[Start automatic charge]
  O --> H[Charge Success]
  H --> G
  O --> I[Charge Failure]
  I --> G
  I --> K[Enter retry or termination decision]
  K --> M[Cancel Subscription]
```

## Related Topics

* [Subscription Payment API](/docs/en/V20260628/api/version2/Subscription)
* [Subscription Create](/docs/en/api-reference/subscription/api/subscriptionApply)
* [Subscription Query](/docs/en/api-reference/subscription/api/subscriptionQuery)
* [Subscription Cancel](/docs/en/api-reference/subscription/api/subscriptionCancel)