Deposits

What is a Deposit?

A deposit represents a single NGN bank transfer into an onramp’s virtual account. It is the upstream event that triggers FX conversion and settlement.

A deposit is not the on-chain transaction—it’s the NGN inflow. The on-chain withdrawal (if applicable) happens after FX conversion.

Deposit Properties

Property	Description	Example
`deposit_id`	Unique identifier	`dep_9x2k5m8p`
`onramp_id`	Parent onramp	`onramp_3j5k8n2q`
`merchant_id`	Owner (inferred)	`merch_abc123`
`user_email`	End-user email	`[email protected]`
`payment_reference`	Daya-generated reference	`DAYA-3J5K8N2Q`
`amount_ngn`	NGN amount received	`15000.00`
`bank_reference`	Bank’s transaction reference	`FLW-REF-123456`
`rate_id`	FX rate used	`rate_8x7k2mq9p`
`amount_asset`	Asset amount after conversion	`9.70`
`asset`	Asset type	`USDC`, `USDT`
`chain`	Blockchain network	`BASE`, `ETH`, etc.
`tx_hash`	On-chain transaction hash	`0x8f3e2d...`
`status`	Current state	See Deposit Statuses
`failure_reason`	Why deposit failed (if applicable)	`"Rate expired"`
`flag_reason`	Why flagged (if applicable)	`"Deposit after expiry"`
`created_at`	When deposit received	`2026-01-14T15:06:30Z`
`settled_at`	When fully settled	`2026-01-14T15:08:15Z`
`updated_at`	Last status change	`2026-01-14T15:08:15Z`

Bank sender details (sender_name, sender_account, sender_bank) are captured internally but not exposed via API in v0.1.

Deposit Statuses

Status	Description	Terminal?	Merchant Action Required?
`PENDING_FX`	NGN received, awaiting FX execution	❌ No	❌ No
`PENDING_WITHDRAWAL`	FX done, waiting for on-chain confirmation	❌ No	❌ No
`SETTLED`	Fully complete (on-chain or balance credit)	✅ Yes	❌ No
`FAILED`	Permanent failure	✅ Yes	✅ Contact support
`FLAGGED`	Held for manual review	✅ Yes	✅ Contact support
`REVERSED`	Bank reversed the transfer	✅ Yes	❌ No

Terminal vs Non-Terminal States

Non-terminal states (in-progress):

PENDING_FX → FX conversion in progress
PENDING_WITHDRAWAL → On-chain broadcast in progress

Terminal states (final):

SETTLED → Success
FAILED → Permanent failure
FLAGGED → Requires manual ops review
REVERSED → Bank reversed the original transfer

Deposits in FAILED, FLAGGED, or REVERSED states are not counted as Daya-owned funds and are excluded from treasury calculations.

Deposit Lifecycle

Lifecycle Stages

NGN deposit received, FX not yet executedTriggers:

Bank transfer lands in virtual account
Webhook from payment provider received

Next steps:

Validate deposit is within onramp TTL and rate expiry
Check limits (per-onramp, per-merchant, system-wide)
Execute FX conversion

Webhook: deposit.created

FX executed, waiting for on-chain confirmationOnly for AUTO_WITHDRAW modeActions:

Risk engine evaluates withdrawal
If approved, broadcast to blockchain
Wait for on-chain confirmation

Duration: Typically 1-5 minutes depending on chain

Deposit fully completeAuto-Withdraw:

On-chain transaction confirmed
Funds in user’s wallet

Merchant Balance:

USD credited to merchant’s internal balance
Available for withdrawal via separate API

Webhook: deposit.settled

Permanent failureCommon causes:

FX execution error (no liquidity, internal error)
On-chain failure (gas issues, network outage)
Invalid destination address

Merchant action: Contact support for resolutionWebhook: deposit.failed

Held for manual reviewCommon causes:

Deposit after onramp/rate expiry
Limits exceeded
Risk engine flagged transaction
Suspicious activity detected

Resolution: Requires manual operations reviewWebhook: deposit.flagged

Bank reversed the original transferCause: Bank clawback (rare but possible)Impact:

If payout already occurred, Daya absorbs the loss (v0.1)
Merchant not charged back in v0.1

Webhook: deposit.reversed (future)

Idempotency

Duplicate bank transfers with the same bank_reference create only one deposit record. Why?

Banks may send duplicate webhooks
User may accidentally transfer twice to same VA
Payment provider may retry notifications

Guarantee: Each unique bank_reference maps to exactly one deposit_id.

Your webhook handler should also implement idempotency by checking event_id or deposit_id to avoid processing the same event twice.

Querying Deposits

List Deposits

Retrieve deposits with optional filters:

GET /v1/deposits?onramp_id=onramp_123&status=SETTLED&from=2026-01-01&to=2026-01-31

Query Parameters:

Parameter	Description	Example
`onramp_id`	Filter by onramp	`onramp_3j5k8n2q`
`status`	Filter by status	`SETTLED`, `PENDING_FX`
`from`	Start date (ISO 8601)	`2026-01-01T00:00:00Z`
`to`	End date (ISO 8601)	`2026-01-31T23:59:59Z`
`page`	Page number	`1`
`per_page`	Results per page	`20` (max 100)

