What is a Withdrawal?
A withdrawal moves funds from your Daya withdrawal balance to an on-chain destination address. Withdrawals are separate from deposits and transfers. A deposit may settle into the merchant collection balance first, then be transferred to the withdrawal balance, and the withdrawal happens later as its own lifecycle.The merchant balance is split into a collection balance and a withdrawal balance. Withdrawals draw from the withdrawal balance. Use
POST /v1/merchant/balance/transfer to move funds from collection to withdrawal.How the Merchant Balance Works
Your merchant balance has two sides:| Balance | What goes in | What goes out |
|---|---|---|
| Collection balance | Funding account deposits and USD virtual account deposits | Balance transfers to withdrawal balance |
| Withdrawal balance | Balance transfers from collection, merchant funding deposits | Transfers to bank recipients, on-chain withdrawals |
POST /v1/merchant/balance/transfer.
You can also fund the withdrawal balance directly:
- Crypto deposits — send stablecoins to your merchant funding crypto wallet addresses on any supported chain.
- NGN deposits — transfer Naira to your permanent merchant funding NGN bank account. These are converted to USD at the current rate.
When Withdrawals Are Used
Withdrawals apply when you want to move funds from your Daya withdrawal balance to an on-chain crypto address. For sending funds to bank accounts, use the Transfers API instead. Typical flow:- Fund your balance — funding account deposits and USD virtual account deposits land in the collection balance, or fund directly via merchant funding
- Move funds to the withdrawal balance via
POST /v1/merchant/balance/transfer(skip this step if funded via merchant funding) - Create a withdrawal to a supported chain and token
- Daya tracks the withdrawal until it settles or fails
Withdrawal Properties
Each withdrawal is represented by the following fields:| Property | Description |
|---|---|
id | Unique withdrawal identifier |
amount_usd | Amount withdrawn from merchant balance |
chain | Destination chain |
token | Token sent on-chain |
destination_address | Recipient address |
status | Current withdrawal status |
failure_code | Failure code if unsuccessful |
failure_message | Human-readable failure detail |
provider_tx_id | Provider-side transfer identifier |
tx_hash | On-chain transaction hash after submission/settlement |
created_at | When the withdrawal record was created |
updated_at | Last update time |
submitted_at | When the withdrawal was submitted to the provider |
settled_at | When the withdrawal completed |
Withdrawal Statuses
| Status | Meaning | Terminal |
|---|---|---|
PENDING | Withdrawal record exists but has not been submitted yet | No |
SUBMITTED | Sent to the provider and awaiting final outcome | No |
SETTLED | Withdrawal completed successfully | Yes |
FAILED | Withdrawal failed permanently | Yes |
Lifecycle
At a high level, withdrawals move through these stages:- Created A withdrawal request is accepted against available merchant balance
- Submitted The withdrawal is successfully initiated with the provider
-
Completed
The withdrawal becomes
SETTLEDorFAILED
Withdrawal progress can be tracked via both the withdrawal read APIs and merchant webhook events.
Webhook Events
Merchant-configured webhook endpoints receive withdrawal lifecycle events:withdrawal.createdwithdrawal.submittedwithdrawal.completedwithdrawal.failed
eventtimestampdata(the public withdrawal object)
Supported Chains and Tokens
Withdrawals are constrained by token-level support, not just chain-level support.Withdrawals currently support chains: SOLANA, TRON, APTOS, BASE, POLYGON, ETHEREUM with tokens USDC and USDT.
API Routes
Use these routes to work with balances and withdrawals:- Get Merchant Balance — check collection and withdrawal balances
- Transfer Merchant Balance — move funds from collection to withdrawal
- Get Merchant Funding — view funding instructions (NGN account + crypto wallets)
- Create Transfer — send funds to bank recipients (NGN, ACH, wire, SWIFT)
- Withdraw Merchant Balance — withdraw to an on-chain address
- List Withdrawals
- Get Withdrawal
Next Steps
Merchant Balance
Check available funds before creating withdrawals
Supported Chains
Validate supported chain and token combinations
Webhook Events
Track withdrawal lifecycle asynchronously