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

# Withdraw to Bank

> Initiate a fiat withdrawal from your Daya Pro NGN balance to a Nigerian bank account

## Overview

Move NGN from your Daya Pro balance to a Nigerian bank account. The withdrawal is queued and dispatched through Daya's payout provider; the response returns immediately with a transaction ID and the initial status.

Requires **Trade** scope.

<Note>
  Requests are idempotent on `idempotency_key`. Replaying the same key always returns the original transaction without re-running the withdrawal — safe to retry on network failures.
</Note>

There are two ways to specify the destination:

1. **Saved beneficiary** — pass `bank_account_id` (UUID of a beneficiary previously stored on your account). All other bank fields are ignored.
2. **Inline details** — pass `account_number`, `bank_code`, `account_name`, `bank_name` directly.

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your API key with Trade scope
</ParamField>

## Request Body

<ParamField body="idempotency_key" type="string" required>
  Caller-supplied unique key. Reuse on retry to avoid double-spend.

  **Example:** `wd-2026-05-06-01`
</ParamField>

<ParamField body="amount" type="string" required>
  Withdrawal amount as a decimal string.

  **Example:** `1000000.00`
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code.

  **Example:** `NGN`
</ParamField>

<ParamField body="bank_account_id" type="string">
  UUID of a saved bank account on the user. When set, the inline bank fields below are ignored.
</ParamField>

<ParamField body="account_number" type="string">
  Destination NUBAN. Required when `bank_account_id` is omitted.

  **Example:** `0123456789`
</ParamField>

<ParamField body="bank_code" type="string">
  CBN bank code. Required when `bank_account_id` is omitted.

  **Example:** `058`
</ParamField>

<ParamField body="account_name" type="string">
  Account holder name as registered with the destination bank. Required when `bank_account_id` is omitted. Must match — the provider rejects mismatched names.
</ParamField>

<ParamField body="bank_name" type="string">
  Display name of the destination bank. Required when `bank_account_id` is omitted.

  **Example:** `GTBank`
</ParamField>

<ParamField body="narration" type="string">
  Optional free-form narration shown on the recipient's bank statement.
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl --request POST \
    --url https://api.pro.daya.co/public/v1/withdrawals/bank \
    --header 'X-Api-Key: daya_sk_YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "idempotency_key": "wd-2026-05-06-01",
      "account_number": "0123456789",
      "bank_code": "058",
      "account_name": "Jane Doe",
      "bank_name": "GTBank",
      "amount": "1000000.00",
      "currency": "NGN",
      "narration": "Payout for invoice 123"
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="data.transaction_id" type="string" required>
  Daya transaction UUID. Use this to track status.
</ResponseField>

<ResponseField name="data.status" type="string" required>
  Initial status. Most withdrawals return as `processing` and transition asynchronously.

  **Values:** `pending`, `processing`, `completed`, `failed`
</ResponseField>

<ResponseField name="data.amount" type="string" required>
  Echoed amount.
</ResponseField>

<ResponseField name="data.currency" type="string" required>
  Echoed currency.
</ResponseField>

<ResponseField name="data.fee" type="string">
  Fee charged for the withdrawal.
</ResponseField>

<ResponseField name="data.transfer_id" type="string">
  Provider-side transfer reference (when available).
</ResponseField>

<ResponseField name="data.created_at" type="string" required>
  ISO 8601 timestamp when the withdrawal was accepted.
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "success": true,
    "message": "Withdrawal initiated successfully",
    "data": {
      "transaction_id": "22222222-2222-2222-2222-222222222222",
      "status": "processing",
      "amount": "1000000.00",
      "currency": "NGN",
      "fee": "100.00",
      "transfer_id": "FLW-TRF-9001",
      "created_at": "2026-05-06T12:00:00Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

| Code  | Meaning                                                              |
| ----- | -------------------------------------------------------------------- |
| `400` | Validation error or insufficient balance                             |
| `403` | Missing Trade scope, or account restricted                           |
| `409` | Same `idempotency_key` previously used with a different request body |

## Notes on settlement

The response confirms the withdrawal was *accepted*, not that funds have arrived. Final settlement happens through the underlying payout provider and can take seconds to minutes depending on the destination bank.