Skip to main content

​
Overview

The Daya Onramps API is built around three core entities: Onramps, Deposits, and Rates. Understanding these concepts is essential for successful integration.

​
Key Entities

Onramps

Deposit configurations that define how NGN is converted and settled

Deposits

Individual NGN inflows into an onramp’s virtual account

Rates

Firm FX quotes with guaranteed exchange rates and TTL

​
Onramps

An onramp is a deposit configuration that specifies:
  • Type: Permanent (long-lived) or Throwaway (ephemeral)
  • Virtual Account: NGN bank account details for receiving deposits
  • Rate Semantics: How FX conversion is determined
  • Settlement Behavior: Where converted funds go (auto-withdraw or merchant balance)
Think of an onramp as a “recipe” for processing deposits. Once created, its settlement configuration is immutable.

​
Onramp Lifecycle

Learn more in Onramps.

​
Deposits

A deposit represents a single NGN bank transfer into an onramp’s virtual account. Each deposit:
  • Has a unique deposit_id and payment_reference
  • Is tied to one onramp
  • Undergoes FX conversion (if within validity window)
  • Results in settlement (on-chain withdrawal or balance credit)

​
Deposit Lifecycle

Learn more in Deposits.

​
Rates

A rate is a firm FX quote with:
  • Exchange Rate: NGN → USDC/USDT conversion rate
  • TTL: Approximately 30-minute validity window
  • Minimum Deposit: Per-chain minimum amounts
New rates are generated every ~10 minutes. Throwaway onramps lock to a specific rate_id at creation.

​
Rate Validity

Onramp TypeFX Rate UsedBehavior
ThrowawayBound rate_idUses rate locked at onramp creation time
PermanentCurrent rateUses latest rate at deposit settlement time
Deposits arriving after rate_id expiry (for throwaway onramps) are flagged and require manual operations review.
Learn more in Rates.

​
Settlement Modes

Daya supports two settlement modes:
For: Direct payment to user walletsAfter FX conversion, USDC/USDT is automatically withdrawn to the specified on-chain address.Requires:
  • destination_address
  • asset (USDC or USDT)
  • chain (e.g., BASE, Ethereum)
Use case: Apps that want to pay users directly without holding funds.

​
Relationship Model

​
Guarantees

For throwaway onramps, the rate_id at creation time is guaranteed for deposits within the validity window. No slippage or rate changes.
Duplicate bank transfers (same bank_reference) create only one deposit record. Webhooks may deliver multiple times, but your system should handle deduplication.
FX conversion and settlement are atomic. Partial execution is impossible—either both succeed or both fail.
Once created, onramp settlement configuration cannot be changed. This prevents unauthorized modification attacks.

​
Edge Cases

Understanding edge cases is critical for production readiness. See Edge Cases & Guarantees for detailed failure mode documentation.
Common edge cases:
  • Late deposits: NGN arrives after onramp/rate expiry → FLAGGED
  • FX failures: No liquidity or conversion error → FAILED or FLAGGED
  • On-chain failures: Gas issues or network problems → FAILED
  • Bank reversals: Original transfer reversed by bank → REVERSED

​
Next Steps

Onramps

Deep dive into onramp types and configuration

Deposits

Understand deposit lifecycle and statuses

Rates

Learn about FX quotes and rate validity