Create a withdrawal

Send money from a wallet out to an external bank account. Asynchronous, resolved by webhook.

POST/v1/wallets/:id/withdraw
Idempotentwallet

Withdraws from this wallet to an external bank account. Asynchronous: it returns 201 with status: "processing", then a withdrawal.completed or withdrawal.failed webhook resolves it. Requires the wallet scope and an Idempotency-Key.

Try it, for realPOST /wallets/:id/withdrawscope: wallet

Test keys only. Never paste a live key. Your key is stored only in this browser (localStorage) and sent only to the same-origin playground proxy.

›Equivalent request (curl / TypeScript)
curl
curl -X POST https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/withdraw \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: …" \
  -d '{"amount":1000000,"accountNumber":"0123456789","bankCode":"044","accountName":"ADA LOVELACE"}'
TypeScript
const res = await fetch("https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/withdraw", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACUTE_TEST_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"amount":1000000,"accountNumber":"0123456789","bankCode":"044","accountName":"ADA LOVELACE"}),
});
const { data, meta } = await res.json();

# withdraw ₦10,000 to a bank account
curl -X POST https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/withdraw \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2c8a1e-7b34-4d5a-9e1f-22c0d8b6a4e5" \
  -d '{
    "amount": 1000000,
    "accountNumber": "0123456789",
    "bankCode": "044",
    "accountName": "ADA LOVELACE"
  }'
{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "acuinf615098372240wth",
    "sourceWalletId": "acuinf483920175566wlt",
    "amount": 1000000,
    "fee": 12000,
    "totalAmount": 1012000,
    "status": "processing",
    "counterparty": {
      "accountNumber": "0123456789",
      "accountName": "ADA LOVELACE",
      "bankCode": "044",
      "bankName": "Access Bank"
    },
    "failureReason": null,
    "currency": "NGN",
    "createdAt": "2026-06-24T09:25:40.500Z",
    "completedAt": null
  },
  "meta": { "requestId": "req_4f9c2a7e1b0d8c3a5e6f10a2" }
}

Withdrawals resolve out of band

The 201 only means accepted. Treat the money as final when the withdrawal.completed webhook lands, and handle withdrawal.failed / returned, which credit the wallet back. The withdrawals guide covers the non-lossy resolver.

idstringpathrequired

The source wallet reference.

amountinteger (kobo)bodyrequired

Amount to withdraw, in kobo. Positive integer. Fees are added on top.

accountNumberstringbodyrequired

Destination NUBAN, exactly 10 digits.

bankCodestringbodyrequired

Destination bank code. See the banks reference.

accountNamestringbodyoptional

Account holder name. If omitted, the name is resolved for you; a mismatch fails name verification (WITHDRAWAL_NAME_VERIFICATION_FAILED).

narrationstringbodyoptional

Optional transfer narration.

WithdrawalResponseData.

idstringrequired

The withdrawal reference (acuinf…wth).

sourceWalletIdstringrequired

The source wallet reference.

amountnumber (kobo)required

The withdrawal amount.

feenumber (kobo)required

The total fee charged for the withdrawal, in kobo. See fees.

totalAmountnumber (kobo)required

amount + fee debited from the wallet.

status'processing' | 'completed' | 'failed' | 'returned'required

Starts processing; resolves via webhook. returned means the bank rail bounced the funds back.

counterpartyWithdrawalCounterpartyrequired

{ accountNumber, accountName, bankCode, bankName }, the destination.

failureReasonstring | nullrequired

Populated when status is failed or returned.

currencystringrequired

The currency (NGN).

createdAtstringrequired

ISO-8601 timestamp.

completedAtstring | nullrequired

Set when the withdrawal resolves; null while processing.