Architecture

NextAPI is a multi-layer system: your platform sits at the top, bank and e-wallet providers sit at the bottom, and NextAPI handles everything in between — routing, ledger, webhook dispatch, and compliance.

System overview

┌──────────────────────────────────────────────────────────┐
│                     Your Platform                        │
│         (REST API calls via Basic Auth)                  │
└──────────────────────────┬───────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────┐
│                    NextAPI Gateway                       │
│  Auth · Rate limiting · Request validation · Idempotency │
└──────────────────────────┬───────────────────────────────┘
                           │
         ┌─────────────────┼────────────────────┐
         │                 │                    │
┌────────▼──────┐ ┌────────▼──────┐  ┌──────────▼──────┐
│  Merchant &   │ │  Payment      │  │  Payout &       │
│  Account Mgmt │ │  Engine       │  │  Disbursement   │
│               │ │  (Money In)   │  │  Engine         │
│  Wallet       │ │               │  │  (Money Out)    │
│  hierarchy    │ │  Funding      │  │                 │
│  management   │ │  Methods +    │  │  Payout         │
│               │ │  Payment      │  │  Requests +     │
│               │ │  Intents      │  │  Rail routing   │
└───────────────┘ └───────────────┘  └─────────┬───────┘
                           │                   │
┌──────────────────────────▼───────────────────▼──────────┐
│                      Ledger                             │
│     Double-entry postings · Account balances ·          │
│     Transaction records · Reconciliation data           │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────┐
│                  Webhook Dispatcher                      │
│  Event routing · Retry logic · HMAC-SHA256 signatures    │
└──────────────────────────┬───────────────────────────────┘
                           │
         ┌─────────────────┼────────────────────┐
         │                 │                     │
┌────────▼──────┐ ┌────────▼──────┐  ┌──────────▼──────┐
│  Provider 1   │ │  Provider 2   │  │  Provider 3     │
│   (Bank)      │ │  (E-wallet)   │  │  (Bank)         │
└───────┬───────┘ └───────┬───────┘  └──────────┬──────┘
        │                 │                     │
        └─────────────────┴─────────────────────┘
                          │
              BancNet · InstaPay · PESONet · QRPH
               (provider network continues to grow)

The wallet hierarchy

Every entity in NextAPI maps to a level in a three-tier hierarchy:

Partner (you)
├── Merchant A           ← your customer's business
│   ├── Account A1       ← e.g., "Collections"
│   └── Account A2       ← e.g., "Payroll"
└── Merchant B
    └── Account B1

Partners are BSP-licensed through NextPay. You never need your own license.

Merchants represent the businesses or entities on your platform. A cloud POS creates one merchant per restaurant. A payroll platform creates one merchant per client company.

Accounts hold funds. A merchant can have multiple accounts for different purposes — one for collecting payments, another for disbursements. Each account can have its own QRPH code and bank account number (via Funding Methods).

Balances are tracked per account:

• Available — funds ready to use
• Pending — funds in transit (not yet settled)
• Reserved — funds held for in-flight transactions

Multi-provider routing

NextAPI routes transactions across a growing network of financial providers — currently 3 partner institutions (banks and e-wallets), with more being added over time. Having multiple providers means no single point of failure: if one is degraded, traffic shifts automatically. The routing layer considers:

Factor	How it influences routing
Transaction amount	InstaPay: ≤ PHP 50,000. Larger amounts route to PESONet.
Provider cost	NextAPI routes to the lowest-cost available provider. Your net cost is set by your partner agreement, not the underlying provider rates.
Strategic factors	Routing balances cost, reliability, and strategic considerations — it is not purely cost-optimized.
Provider reliability	Live success rate monitoring. If a provider has elevated failures, traffic shifts away automatically.
Partner-specific rules	For certain integrations, routing can be configured based on existing financial relationships between the partner and a specific provider.

Your integration doesn't need to know any of this. Specify the destination account and amount; NextAPI picks the rail.

→ See Multi-Provider Routing for the full decision tree. → See Disbursement Channels for InstaPay vs PESONet differences.

The ledger

Every peso movement creates a posting — a ledger entry with:

• Account ID (debit or credit)
• Amount in centavos
• Timestamp
• Associated transaction ID
• Direction (debit/credit)

Postings are grouped into transactions (atomic operations). A simple payout creates two postings: a debit from the source account and a credit to a clearing account. When the bank confirms settlement, a second transaction posts the final debit from clearing.

This double-entry structure means your balances always reconcile. Query GET /v2/accounts/{id}/postings to get a complete audit trail — no manual bank statement matching required.

Money In flow (QRPH collection)

1. Your platform calls POST /v2/payment-intents (or creates a Funding Method)
2. NextAPI creates a QRPH payload via the selected provider
3. NextAPI returns the QRPH code/URL to your platform
4. Your platform displays the QR to the end user
5. End user scans and pays via GCash, Maya, or any bank app
6. Bank routes payment through BancNet → provider
7. Provider notifies NextAPI
8. NextAPI posts the credit to the merchant account ledger
9. NextAPI dispatches a webhook to your endpoint

Funding Methods (static) are created once per account and remain active until archived. Use for recurring collection points — a merchant's permanent QR code on their counter.

Payment Intents (dynamic) are single-use. Create one per transaction for exact-amount collection — an invoice, an order checkout, a subscription renewal.

Money Out flow (payout)

1. Your platform calls POST /v2/payout-requests
2. NextAPI validates the request, checks source account balance
3. NextAPI creates a Payout Request with status: initiated
4. Routing engine selects the provider and rail (InstaPay or PESONet)
5. NextAPI submits to the provider
6. For InstaPay: typically completes in <30 seconds
   For PESONet: completes at next batch cutoff (2x daily)
7. Provider confirms settlement
8. NextAPI updates status to: completed
9. NextAPI dispatches webhook: payout_request.completed

A single Payout Request may split into multiple Payouts if the amount exceeds InstaPay's PHP 50,000 limit. The Payout Request tracks the overall intent; individual Payouts track each rail transaction.

Webhook delivery

NextAPI attempts webhook delivery up to 5 times with exponential backoff. Each attempt signs the request body with HMAC-SHA256 using your webhook secret. Always verify the x-nextpay-signature header before processing.

→ See Webhooks for signature verification and event types.

Compliance boundary

NextAPI operates under NextPay's BSP OPS (Operations) license. This license covers:

• All money movement through the system
• KYC for merchants onboarded through NextAPI
• AML transaction monitoring
• Reporting obligations to BSP

As a partner, you inherit this compliance coverage. You do not need your own OPS license to process payments through NextAPI.

→ See Security and Compliance.