> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daya.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Funding Accounts
> How customers receive funds into Daya
## Overview
A **funding account** is the API resource that powers onramps and offramps. It gives a customer either an NGN virtual account or a crypto address, and lets you control where the money settles after it arrives.
Funding accounts are scoped to one customer and one rail:
| Rail | What the customer receives | Required fields |
| --------------------- | --------------------------------------- | ---------------- |
| `NGN_VIRTUAL_ACCOUNT` | Bank account details for NGN transfers | `currency: NGN` |
| `CRYPTO_ADDRESS` | Stablecoin address on a supported chain | `asset`, `chain` |
## What You Can Build
Use funding accounts to create the receive flow you need:
| Flow | Funding account shape | Settlement |
| ----------------- | ----------------------------------- | ---------------------------------- |
| Temporary onramp | `NGN_VIRTUAL_ACCOUNT` + `TEMPORARY` | `INTERNAL_BALANCE` or `ONCHAIN` |
| Permanent onramp | `NGN_VIRTUAL_ACCOUNT` + `PERMANENT` | `INTERNAL_BALANCE` or `ONCHAIN` |
| Temporary offramp | `CRYPTO_ADDRESS` + `TEMPORARY` | `NGN_PAYOUT` |
| Permanent offramp | `CRYPTO_ADDRESS` + `PERMANENT` | `INTERNAL_BALANCE` or `NGN_PAYOUT` |
For example, if you want to give a customer a reusable wallet address to collect USDC and keep the funds in your Daya balance, create a `PERMANENT` crypto funding account with `settlement_destination.type: INTERNAL_BALANCE`.
```json Reusable crypto address to Daya balance theme={null}
{
"type": "PERMANENT",
"rail": "CRYPTO_ADDRESS",
"customer": {
"customer_id": "650e8400-e29b-41d4-a716-446655440000"
},
"asset": "USDC",
"chain": "BASE",
"settlement_destination": {
"type": "INTERNAL_BALANCE"
}
}
```
The account or address the customer should pay into is returned in `instructions`.
For NGN, `instructions` contains the bank account details:
```json theme={null}
{
"currency": "NGN",
"instructions": [
{
"type": "NGN_VIRTUAL_ACCOUNT",
"status": "ACTIVE",
"bank_name": "Wema Bank",
"bank_code": "035",
"account_number": "1234567890",
"account_name": "Daya - Ada Lovelace",
"currency": "NGN"
}
]
}
```
For crypto, `asset` identifies the stablecoin, `chain` identifies the network, and `instructions` contains the wallet address:
```json theme={null}
{
"asset": "USDC",
"chain": "BASE",
"instructions": [
{
"type": "CRYPTO_ADDRESS",
"status": "ACTIVE",
"address": "0x742d35cc6634c0532925a3b844bc9e7595f2bd18",
"chain": "BASE"
}
]
}
```
The product concepts are still onramps and offramps. New integrations create both with `/v1/funding-accounts`. The Legacy API section lists older `/v1/onramps` and `/v1/offramps` routes for existing integrations.
## Account Types
| Type | Use case | Amount | Lifetime |
| ----------- | ------------------------ | -------------------------------------------------- | ----------------------- |
| `TEMPORARY` | One-time payment details | Required integer `amount` for NGN virtual accounts | May expire |
| `PERMANENT` | Reusable payment details | Not allowed | Reusable until disabled |
Permanent NGN virtual accounts require the customer to have completed Tier 1 KYC.
## Developer Fees
Developer fees let you keep a percentage of each deposit received through a funding account. Add `developer_fee.percentage` when creating the funding account.
Use a decimal string from `0` to `50`. Omit `developer_fee` to use `0%`.
`developer_fee.percentage` uses percentage values, not basis points. For example, `0.5` means `0.5%`, `2` means `2%`, and `50` means `50%`. This differs from rate `fee_bps`, where `50` means `0.5%`.
The percentage is stored on the funding account and applies to every deposit received through that account. Funding account responses include `developer_fee.percentage`. Deposit responses and deposit webhooks include `developer_fee` and `customer_amount` after Daya calculates the split, so you can reconcile your fee separately from Daya fees.
The developer fee is deducted before the final customer amount is calculated. It is not added as a separate charge. Use `developer_fee.amount` and `developer_fee.currency` to track the fee your merchant account kept, and use `customer_amount` as the amount left for the customer.
Flat developer fees, such as `NGN 500` or `$1` per transaction, are not currently supported through `developer_fee`.
## Settlement Destinations
Settlement destination controls where received funds are delivered after the funding account receives money.
| Rail | Type | Supported destinations |
| --------------------- | ----------- | -------------------------------- |
| `NGN_VIRTUAL_ACCOUNT` | `TEMPORARY` | `INTERNAL_BALANCE`, `ONCHAIN` |
| `NGN_VIRTUAL_ACCOUNT` | `PERMANENT` | `INTERNAL_BALANCE`, `ONCHAIN` |
| `CRYPTO_ADDRESS` | `TEMPORARY` | `NGN_PAYOUT` |
| `CRYPTO_ADDRESS` | `PERMANENT` | `INTERNAL_BALANCE`, `NGN_PAYOUT` |
For `NGN_PAYOUT`, fetch supported banks with [`GET /v1/banks`](/api-reference/banks/list-banks), verify the account with [`POST /v1/banks/resolve`](/api-reference/banks/resolve-bank-account), then send the verified `destination_bank.account_number` and `destination_bank.bank_code`.
## Lifecycle
Funding accounts move through these statuses:
| Status | Meaning |
| ---------- | ---------------------------------------------------------- |
| `PENDING` | Funding account setup is in progress |
| `ACTIVE` | Payment details are ready and can be shown to the customer |
| `FAILED` | Funding account setup failed |
| `DISABLED` | Funding account and active payment details are disabled |
Permanent active funding accounts can rotate settlement destination with `PATCH /v1/funding-accounts/{id}/settlement-destination`. Rotation does not create new payment details.
## Webhooks
Funding account setup emits:
| Event | When sent |
| -------------------------- | ---------------------------------------------------- |
| `funding_account.created` | Funding account record is created in `PENDING` state |
| `funding_account.active` | Payment details are ready |
| `funding_account.failed` | Setup fails |
| `funding_account.disabled` | An active funding account is disabled |
The webhook `data` object is the same public funding account response returned by the API.
## Deposits from Funding Accounts
When money arrives through a funding account, Daya creates a deposit. Deposit API responses and deposit webhook payloads include `funding_account_id` so you can connect the incoming money back to the funding account the customer paid into.
Funding-account instruction IDs stay internal. Your integration should store the public `funding_account_id` and the deposit `id`.
| Event | When sent |
| ------------------------- | --------------------------------------------------- |
| `deposit.received` | Incoming funds are recorded |
| `deposit.processing` | Settlement has started |
| `deposit.requires_review` | The deposit needs review before it can continue |
| `deposit.completed` | Funds reached the configured settlement destination |
| `deposit.failed` | The deposit failed |
| `deposit.reversed` | A completed deposit was reversed |
If settlement requires background delivery work, track the merchant-facing lifecycle with `deposit.*` events. Funding-account settlement does not emit separate payout webhooks.
## Next Steps
Create NGN or crypto payment details.
Collect NGN from customers.
Collect stablecoins from customers.
Track funding account and deposit state changes in real time.