Account hierarchy
Everything you create in the NAS API hangs off your client. This page shows how the pieces relate, so you know which id to send on each call.
Your client (the credentials NAS issues to you)
└── Your programme account
└── Customer account (one per customer, verified once)
├── Cardholder (the person named on the cards)
│ └── Cards (virtual or physical, up to five)
├── Budgets (shared pools of funds)
│ └── Budget cards draw on them
└── Wallets (deposit addresses and balances)
The pieces
| Level | What it is | Id you send |
|---|---|---|
| Client | The credentials NAS issues to you. A client sees only its own data. | clientId, on the token calls only |
| Account | Holds balances, wallets and verification state. | accountId, on nearly every call |
| Cardholder | The person a card is issued to. | cardholderId |
| Card | A virtual or physical card on a card BIN. | cardId |
| Budget | A shared pool of funds that budget cards draw on. | budgetId |
| Wallet | Holds a currency balance and has deposit addresses. | wallet id |
Accounts
Every call that touches money or cards names an accountId. In production you register one account for each customer, and each account is verified for one person only. See KYC. The sandbox does not register accounts, so you use the single account id NAS gave you. See Quick start.
Cardholders and cards
A cardholder is created on an account, after the account's KYC result is PASSED. A cardholder holds at most five cards, whether virtual or physical. Each card sits on a card BIN, which is a card product. It fixes the network, the currency and whether physical cards are available. See Cards.
A card is one of two types:
- A prepaid card holds its own balance. You move money onto it and back.
- A budget card has no balance of its own. It draws on a budget, so several cards can share one pool of money.
Budgets
A budget belongs to an account. You fund it with Increase budget balance and reduce it with Decrease budget balance. List cards can filter by budgetId. For a budget card, the remaining budget balance also caps what it can spend. See Cards.
Wallets
Wallets belong to the account too. Deposits arrive in a wallet, you convert between currencies inside your wallets, and you move money from there onto cards and budgets. See Wallets and funding.
What a client can see
A call that names an account, cardholder, card, budget or wallet that is not yours is refused with NB40302. See Status codes.