Core Objects

NadaPay's API is built around five core resources. Every operation you perform maps to one of these objects. Understanding how they relate to each other is the fastest way to reason about any API call.

The five core objects

Organization

The top-level entity. Represents a real-world business that has been onboarded onto NadaPay. All other resources — accounts, wallets, beneficiaries, and transactions — belong to an organization.

An organization must pass KYC/KYB verification before it can perform financial operations in production.

Account

A sub-structure within an organization used to segment financial operations. One organization can have multiple accounts — for example, separating vendor payouts from treasury reserves.

Accounts are containers. They do not hold balances directly — their wallets do.

Wallet

Where balances live. Each wallet is tied to a single currency and belongs to an account. An account can have multiple wallets across different currencies.

Wallets must be funded before transactions can be initiated from them.

Beneficiary

A named, reusable payout destination. A beneficiary represents a person or business your organization pays regularly. Each beneficiary can have one or more beneficiary accounts — the actual payout instruments (bank account, mobile money wallet, etc.) funds are sent to.

Beneficiary accounts must be validated before a transaction can be executed to them.

Transaction

The execution of a money movement from a wallet to a beneficiary account. Transactions are always preceded by a quote, which locks in the exchange rate and fee before funds move.

Transactions are asynchronous — status updates are delivered via webhook.

How the objects compose

Organization
  └── Account(s)
        └── Wallet(s)          [currency-specific balances]

Organization
  └── Beneficiary(s)
        └── Beneficiary Account(s)   [validated payout destinations]

Wallet ──────────────────────────────────────────► Beneficiary Account
         Quote → Transaction

Every transaction flows from a wallet (source) to a beneficiary account (destination), using a quote to price the transfer.

Object ID format

All NadaPay resource IDs follow a consistent format:

Object	ID prefix	Example
Organization	`org_`	`org_01HXXXXXXXXXXXXXXXXXX`
Account	`acct_`	`acct_01HXXXXXXXXXXXXXXXXXX`
Wallet	`wlt_`	`wlt_01HXXXXXXXXXXXXXXXXXX`
Beneficiary	`ben_`	`ben_01HXXXXXXXXXXXXXXXXXX`
Beneficiary Account	`bac_`	`bac_01HXXXXXXXXXXXXXXXXXX`
Transaction	`txn_`	`txn_01HXXXXXXXXXXXXXXXXXX`
Quote	`qte_`	`qte_01HXXXXXXXXXXXXXXXXXX`

📘
ID format
NadaPay IDs are time-sortable and prefixed by resource type. Always copy and paste IDs — do not construct or guess them. IDs are case-sensitive.

Quick reference

I want to…	Object to use
Check available funds	Wallet (`available_balance`)
Add a new payout destination	Beneficiary → Beneficiary Account
Price a transfer	Quote
Move money	Transaction
Check compliance status	Organization (`verification_status`)

What's next

Next step	Link
See how objects relate structurally	API Structure
Understand request and response format	Request and Response Format
Learn about idempotency	Idempotency