The Stellar Subscription Engine is a recurring billing infrastructure built on the Stellar blockchain using Soroban smart contracts. It enables SaaS businesses to accept USDC-based subscription payments with automated billing cycles, usage-based billing support, and merchant APIs.

This system acts as a Web3-native billing layer comparable to Stripe's subscription infrastructure, optimized for low-fee, high-speed settlement on Stellar.

Web3 currently lacks a standardized and reliable recurring billing mechanism.

Key limitations:

• No native recurring payment primitive
• No secure wallet auto-debit model
• Manual reconciliation for SaaS platforms
• Limited support for usage-based billing
• No infrastructure-grade billing API for Stellar ecosystem

The system introduces a prepaid subscription vault model:

• Users deposit USDC into a smart contract vault
• The contract releases funds on a defined billing interval
• Backend billing engine triggers on-chain execution
• Off-chain services handle indexing, analytics, and notifications

This approach avoids forced wallet deductions while maintaining automation.

flowchart TD
    A[Customer Wallet] -->|Deposit USDC| B[Soroban Smart Contract]
    C[Merchant Dashboard] --> D[API Gateway]
    D --> E[Subscription Service]
    D --> F[Billing Engine]
    D --> G[Usage Metering Service]
    F -->|Trigger Charge| B
    B --> H[Stellar Network]
    H --> I[Horizon Listener]
    I --> E
    E --> J[(PostgreSQL Database)]
    E --> K[Webhook Service]
    K --> L[Merchant Backend]

Responsibilities:

• Store subscription agreements
• Maintain subscriber vault balances
• Enforce billing intervals
• Execute payments
• Handle cancellations and grace periods

struct Subscription {
    subscriber: Address,
    merchant: Address,
    amount: i128,
    interval_seconds: u64,
    last_payment_timestamp: u64,
    status: SubscriptionStatus,
    prepaid_balance: i128,
    usage_enabled: bool,
}

• create_subscription()
• deposit_funds()
• charge_subscription()
• cancel_subscription()
• pause_subscription()
• withdraw_merchant_funds()

• merchants
• plans
• subscriptions
• customers
• transactions
• usage_records

sequenceDiagram
    participant User
    participant Frontend
    participant SmartContract
    participant Backend

    User->>Frontend: Select plan
    Frontend->>SmartContract: Deposit USDC
    SmartContract-->>Backend: Emit event
    Backend->>Database: Store subscription

sequenceDiagram
    participant BillingEngine
    participant SmartContract
    participant Stellar
    participant HorizonListener
    participant Backend

    BillingEngine->>SmartContract: charge_subscription()
    SmartContract->>Stellar: Transfer USDC
    Stellar-->>HorizonListener: Payment event
    HorizonListener->>Backend: Confirm transaction
    Backend->>Database: Update status

sequenceDiagram
    participant User
    participant SmartContract
    participant Backend

    User->>SmartContract: cancel_subscription()
    SmartContract-->>Backend: Emit cancellation event
    Backend->>Database: Update status

erDiagram
    MERCHANTS ||--o{ PLANS : creates
    PLANS ||--o{ SUBSCRIPTIONS : assigned_to
    CUSTOMERS ||--o{ SUBSCRIPTIONS : owns
    SUBSCRIPTIONS ||--o{ TRANSACTIONS : generates
    SUBSCRIPTIONS ||--o{ USAGE_RECORDS : tracks

Stellar does not allow forced wallet debits.

Solution: Prepaid vault model

• User deposits USDC in advance
• Contract releases funds per billing interval
• Insufficient balance → subscription suspension

Optional enhancements:

• Balance threshold alerts
• Auto-reminder notifications

• Strict signature validation
• Replay protection
• Contract upgrade mechanism
• Merchant authentication
• Rate limiting
• Input validation
• Grace period enforcement
• Transaction idempotency

This system is not a consumer application. It is a billing infrastructure layer for the Stellar ecosystem.

Target users:

• Web3 SaaS platforms
• AI API providers
• Developer tools
• Indie software businesses

The Stellar Subscription Engine introduces a structured, programmable, and scalable recurring billing model for USDC on Stellar.

It leverages:

• Low transaction fees
• Fast settlement
• Soroban smart contracts
• API-driven backend architecture

This infrastructure can become a foundational billing layer for Web3-native SaaS applications within the Stellar ecosystem.