Skip to main content

​
Overview

Deposits flow through different statuses from initial creation to final settlement. Each status indicates where the deposit is in its lifecycle and whether merchant action is required.

​
Status Values

StatusDescriptionTerminal?Action Required?
PENDING_FXNGN received, awaiting FX❌ No❌ No
PENDING_WITHDRAWALFX done, awaiting on-chain tx❌ No❌ No
SETTLEDFully complete✅ Yes❌ No
FAILEDPermanent failure✅ Yes✅ Yes (notify user)
FLAGGEDHeld for manual review✅ Yes✅ Yes (contact support)
REVERSEDBank reversed transfer✅ Yes❌ No

​
Complete Lifecycle

​
Status Descriptions

​
PENDING_FX

NGN received, FX conversion pending
  • Bank transfer detected in virtual account
  • Validation in progress (limits, expiry, risk)
  • Next: Execute FX conversion
Duration: Typically < 1 minute Webhook: deposit.created

​
PENDING_WITHDRAWAL

FX complete, on-chain withdrawal pending
  • FX successfully executed
  • Waiting for on-chain transaction confirmation
  • Only applies to AUTO_WITHDRAW mode
Duration: 1-5 minutes (depends on blockchain) Why delays occur:
  • Network congestion
  • Gas price fluctuations
  • Chain confirmation requirements

​
SETTLED

Deposit fully complete ✅ For AUTO_WITHDRAW:
  • On-chain transaction confirmed
  • Funds in destination wallet
For MERCHANT_BALANCE:
  • USD credited to merchant’s internal balance
  • Available for withdrawal
Webhook: deposit.settled

​
FAILED

Permanent failure ❌ Deposit cannot be completed automatically. Requires merchant intervention. Common causes:
CauseDescriptionFix
Below minimumDeposit < min_deposit_ngnUser must transfer sufficient amount
FX failureNo liquidity or conversion errorContact support
Invalid addressDestination address invalidCorrect address in new onramp
On-chain errorGas failure or network issueMay be retried by operations
Webhook: deposit.failed

​
FLAGGED

Held for manual review ⚠️ Deposit is frozen pending operations review. Not automatically processed. Common reasons:
ReasonDescriptionResolution Time
Late depositDeposit after onramp/rate expiry1-2 business days
Limit exceededPer-onramp, merchant, or system limit1-2 business days or next day
Risk triggerUnusual pattern or address flagged2-5 business days
ComplianceKYC/AML concernVariable
Webhook: deposit.flagged
Flagged deposits are not counted as Daya-owned funds until resolved. They do not affect your available balance.

​
REVERSED

Bank reversed the original transfer Rare but possible: The sending bank clawed back the NGN transfer. Impact:
  • If payout already occurred, Daya absorbs the loss (v0.1)
  • Merchant not charged back in v0.1
  • May affect future risk scoring
Webhook: deposit.reversed (future)

​
Terminal vs Non-Terminal States

​
Non-Terminal (In Progress)

Deposit is still being processed:
  • PENDING_FX
  • PENDING_WITHDRAWAL
Merchant action: Monitor via webhooks or polling

​
Terminal (Final)

Deposit has reached end state:
  • SETTLED (success)
  • FAILED (error)
  • FLAGGED (review)
  • REVERSED (clawback)
Merchant action: Handle accordingly (notify user, show tx_hash, etc.)

​
Handling Each Status

User message: “Processing your deposit…”Action: Show loading indicator, monitor for updates

​
Common Transitions

PENDING_FX (1 min)
→ PENDING_WITHDRAWAL (3 min)
→ SETTLED
Total: ~4 minutes
PENDING_FX (1 min)
→ SETTLED
Total: ~1 minute (no on-chain wait)
NGN arrives after expiry
→ FLAGGED immediately
No FX executed automatically
PENDING_FX
→ Limit check fails
→ FLAGGED

PENDING_FX
→ FX execution error
→ FAILED

​
Best Practices

1

Use webhooks for status changes

Don’t poll. Set up webhooks for real-time updates.
2

Handle all terminal states

Your UI must gracefully handle SETTLED, FAILED, FLAGGED, and REVERSED.
3

Show clear error messages

For FAILED and FLAGGED, explain what happened and what the user should do.
4

Display tx_hash for settled deposits

Link to block explorer so users can verify on-chain.
5

Implement timeout alerts

If deposit stays in PENDING_WITHDRAWAL > 10 minutes, alert your operations team.

​
Next Steps

Onramp Statuses

Learn about onramp lifecycle states

Webhooks

Set up real-time status notifications