> ## 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 helps you understand the full lifecycle of a HaiPay subscription. Read the summary first, then review each stage diagram, and finally move back to the [Subscription Payment API](/docs/en/api/version2/Subscription) and API Reference for implementation details.

<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 Charges" 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]
```

## Recommended Reading Order

1. Start with the [Subscription Payment API](/docs/en/api/version2/Subscription) to choose the right frontend integration mode.
2. Then read [Subscription Create](/docs/en/api-reference/subscription/api/subscriptionApply) and [Subscription Query](/docs/en/api-reference/subscription/api/subscriptionQuery) for field definitions and response structure.
3. Finish with [Subscription Cancel](/docs/en/api-reference/subscription/api/subscriptionCancel) for cancellation handling. For refunds, use the unified [Card Refund API](/docs/en/api-reference/card/api/refundApply).

## Related Topics

* [Common API](/docs/en/api/version2/CommonApi)
* [HaiPay API Description and Common Rules](/docs/en/guide/api_description_guide)
* [Payout Voucher PDF/ZIP API](/docs/en/api/version2/VoucherPdf)