Skip to main content

Understanding Your Wallet Structure

Learn how NextAPI wallets are structured and how they organize funds across different accounts and purposes.

Wallet Hierarchy​

NextAPI uses a hierarchical wallet structure to organize funds:

Master Wallet (Platform)
├── Operating Wallet
├── Reserve Wallet
└── Sub-Merchant Wallets
    ├── User Wallet 1
    ├── User Wallet 2
    └── User Wallet N

Wallet Types​

Master Wallet​

  • Holds all platform funds
  • Managed by platform administrators
  • Source of funds for sub-merchant wallets

Operating Wallet​

  • Day-to-day transaction funds
  • Liquid and readily available
  • Used for immediate payouts

Reserve Wallet​

  • Emergency and contingency funds
  • Regulatory compliance requirements
  • Not typically used for regular operations

Sub-Merchant Wallets​

  • Individual user or business wallets
  • Isolated from other users' funds
  • Independent balance tracking

Balance Structure​

Each wallet maintains multiple balance states:

{
  "wallet_id": "wallet_123",
  "balances": {
    "available": 100000,  // Ready for withdrawal
    "pending": 25000,     // In transit/processing
    "reserved": 15000,    // Held for disputes/chargebacks
    "total": 140000       // Sum of all balances
  },
  "currency": "PHP"
}

Fund Flow​

Credit Operations​

  1. Funds enter Master Wallet
  2. Credit to Operating or Reserve Wallet
  3. Distribute to Sub-Merchant Wallets
  4. Update available/pending balances

Debit Operations​

  1. Request payout from Sub-Merchant Wallet
  2. Check available balance
  3. Reserve funds during processing
  4. Complete debit and update balances

Security Features​

  • Fund Isolation: Each sub-merchant wallet is cryptographically isolated
  • Audit Trail: All balance changes are logged and auditable
  • Multi-signature: Critical operations require multiple approvals
  • Real-time Reconciliation: Balances are continuously reconciled

API Access​

Different wallet operations require different permissions:

// View wallet balance
GET /v1/wallets/{wallet_id}/balance

// Credit wallet (funds in)
POST /v1/wallets/{wallet_id}/credit

// Debit wallet (funds out)
POST /v1/wallets/{wallet_id}/debit

// Transfer between wallets
POST /v1/wallets/{source_id}/transfer

Best Practices​

  1. Monitor Balances: Regularly check wallet balances
  2. Set Alerts: Configure low-balance alerts
  3. Maintain Reserves: Keep adequate reserve funds
  4. Reconcile Daily: Perform daily balance reconciliation
  5. Track Pending: Monitor pending transaction amounts
  • [The Lifecycle of a Payout](./the-lifecycle-of-a-payout
  • [Security & Compliance](./security-compliance
  • [IDs, Reference IDs, and Idempotency](./ids-reference-ids-idempotency