Accounts & Wallets

Each user has one or more wallets. Wallets hold balances in a specific currency and can be frozen, configured with limits, or designated as the primary wallet.

Wallet Types

Type	Description
main	Default wallet created at registration
savings	Linked to a savings product
investment	Investment account
business	Business/merchant wallet

List Wallets

GET /api/v1/wallets

cURL

curl https://api.korastratum.com/api/v1/banking/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: fmfb"

Node.js

const res = await fetch("https://api.korastratum.com/api/v1/banking/wallets", {
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Tenant-ID": "fmfb",
  },
});
const wallets = (await res.json()).data;

Python

res = requests.get(
    "https://api.korastratum.com/api/v1/banking/wallets",
    headers={"Authorization": f"Bearer {token}", "X-Tenant-ID": "fmfb"},
)
wallets = res.json()["data"]

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "walletNumber": "0000123456",
      "walletType": "main",
      "currency": "NGN",
      "balance": 1500000.00,
      "availableBalance": 1500000.00,
      "isActive": true,
      "isFrozen": false,
      "isPrimary": true,
      "dailyLimit": 5000000.00,
      "monthlyLimit": 50000000.00,
      "createdAt": "2025-07-01T10:00:00Z"
    }
  ]
}

Create a Wallet

POST /api/v1/wallets

{
  "walletType": "business",
  "currency": "USD"
}

Response:

{
  "success": true,
  "data": {
    "id": "f8e7d6c5-...",
    "walletNumber": "0000789012",
    "walletType": "business",
    "currency": "USD",
    "balance": 0.00,
    "availableBalance": 0.00,
    "isActive": true,
    "isFrozen": false,
    "isPrimary": false,
    "dailyLimit": 5000000.00,
    "monthlyLimit": 50000000.00
  }
}

Supported currencies: NGN, USD, GBP.

Get Wallet Details

GET /api/v1/wallets/:id

Returns the same wallet object shown above, including current balance and limits.

Freeze / Unfreeze a Wallet

Freezing a wallet blocks all debits. Credits (incoming transfers) still succeed.

POST /api/v1/wallets/:id/freeze
POST /api/v1/wallets/:id/unfreeze

When a wallet is frozen:

• Transfers out return 403 with code WALLET_FROZEN
• Bill payments from the wallet are blocked
• Loan disbursements to the wallet still proceed
• Incoming transfers are credited normally

Transaction Limits

Each wallet has daily and monthly limits that depend on the user's KYC level:

KYC Level	Daily Limit (NGN)	Monthly Limit (NGN)
Level 1	300,000	1,000,000
Level 2	2,000,000	10,000,000
Level 3	5,000,000	50,000,000

Check a user's current usage against their limits:

GET /api/v1/transaction-limits

{
  "success": true,
  "data": {
    "dailyLimit": 5000000.00,
    "dailyUsed": 250000.00,
    "dailyRemaining": 4750000.00,
    "monthlyLimit": 50000000.00,
    "monthlyUsed": 3200000.00,
    "monthlyRemaining": 46800000.00
  }
}

GET /api/v1/transaction-limits/spending

Returns a breakdown of spending against limits by category (transfers, bills, etc.).

Account Statements

Download transaction statements as PDF or CSV:

GET /api/v1/reports/statements?from=2026-01-01&to=2026-02-28&format=pdf

GET /api/v1/transactions/download?from=2026-01-01&to=2026-02-28

Delete a Wallet

DELETE /api/v1/wallets/:id

warning

You can only delete wallets with a zero balance. The primary wallet cannot be deleted.

Next Steps

• Transfers — Send money from wallets.
• Savings — Link wallets to savings products.
• Transaction Types — All transfer types and statuses.