Skip to main content

​
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)

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

​
Response (Test Key)

{
  "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 for the full payload shape and signature headers.

​
Invalid Example (Insufficient Balance)

{
  "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 
{
  "amountUsdt": 100
}

​
Quote Response

{
  "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 
{
  "amountUsdt": 100
}

​
Success Response

{
  "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