> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexapay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdrawals

# Withdrawals

## Request Withdrawal (API Key)

`POST /business/withdrawal/request`

Withdrawal requests are processed by NexaPay, and the final outcome is also sent to your webhook URL as a signed event.

### Response (Production)

```json theme={null}
{
  "success": true,
  "msg": "Withdrawal successful",
  "withdrawal": {
    "transactionId": "NEXA-...",
    "amount": 10000,
    "fee": 250,
    "totalDebit": 10250,
    "bankAccount": "0123456789",
    "status": "COMPLETED"
  }
}
```

### Response (Test Key)

```json theme={null}
{
  "success": true,
  "msg": "Test withdrawal completed successfully",
  "withdrawal": {
    "transactionId": "NEXA-...",
    "amount": 10000,
    "fee": 250,
    "totalDebit": 10250,
    "bankAccount": "0123456789",
    "status": "COMPLETED",
    "environment": "test",
    "simulated": true
  }
}
```

### Notes

* Production-key withdrawals validate the recipient and call the real transfer provider.
* Test-key withdrawals use sandbox balances only and do not trigger a real transfer.
* Successful withdrawals emit a `withdrawal.completed` webhook.
* Failed withdrawals emit a `withdrawal.failed` webhook.

## Webhook Events

The webhook payload includes the merchant reference data stored with the transaction so your backend can reconcile the payout against the correct customer or order.

See [Webhooks](webhooks) for the full payload shape and signature headers.

### Invalid Example (Insufficient Balance)

```json theme={null}
{
  "success": false,
  "msg": "Insufficient balance. You need ₦10,250"
}
```

## Withdrawal History

Withdrawal history is currently available in the merchant dashboard only and is not exposed for server-to-server integrations.

## Crypto Withdrawals

Merchants can also withdraw from their `USDT balance` through the crypto withdrawal endpoints. NexaPay converts the requested `USDT` amount to `NGN` and settles the `NGN` equivalent to the merchant's saved bank account.

### Generate Withdrawal Quote

`POST /business/crypto/withdrawals/quote`

```json theme={null}
{
  "amountUsdt": 100
}
```

### Quote Response

```json theme={null}
{
  "success": true,
  "quote": {
    "amountUsdt": 100,
    "conversionRate": 1520,
    "grossAmountNgn": 152000,
    "withdrawalFeeNgn": 3090,
    "netAmountNgn": 148910,
    "availableUsdtBalance": 1250.5,
    "pendingUsdtBalance": 50,
    "bankAccount": "0123456789",
    "bankName": "GTBank"
  }
}
```

### Request Crypto Withdrawal

`POST /business/crypto/withdrawals/request`

```json theme={null}
{
  "amountUsdt": 100
}
```

### Success Response

```json theme={null}
{
  "success": true,
  "msg": "Crypto withdrawal successful",
  "withdrawal": {
    "withdrawalId": "bcwd_1747713000000_a1b2c3d4",
    "amountUsdt": 100,
    "conversionRate": 1520,
    "grossAmountNgn": 152000,
    "withdrawalFeeNgn": 3090,
    "netAmountNgn": 148910,
    "bankAccount": "0123456789",
    "bankName": "GTBank",
    "providerReference": "NEXA-REF-123",
    "status": "COMPLETED"
  }
}
```

### History

`GET /business/crypto/withdrawals/history`