Skip to main content

​
What is an Onramp?

An onramp is a deposit configuration that defines:
  1. How deposits are received (virtual account details)
  2. When deposits are valid (TTL and expiry)
  3. What rate is used for FX conversion
  4. Where converted funds are sent (settlement mode)
Once created, an onramp’s settlement configuration is immutable.

​
Onramp Properties

Every onramp has the following properties:
PropertyDescriptionExample
onramp_idUnique identifieronramp_3j5k8n2q
merchant_idOwner (inferred from API key)merch_abc123
typePERMANENT or THROWAWAYTHROWAWAY
statusCurrent stateACTIVE, EXPIRED, DISABLED, FLAGGED
user.emailEnd-user email[email protected]
rate_idAssociated FX quoterate_8x7k2mq9p
payment_referenceUnique payment identifierDAYA-3J5K8N2Q
virtual_accountNGN bank account detailsSee below
expires_atWhen onramp becomes invalid2026-01-14T15:30:00Z
settlementWhere funds go after conversionSee Settlement Modes
created_atCreation timestamp2026-01-14T15:05:12Z

​
Virtual Account Object

{
  "account_number": "9876543210",
  "account_name": "Daya - [email protected]",
  "bank_name": "Wema Bank",
  "bank_code": "035"
}
Virtual account numbers are never reused within 365 days to prevent accidental deposits to the wrong merchant.

​
Onramp Types

Daya supports two onramp types:
Long-lived virtual account for recurring deposits from the same user.Characteristics:
  • No expiry (remains ACTIVE indefinitely)
  • Uses current FX rate at deposit time (not locked to rate_id)
  • Typically tied to one user and one destination address
  • Best for repeat customers
Use case: A user regularly deposits NGN monthly. Create one permanent onramp and reuse.→ Learn more

​
Settlement Modes

AUTO_WITHDRAW

Automatically send USDC/USDT to specified on-chain address after FX conversion.Requires:
  • destination_address
  • asset (USDC or USDT)
  • chain (BASE, Ethereum, etc.)

MERCHANT_BALANCE

Credit merchant’s internal Daya USD balance. Withdraw later via separate API.Requires:
  • No destination address needed

​
Settlement Configuration

Auto-Withdraw Example: 
{
  "settlement": {
    "mode": "AUTO_WITHDRAW",
    "asset": "USDC",
    "chain": "BASE",
    "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}
Merchant Balance Example: 
{
  "settlement": {
    "mode": "MERCHANT_BALANCE"
  }
}
Settlement configuration is immutable. To change destination or mode, create a new onramp.

​
Onramp Statuses

StatusDescriptionCan Receive Deposits?
ACTIVEOnramp is operational✅ Yes (if within TTL)
EXPIREDTTL elapsed (throwaway only)❌ No (deposits flagged)
DISABLEDManually disabled by operations❌ No
FLAGGEDRisk or compliance review triggered❌ No

​
Status Transitions

​
Creating Onramps

Use POST /v1/onramp to create an onramp: 
curl --request POST \
  --url https://api.daya.xyz/v1/onramp \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "THROWAWAY",
    "user": {
      "email": "[email protected]"
    },
    "rate_id": "rate_8x7k2mq9p",
    "settlement": {
      "mode": "AUTO_WITHDRAW",
      "asset": "USDC",
      "chain": "BASE",
      "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }
  }'
See API Reference for full details.

​
Rate Binding Semantics

Locked to rate_id at creation:
  1. Merchant requests rate_id via GET /v1/rates
  2. Merchant creates onramp with that rate_id
  3. Deposit arrives before rate_id.expires_at → FX uses that rate
  4. Deposit arrives after expiry → FLAGGED, no automatic FX
Guarantee: Rate is firm. No slippage within validity window.

​
Common Patterns

User buys $10 USDC once:
  1. Request GET /v1/rates → get rate_id
  2. Create throwaway onramp with auto-withdraw
  3. User transfers NGN within 25 minutes
  4. USDC sent to user’s wallet
  5. Onramp expires (cannot be reused)
User deposits monthly salary:
  1. Create permanent onramp once
  2. User saves virtual account details
  3. User transfers NGN monthly
  4. Each deposit converts at current rate
  5. USDC sent to same destination address each time
App processes 1000 small deposits:
  1. Create throwaway onramps with MERCHANT_BALANCE
  2. Users transfer NGN
  3. All deposits credited to merchant’s internal USD balance
  4. Merchant withdraws in bulk to reduce on-chain fees

​
Best Practices

1

Always check rate_id expiry

Before creating throwaway onramps, ensure rate_id.expires_at is at least 25 minutes in the future.
2

Use permanent VAs for repeat users

If a user deposits regularly, create one permanent onramp instead of multiple throwaway onramps.
3

Store onramp_id with user records

Link onramp_id to your user’s profile for easy lookup and support.
4

Handle expiry gracefully

Educate users that throwaway onramps expire in 25 minutes. Show countdown timers.
5

Monitor for FLAGGED status

Set up webhooks to detect onramp.flagged events and alert your operations team.

​
Limits

Each merchant can create up to 1,000 onramps per day. Exceeding this triggers automatic account freeze. See Limits & Risk for details.

​
Next Steps

Deposits

Learn how deposits flow through onramps

Rates

Understand FX quotes and rate validity

Create Onramp API

API reference for creating onramps