Prepaid Wallet System

The Prepaid Wallet system enables real-time balance checking, reservations, and consumption control.

Use Cases

• API Billing (like OpenAI) - prevent overage without payment
• Telecom - real-time call/data deduction
• IoT - device consumption control
• Gaming - in-app purchases and virtual currency

Architecture Overview

Key Concepts

Wallet Types

Type	Description	Balance Control
PREPAID	Pre-funded wallet	Strict balance enforcement
POSTPAID	Pay-after wallet	No balance restrictions

Balance Levels

Level	Purpose
lowBalanceLevel	Trigger LOW_BALANCE notification
rejectLevel	Block consumption below this level

Operation Status

Status	Description	Balance Impact
OPEN	Active, ready for invoicing	Deducted
RESERVED	Prepaid hold	Held (not deducted yet)
TREATED	Invoiced	Deducted
CANCELED	Reversed	Restored

Prepaid vs Postpaid

Aspect	Prepaid	Postpaid
Balance Required	Yes (pre-fund)	No
Reject Level	Enforced	Ignored
Reservation	Required for real-time	Optional
Real-time Check	Yes	No
Invoice Timing	Optional	End of cycle
Low Balance Alert	Yes	N/A

Core Entities

WalletTemplate

Configuration template for wallets.

WalletTemplate {
    code: String                    // "PREPAID_API_CREDITS"
    walletType: BillingWalletTypeEnum  // PREPAID or POSTPAID
    lowBalanceLevel: BigDecimal     // Trigger notification threshold
    rejectLevel: BigDecimal         // Reject consumption threshold
    lowBalanceLevelEl: String       // Dynamic EL expression
    rejectLevelEl: String           // Dynamic EL expression
}

WalletInstance

Per-user wallet linked to UserAccount.

WalletInstance {
    code: String                // "PRINCIPAL" or custom
    walletTemplate: WalletTemplate
    userAccount: UserAccount    // Owner
    lowBalanceLevel: BigDecimal // Override from template
    rejectLevel: BigDecimal     // Override from template
}

WalletOperation

Base transaction entity.

WalletOperation {
    type: OperationTypeEnum     // CREDIT or DEBIT
    status: WalletOperationStatusEnum
    amountWithoutTax: BigDecimal
    amountWithTax: BigDecimal
    wallet: WalletInstance
    chargeInstance: ChargeInstance
}

Reservation

Tracks prepaid reservation lifecycle.

Reservation {
    status: ReservationStatus   // OPEN, CONFIRMED, CANCELLED, EXPIRED
    reservationDate: Date
    expiryDate: Date
    quantity: BigDecimal
    amountWithTax: BigDecimal
    counterPeriodValues: Map    // For counter restoration
}

Key Files

Entities:

• opencell-model/.../billing/WalletInstance.java
• opencell-model/.../catalog/WalletTemplate.java
• opencell-model/.../billing/WalletOperation.java
• opencell-model/.../billing/WalletReservation.java
• opencell-model/.../billing/Reservation.java

Services:

• opencell-admin/ejbs/.../WalletService.java
• opencell-admin/ejbs/.../WalletOperationService.java
• opencell-admin/ejbs/.../WalletReservationService.java
• opencell-admin/ejbs/.../ReservationService.java

APIs:

• opencell-api/.../billing/WalletRs.java
• opencell-api/.../billing/MediationRs.java