> ## 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.

# Merchant Withdrawals

> How merchant-balance withdrawals are created, tracked, and completed

## 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.

<Info>
  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.
</Info>

***

## 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](/api-reference/merchant-funding/get-merchant-funding) deposits | [Transfers](/api-reference/transfers/create-transfer) to bank recipients, on-chain withdrawals |

To use collection funds for transfers or withdrawals, move them to your withdrawal balance via [`POST /v1/merchant/balance/transfer`](/api-reference/merchant-balance/transfer-merchant-balance).

You can also fund the withdrawal balance directly:

* **Crypto deposits** — send stablecoins to your [merchant funding](/api-reference/merchant-funding/get-merchant-funding) crypto wallet addresses on any supported chain.
* **NGN deposits** — transfer Naira to your permanent [merchant funding](/api-reference/merchant-funding/get-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](/api-reference/transfers/create-transfer) instead.

Typical flow:

1. Fund your balance — funding account deposits and USD virtual account deposits land in the collection balance, or fund directly via merchant funding
2. Move funds to the withdrawal balance via [`POST /v1/merchant/balance/transfer`](/api-reference/merchant-balance/transfer-merchant-balance) (skip this step if funded via merchant funding)
3. Create a withdrawal to a supported chain and token
4. 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:

1. **Created**
   A withdrawal request is accepted against available merchant balance

2. **Submitted**
   The withdrawal is successfully initiated with the provider

3. **Completed**
   The withdrawal becomes `SETTLED` or `FAILED`

<Info>
  Withdrawal progress can be tracked via both the withdrawal read APIs and merchant webhook events.
</Info>

***

## Webhook Events

Merchant-configured webhook endpoints receive withdrawal lifecycle events:

* `withdrawal.created`
* `withdrawal.submitted`
* `withdrawal.completed`
* `withdrawal.failed`

Each webhook uses the common merchant webhook envelope:

* `event`
* `timestamp`
* `data` (the public withdrawal object)

***

## Supported Chains and Tokens

Withdrawals are constrained by token-level support, not just chain-level support.

<Info>
  Withdrawals currently support chains: **SOLANA**, **TRON**, **APTOS**, **BASE**, **POLYGON**, **ETHEREUM** with tokens **USDC** and **USDT**.
</Info>

Use [List Supported Chains](/api-reference/supported-chains/list-supported-chains) to fetch the current live matrix of supported chains and token combinations.

***

## API Routes

Use these routes to work with balances and withdrawals:

* [Get Merchant Balance](/api-reference/merchant-balance/get-merchant-balance) — check collection and withdrawal balances
* [Transfer Merchant Balance](/api-reference/merchant-balance/transfer-merchant-balance) — move funds from collection to withdrawal
* [Get Merchant Funding](/api-reference/merchant-funding/get-merchant-funding) — view funding instructions (NGN account + crypto wallets)
* [Create Transfer](/api-reference/transfers/create-transfer) — send funds to bank recipients (NGN, ACH, wire, SWIFT)
* [Withdraw Merchant Balance](/api-reference/merchant-balance/withdraw-merchant-balance) — withdraw to an on-chain address
* [List Withdrawals](/api-reference/merchant-balance/list-withdrawals)
* [Get Withdrawal](/api-reference/merchant-balance/get-withdrawal)

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Merchant Balance" icon="wallet" href="/api-reference/merchant-balance/get-merchant-balance">
    Check available funds before creating withdrawals
  </Card>

  <Card title="Supported Chains" icon="server" href="/api-reference/supported-chains/list-supported-chains">
    Validate supported chain and token combinations
  </Card>

  <Card title="Webhook Events" icon="bell" href="/api-reference/webhooks/events">
    Track withdrawal lifecycle asynchronously
  </Card>
</CardGroup>