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.

Terminology quick reference

---

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 can be asynchronous. Your integration should retrieve and track transaction status through the available API workflow and your own operational monitoring.

---

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.

---

Quick reference

---

What's next