See List Deposits API.

Get Single Deposit

Retrieve specific deposit by ID:

GET /v1/deposits/{deposit_id}

See Get Deposit API.

Example Responses

{
  "deposit_id": "dep_9x2k5m8p",
  "onramp_id": "onramp_3j5k8n2q",
  "payment_reference": "DAYA-3J5K8N2Q",
  "user_email": "[email protected]",
  "amount_ngn": "15000.00",
  "status": "SETTLED",
  "rate_id": "rate_8x7k2mq9p",
  "amount_asset": "9.70",
  "asset": "USDC",
  "chain": "BASE",
  "tx_hash": "0x8f3e2d1c0b9a8e7f6d5c4b3a2e1f0d9c8b7a6e5f4d3c2b1a",
  "created_at": "2026-01-14T15:06:30Z",
  "settled_at": "2026-01-14T15:08:15Z",
  "updated_at": "2026-01-14T15:08:15Z"
}

Atomicity Guarantees

FX conversion and settlement are atomic:

Either: Both FX and settlement succeed → SETTLED
Or: One or both fail → FAILED or FLAGGED

Never possible: Partial FX (e.g., NGN debited but USDC not credited) This is enforced via double-entry ledger accounting. All money-affecting operations create compensating ledger entries.

Common Deposit Flows

Happy Path (Auto-Withdraw)
Happy Path (Merchant Balance)
Late Deposit (Flagged)
Limit Exceeded (Flagged)

User transfers 15,000 NGN to virtual account
Deposit created: PENDING_FX
FX executed: 15,000 NGN → 9.70 USDC
Risk engine approves withdrawal
Status → PENDING_WITHDRAWAL
On-chain transaction broadcast to BASE
Transaction confirms
Status → SETTLED
Webhook: deposit.settled

Duration: 2-5 minutes

User transfers 15,000 NGN
Deposit created: PENDING_FX
FX executed: 15,000 NGN → 9.70 USDC equivalent
USD credited to merchant balance
Status → SETTLED
Webhook: deposit.settled

Duration: 1-2 minutes

Onramp expires at 15:30:00
User transfers NGN at 15:35:00
Deposit created: FLAGGED
flag_reason: “Deposit after expiry”
Webhook: deposit.flagged
Requires manual ops resolution

Merchant has used $9,500 of daily$ 10,000 limit
User transfers NGN equivalent to $600
Deposit created: PENDING_FX
Limit check fails
Status → FLAGGED
flag_reason: “Merchant daily limit exceeded”
Webhook: deposit.flagged

Merchant-Visible Fields Only

The following fields are captured internally but not exposed via API:

sender_name (bank sender’s name)
sender_account (sender’s account number)
sender_bank (sender’s bank code)
Internal risk scores
Detailed risk engine decision logs

If you need sender details for support or compliance, contact Daya operations with the deposit_id.

Best Practices

Use webhooks, not polling

Set up webhooks for real-time updates instead of polling GET /v1/deposits.

Handle all terminal states

Your application should gracefully handle SETTLED, FAILED, FLAGGED, and REVERSED.

Store deposit_id with user records

Link deposit_id to your user’s transaction history for easy lookup.

Implement idempotency in webhooks

Use event_id or deposit_id to deduplicate webhook deliveries.

Show tx_hash to users

Display tx_hash (if available) so users can verify on-chain settlement on block explorers.

Next Steps

Lifecycle & Statuses

Detailed deposit status explanations

Webhooks

Set up real-time event notifications

List Deposits API

API reference for querying deposits

Getting Started

Core Concepts

Onramp Types

Lifecycle & Statuses

Limits & Risk

What is a Deposit?

Deposit Properties

Deposit Statuses

Terminal vs Non-Terminal States

Deposit Lifecycle

Lifecycle Stages

Idempotency

Querying Deposits

List Deposits

Get Single Deposit

Example Responses

Atomicity Guarantees

Common Deposit Flows

Merchant-Visible Fields Only

Best Practices

Next Steps

Lifecycle & Statuses

Webhooks

List Deposits API

Getting Started

Core Concepts

Onramp Types

Lifecycle & Statuses

Limits & Risk

​What is a Deposit?

​Deposit Properties

​Deposit Statuses

​Terminal vs Non-Terminal States

​Deposit Lifecycle

​Lifecycle Stages

​Idempotency

​Querying Deposits

​List Deposits

​Get Single Deposit

​Example Responses

​Atomicity Guarantees

​Common Deposit Flows

​Merchant-Visible Fields Only

​Best Practices

​Next Steps

Lifecycle & Statuses

Webhooks

List Deposits API

What is a Deposit?

Deposit Properties

Deposit Statuses

Terminal vs Non-Terminal States

Deposit Lifecycle

Lifecycle Stages

Idempotency

Querying Deposits

List Deposits

Get Single Deposit

Example Responses

Atomicity Guarantees

Common Deposit Flows

Merchant-Visible Fields Only

Best Practices

Next Steps