Wallet Configuration

How to configure prepaid wallets for different use cases.

Wallet Template

Create Wallet Template

POST /api/rest/billing/wallet/template
Content-Type: application/json

{
  "code": "PREPAID_API_CREDITS",
  "description": "Prepaid wallet for API credits",
  "walletType": "PREPAID",
  "lowBalanceLevel": 10.00,
  "rejectLevel": 0.00
}

Fields

Field	Type	Description
code	String	Unique identifier
description	String	Human-readable description
walletType	Enum	PREPAID or POSTPAID
lowBalanceLevel	BigDecimal	Trigger LOW_BALANCE notification
rejectLevel	BigDecimal	Reject consumption below this
lowBalanceLevelEl	String	EL expression for dynamic threshold
rejectLevelEl	String	EL expression for dynamic reject

Dynamic Thresholds with EL

{
  "code": "DYNAMIC_WALLET",
  "walletType": "PREPAID",
  "lowBalanceLevelEl": "#{billingAccount.getCfValue('vip') == true ? 5.00 : 10.00}",
  "rejectLevelEl": "#{chargeInstance.getCfValue('allowOverdraft') == true ? -50.00 : 0.00}"
}

Wallet Instance

Wallets are created automatically when:

1. UserAccount is created (PRINCIPAL wallet)
2. First charge with a wallet template

Manual Wallet Creation

POST /api/rest/billing/wallet/operation
Content-Type: application/json

{
  "userAccount": "UA_001",
  "walletTemplate": "PREPAID_API_CREDITS",
  "chargeInstance": "INITIAL_CREDIT",
  "currency": "USD",
  "amountWithTax": 0.00,
  "description": "Initialize wallet"
}

Override Template Thresholds

WalletInstance wallet = walletService.getWalletInstance(userAccount, template);
wallet.setLowBalanceLevel(new BigDecimal("25.00"));  // Override
wallet.setRejectLevel(new BigDecimal("-10.00"));    // Allow overdraft

Wallet Hierarchy

Each UserAccount can have:

• One PRINCIPAL wallet (code = "PRINCIPAL")
• Multiple prepaid wallets (custom codes)

UserAccount: UA_001
├── wallet (PRINCIPAL) ─ Default postpaid wallet
└── prepaidWallets
    ├── "API_CREDITS" → Prepaid API credits
    ├── "SMS_BUNDLE" → Prepaid SMS package
    └── "DATA_PACK" → Prepaid data package

Access Specific Wallet

// Get principal wallet
WalletInstance principal = userAccount.getWallet();

// Get prepaid wallet by code
WalletInstance apiCredits = userAccount.getWalletInstance("API_CREDITS");

Charge Template Configuration

Link charges to prepaid wallets via wallet templates.

Usage Charge with Wallet

{
  "code": "API_USAGE_CHARGE",
  "chargeType": "USAGE",
  "walletTemplates": ["PREPAID_API_CREDITS"],
  "inputUnitDescription": "API calls",
  "ratingUnitDescription": "1000 calls"
}

Multiple Wallets per Charge

A charge can deduct from multiple wallets in priority order:

{
  "code": "VOICE_CHARGE",
  "walletTemplates": [
    "VOICE_BUNDLE",      // First: use included minutes
    "BONUS_MINUTES",     // Second: use bonus
    "PREPAID_BALANCE"    // Third: use prepaid balance
  ]
}

Balance Operations

Credit (Top-Up)

POST /api/rest/billing/wallet/operation
Content-Type: application/json

{
  "userAccount": "UA_001",
  "walletTemplate": "PREPAID_API_CREDITS",
  "chargeInstance": "CREDIT_CHARGE",
  "currency": "USD",
  "amountWithTax": 100.00,
  "description": "Top-up $100"
}

Debit (Manual Charge)

POST /api/rest/billing/wallet/operation
Content-Type: application/json

{
  "userAccount": "UA_001",
  "walletTemplate": "PREPAID_API_CREDITS",
  "chargeInstance": "DEBIT_CHARGE",
  "currency": "USD",
  "amountWithTax": -25.00,
  "description": "Manual deduction"
}

Provider Settings

Reservation Expiration

// Provider entity
Provider provider = providerService.getProvider();
provider.setPrepaidReservationExpirationDelayinMillisec(300000L);  // 5 minutes

Cache Configuration

# Enable prepaid balance caching (default: true)
cache.cachePrepaidBalance=true

Example Configurations

API Credits Wallet

{
  "walletTemplate": {
    "code": "API_CREDITS",
    "walletType": "PREPAID",
    "lowBalanceLevel": 10.00,
    "rejectLevel": 0.00
  },
  "chargeTemplate": {
    "code": "API_USAGE",
    "chargeType": "USAGE",
    "walletTemplates": ["API_CREDITS"],
    "inputUnitDescription": "tokens",
    "ratingUnitDescription": "1K tokens"
  },
  "pricePlan": {
    "code": "API_PRICING",
    "chargeTemplates": ["API_USAGE"],
    "price": 0.002
  }
}

Telecom Voice Bundle

{
  "walletTemplate": {
    "code": "VOICE_BUNDLE",
    "walletType": "PREPAID",
    "lowBalanceLevel": 10,
    "rejectLevel": 0
  },
  "chargeTemplate": {
    "code": "VOICE_USAGE",
    "chargeType": "USAGE",
    "walletTemplates": ["VOICE_BUNDLE", "PREPAID_BALANCE"],
    "inputUnitDescription": "seconds",
    "ratingUnitDescription": "minutes"
  },
  "counter": {
    "code": "MONTHLY_MINUTES",
    "counterType": "CONSUMPTION",
    "ceiling": 1000,
    "calendar": "MONTHLY"
  }
}

Gaming Currency

{
  "walletTemplate": {
    "code": "GAME_COINS",
    "walletType": "PREPAID",
    "lowBalanceLevel": 100,
    "rejectLevel": 0
  },
  "chargeTemplate": {
    "code": "COIN_PURCHASE",
    "chargeType": "ONE_SHOT",
    "walletTemplates": ["GAME_COINS"]
  },
  "products": [
    { "code": "1000_COINS", "quantity": 1000, "price": 9.99 },
    { "code": "5000_COINS", "quantity": 5000, "price": 39.99 },
    { "code": "10000_COINS", "quantity": 10000, "price": 69.99 }
  ]
}