Deposits

​

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.

---

​

Deposit Properties

Each deposit is recorded with the following core attributes:

---

​

Deposit Statuses

Deposits progress through these states: Older integrations may still send or filter by PENDING or FLAGGED. Treat FLAGGED as REQUIRES_REVIEW in new UI and webhook handling.

​

In-Progress vs Terminal States

In-progress

• RECEIVED
• PROCESSING
• REQUIRES_REVIEW

Terminal

• COMPLETED
• FAILED
• REVERSED

Once a deposit reaches a terminal state, it does not transition further.

---

​

Deposit Lifecycle

At a high level, deposits move through the following stages:

1. Received Transfer detected (NGN bank transfer or crypto deposit) -> RECEIVED
2. Processing Daya starts settlement, conversion, or delivery work -> PROCESSING
3. Completed Funds are delivered to a wallet, merchant balance, or bank account -> COMPLETED
4. Reviewed (if needed) Late, invalid, mismatched, or risky deposits are held -> REQUIRES_REVIEW or FAILED

---

​

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

Deposits in REQUIRES_REVIEW do not settle automatically and require operations review.

​

Funding Account Links

Deposits include funding_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 the funding account has a developer fee, completed deposit responses and webhooks include:

• developer_fee.percentage - the configured percentage
• developer_fee.amount and developer_fee.currency - the amount your merchant account kept
• customer_amount.amount and customer_amount.currency - the amount left for the customer after Daya fees and the developer fee

Developer fees are deducted before the customer amount is finalized. For onramps and offramps, this means the fee is not added as a separate charge. Use the developer_fee object for the exact fee amount and currency.

​

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 with type: 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.

---

​

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, and withdrawal.failed

---

​

Crypto Deposits

For crypto deposits, additional fields are present:

• type — CRYPTO_DEPOSIT
• offramp_id — Legacy crypto receive-flow ID, when present
• settlement_mode — How settlement is handled (INTERNAL_BALANCE or NGN_PAYOUT)
• asset — Stablecoin symbol (USDC or USDT)
• chain — Blockchain network
• tx_hash — On-chain transaction hash

---

​

What Deposits Do Not Represent

• They do not guarantee settlement

---

​

Next Steps