Wallet & payouts

Read your wallet balance, manage the bank accounts you withdraw to, and initiate withdrawals. Withdrawals move real money, so they sit behind extra guardrails - read Withdrawals carefully before enabling them.

All endpoints share the prefix /v1/wallet and authenticate with an API key.

Get balance

GET /v1/wallet/balance

{
  "message": "Wallet balance retrieved",
  "data": {
    "balance": 250000,
    "availableBalance": 245000,
    "pendingWithdrawals": 5000,
    "minimumWithdrawalAmount": 1000,
    "currency": "NGN"
  }
}

availableBalance is what you can withdraw right now - it excludes funds reserved by pending withdrawals.

Payout accounts

Payout accounts are the bank accounts you withdraw to.

List payout accounts

GET /v1/wallet/payout-accounts

{
  "message": "Payout accounts retrieved",
  "data": [
    {
      "id": "pa1a2b3c-...",
      "bankName": "Example Bank",
      "accountNumber": "0123456789",
      "accountName": "Acme Foods Ltd",
      "isDefault": true
    }
  ]
}

List banks

GET /v1/wallet/banks

Returns the banks you can resolve and pay out to.

Query parameters

Resolve an account

POST /v1/wallet/payout-accounts/resolve

Verifies a bank account number and returns the registered account name. Resolve before adding an account so you store the correct name.

Body

{ "account_number": "0123456789", "bank_code": "044" }

Add a payout account

POST /v1/wallet/payout-accounts

Body

Response 201 Created - the new payout account. Send an Idempotency-Key header to avoid duplicates.

Withdrawals

Withdrawals transfer funds from your wallet to a payout account. Because a leaked key could otherwise drain a wallet, API-initiated withdrawals require all of the following:

1. The key holds the wallet:withdrawals:create scope.
2. The (live) key has an IP allowlist.
3. The key has a withdrawal policy configured (set when creating/updating the key):
   • maxPerTransaction - maximum amount per withdrawal
   • maxPerDay - maximum total per rolling day
   • allowedPayoutAccountIds - only these payout accounts may be paid out to
4. The requested payout_account_id is in the policy’s allowlist, and the amount is within both caps.

If any condition fails, the request is rejected before any money moves:

All of Cloove’s standard withdrawal safeguards (minimum amount, verification-level limits, atomic balance checks, and audit logging) still apply.

List withdrawals

GET /v1/wallet/withdrawals

Returns paginated withdrawal history (page, limit).

Initiate a withdrawal

POST /v1/wallet/withdrawals

Body

{ "amount": 25000, "payout_account_id": "pa1a2b3c-..." }

Response 201 Created

{
  "message": "Withdrawal submitted",
  "data": {
    "withdrawal": {
      "id": "w1a2b3c4-...",
      "type": "WALLET_WITHDRAWAL",
      "amount": 25000,
      "currency": "NGN",
      "status": "PENDING",
      "externalReference": "CLV-WD-...",
      "createdAt": "2026-01-15T10:00:00.000Z"
    },
    "fee": { "amount": 50, "currency": "NGN" }
  }
}