What an account can hold
Fourteen assets, in two categories. The category is derived from the currency and is never chosen.Fiat
Every fiat currency opens at any tier. The tier is checked when money moves instead: below it, the account cannot send money and deposits through its details are not credited. A transfer refused this way answers
403 carrying reason: currency_not_available, currentTier, and requiredTier.
UGX has no minor unit — a UGX amount is already whole. Code that divides every balance by 100 is wrong for exactly one currency, which is the kind of bug that survives testing.
Crypto
Every crypto balance is held at 8 decimals, whatever the chain’s own convention. Withdrawal is gated higher still, at tier 3. To send USDC to a wallet address, see Wallet payouts.
Opening an account is one thing; being able to fund it is another. A non-NGN fiat account of your own is issued details only once your verification is approved and your business has international access — see what is checked, and when.
Minor units, once
Every amount in this API is an integer number of the asset’s smallest unit, carried as a string.
It is a string because the value can exceed what a JSON number represents exactly. Parse it into a big-integer or decimal type, never a float, and never do arithmetic on
balanceFormatted.
How money reaches an account
A detail is the address. Which kind you get follows from the account, not from your request.What a payer needs
A NUBAN is enough to pay an NGN account. Other corridors ask for more, so a detail groups what a payer needs by how they are sending.details.domestic is for a payer in the account’s own currency zone, and details.international is for one sending across borders. A block the corridor does not offer is null, and so is a field inside a block that the corridor does not use.
beneficiary.name is the name the payer sends to, and USD wires may also ask for beneficiary.address. details.paymentRails lists how the destination can be paid into, such as ach_push and wire for USD.
Chains
An address is issued per chain, and one issued on the wrong network is where a deposit goes to die.chain to a fiat account and it is refused with 400 chain_not_applicable; omit it on a crypto account and it is 400 chain_required. Neither mistake is allowed to reach the provider.
An account can carry more than one detail. For crypto, that is how you offer the same balance on several chains — one issuance per chain, each with its own address.
Which provider issues it
You are not told, and there is no filter for it. Which integration stands behind a balance is deliberately private: naming the processor tells an attacker where to aim. What you are told isproviderBacked — whether an integration issued this destination at all. Only an issued destination can be reconciled against inbound funds, so that flag is the one your reconciliation should read.
Routing is decided from your business’s own shape — its type, its jurisdiction, the account’s currency, and whether the account is a customer wallet. The same request from two different businesses can land on two different rails, and the response shape is identical either way. Build against the response, not against an assumed provider.
Issuance is asynchronous, sometimes
The three provider steps — your business as an entity, then the account, then the destination — each get skipped if already taken. That is what makes a retry safe.
A practical order of operations
- Start with NGN, whatever you plan to end up with. It is the only currency that moves money below tier 3 and the only one a customer wallet can hold.
- Confirm your approvals before writing non-NGN code. A non-NGN account opens without them, but issuing its details answers
403until your verification and international access are approved. That is an approvals question, not a bug. - Issue the detail immediately after opening, and gate anything user-facing on
transferReady. - Subscribe to
account.updatedrather than polling for readiness. - Pick your minor-unit type once, at the edge of your integration, and never let a float near a balance.