Skip to main content

Understanding Your Wallet Structure

NextAPI uses a hierarchical wallet structure to organize and isolate funds across your platform.

Wallet Hierarchy​

Partner (You)
├── Merchant 1
│   ├── Account A (Operating)
│   └── Account B (Reserve)
├── Merchant 2
│   ├── Account C (Sub-merchant wallet)
│   └── Account D (Sub-merchant wallet)
└── Merchant N
    └── ...

Partner → Merchants → Accounts is the core hierarchy. Each level provides isolation and tracking.

Core Entities​

Merchants​

A merchant represents a business entity on your platform. If you're a SaaS platform, each of your customers is a merchant.

  • Created via POST /v2/merchants
  • Has a unique id and your own external_id
  • Groups related accounts together

Accounts​

An account is a virtual wallet that holds funds. Each merchant can have multiple accounts for different purposes.

  • Created via POST /v2/accounts
  • Linked to a specific merchant
  • Tracks balances independently

Balance Structure​

Each account maintains multiple balance states:

{
  "account_id": "acc_abc123",
  "balances": {
    "available": 100000,
    "pending": 25000,
    "reserved": 15000,
    "total": 140000
  },
  "currency": "PHP"
}
BalanceDescription
AvailableReady for withdrawal or transfer
PendingIn transit or being processed
ReservedHeld for disputes or compliance
TotalSum of all balance states

All amounts are in centavos (PHP minor units). 100000 = PHP 1,000.00.

Fund Flow​

Money In (Credits)​

  1. Payment received via QRPH, bank transfer, or virtual collection account
  2. Funds land in the designated account
  3. pending balance increases during processing
  4. On confirmation, available balance increases

Money Out (Debits)​

  1. Payout request created from an account
  2. available balance decreases, reserved increases
  3. On successful payout, reserved decreases
  4. On failure, reserved returns to available

Fund Isolation​

Each account's funds are completely isolated:

  • No cross-account contamination: Account A's balance cannot affect Account B
  • Independent tracking: Each account has its own posting history
  • Audit trail: All balance changes are logged via postings (viewable at GET /v2/accounts/{id}/postings)