What is a Deposit?
A deposit is money received into Daya through an NGN virtual account or a crypto address. It is the main object you use to reconcile inbound NGN and crypto funds. For new receive-money integrations, a funding account is the payment detail your customer uses. The deposit is the money movement that is created after the customer pays into it. USD bank-account activity is tracked separately as a USD virtual account deposit. Use USD virtual account deposits for payments into USD virtual accounts.| Type | Description |
|---|---|
NGN_DEPOSIT | Naira received into an NGN virtual account |
CRYPTO_DEPOSIT | Stablecoins received into a crypto address |
Deposit Properties
Each deposit is recorded with the following core attributes:| Property | Description |
|---|---|
type | NGN_DEPOSIT or CRYPTO_DEPOSIT |
id | Unique identifier |
funding_account_id | Funding account that received the funds |
onramp_id | Legacy NGN receive-flow ID, when present |
offramp_id | Legacy crypto receive-flow ID, when present |
customer_id | Associated customer |
amount | Amount received into Daya |
currency | NGN, USDC, or USDT |
settled_amount | Amount delivered to the settlement destination |
settled_currency | Settlement destination currency, such as USD for internal balance, NGN for NGN payout, or USDC/USDT for onchain settlement |
fee_amount | Fee deducted |
fee_currency | Fee currency |
rate | Exchange rate applied |
rate_id | FX rate used (if applicable) |
status | Current deposit state |
settlement_status | Settlement progress: PENDING, PROCESSING, REQUIRES_REVIEW, COMPLETED, FAILED, REVERSED |
settlement_mode | ONCHAIN, INTERNAL_BALANCE, or NGN_PAYOUT |
asset | Stablecoin symbol (for crypto deposits) |
chain | Blockchain network (for crypto deposits) |
tx_hash | On-chain transaction hash (for crypto deposits) |
flag_code | Flag code (if flagged) |
flag_message | Flag description (if flagged) |
created_at | When deposit was received |
updated_at | Last status update |
Deposit Statuses
Deposits progress through these states:| Status | Meaning | Terminal |
|---|---|---|
RECEIVED | Deposit received, processing not yet started | No |
PROCESSING | Settlement is in progress | No |
REQUIRES_REVIEW | Deposit needs review before it can continue | No |
COMPLETED | Deposit reached its settlement destination | Yes |
FAILED | Permanent failure | Yes |
REVERSED | Bank reversed the transfer | Yes |
PENDING or FLAGGED. Treat FLAGGED as REQUIRES_REVIEW in new UI and webhook handling.
In-Progress vs Terminal States
In-progressRECEIVEDPROCESSINGREQUIRES_REVIEW
COMPLETEDFAILEDREVERSED
Deposit Lifecycle
At a high level, deposits move through the following stages:-
Received
Transfer detected (NGN bank transfer or crypto deposit) ->
RECEIVED -
Processing
Daya starts settlement, conversion, or delivery work ->
PROCESSING -
Completed
Funds are delivered to a wallet, merchant balance, or bank account ->
COMPLETED -
Reviewed (if needed)
Late, invalid, mismatched, or risky deposits are held ->
REQUIRES_REVIEWorFAILED
Common Flagging Conditions
A deposit may require review when:- It arrives after a temporary funding account or rate expiry
- A merchant or system limit is exceeded
- Risk checks require manual review
- A temporary NGN deposit does not match the expected amount
REQUIRES_REVIEW do not settle automatically and require operations review.
Funding Account Links
Deposits includefunding_account_id in API responses and webhook payloads. Use this ID to tie the incoming money back to the funding account shown to the customer.
Instruction IDs are internal and are not included in public deposit responses.
If a deposit settles through background delivery work, continue tracking the customer-facing status from the deposit. Daya sends
deposit.* events for this flow, not separate payout webhooks.USD Virtual Account Deposits
USD virtual accounts are a separate receive rail for customers who need US dollar bank details. Payments into those accounts are returned by the USD virtual account deposits API withtype: USD_DEPOSIT.
Use /v1/deposits for NGN and crypto deposits. Use /v1/virtual-account-deposits for USD virtual account deposits.
Handling Underpayments and Overpayments (Temporary VAs Only)
For temporary NGN funding accounts, merchants specify an expected deposit amount upfront. When customers send more or less than this amount, Daya handles it automatically through refunds or partial processing.See the full guide: Handling Underpayments and OverpaymentsThis covers underpayments, overpayments, Fidelity Bank exceptions, and API behavior in detail.
Bank Reversals
Banks may occasionally reverse a transfer after it is received. In such cases:- The deposit transitions to
REVERSED
Withdrawals
If a funding account settles to merchant balance, withdrawals happen in a separate lifecycle after the deposit is already complete.- Use Get Merchant Balance to inspect available funds
- Use List Withdrawals and Get Withdrawal to track status
- Use Withdraw Merchant Balance to send funds on-chain
- Subscribe to withdrawal webhook events to observe
withdrawal.created,withdrawal.submitted,withdrawal.completed, andwithdrawal.failed
Crypto Deposits
For crypto deposits, additional fields are present:type—CRYPTO_DEPOSITofframp_id— Legacy crypto receive-flow ID, when presentsettlement_mode— How settlement is handled (INTERNAL_BALANCEorNGN_PAYOUT)asset— Stablecoin symbol (USDCorUSDT)chain— Blockchain networktx_hash— On-chain transaction hash
What Deposits Do Not Represent
- They do not guarantee settlement
Next Steps
Funding Accounts
Learn how customers send funds into Daya
Rates & Settlement
Understand FX and delivery semantics
Withdrawals API
Track merchant balance withdrawals
Deposits API
View the API reference