Skip to content
FWallet Docs

Quick Start

This guide walks you through creating a tenant, provisioning an API key, creating a wallet, funding it via a simulated mobile money deposit, and transferring money — all in under 5 minutes.

Base URL: https://api.fwallet.co.ug

  1. Create an organization (tenant)

    Every FWallet deployment is multi-tenant. Start by creating your organization:

    Terminal window
    curl -X POST https://api.fwallet.co.ug/v1/tenants \
      -H "Content-Type: application/json" \
      -H "X-System-Key: $SYSTEM_KEY" \
      -d '{
        "name": "My Company",
        "slug": "my-company",
        "config": {
          "defaultCurrency": "UGX",
          "allowedCurrencies": ["UGX", "USD"],
          "maxTransactionAmount": 50000000
        }
      }'

    Response:

    {
      "id": "tn_01JQHXYZ...",
      "name": "My Company",
      "slug": "my-company",
      "config": {
        "defaultCurrency": "UGX",
        "allowedCurrencies": ["UGX", "USD"],
        "maxTransactionAmount": 50000000
      },
      "createdAt": "2026-03-18T10:00:00.000Z"
    }

    Save the id — you will need it in the next step.

  2. Get an API key

    Provision a key scoped to your tenant:

    Terminal window
    curl -X POST https://api.fwallet.co.ug/v1/tenants/tn_01JQHXYZ.../api-keys \
      -H "Content-Type: application/json" \
      -H "X-System-Key: $SYSTEM_KEY" \
      -d '{
        "name": "Production Key",
        "scopes": [
          "ledger:read",
          "ledger:write",
          "wallet:transfer",
          "wallet:deposit",
          "tenant:manage"
        ],
        "environment": "test"
      }'

    Response:

    {
      "id": "ak_01JQHXYZ...",
      "name": "Production Key",
      "key": "fwk_test_a1b2c3d4e5f6...",
      "scopes": ["ledger:read", "ledger:write", "wallet:transfer", "wallet:deposit", "tenant:manage"],
      "environment": "test",
      "createdAt": "2026-03-18T10:00:01.000Z"
    }

  3. Create a wallet

    Create a UGX wallet for a user:

    Terminal window
    curl -X POST https://api.fwallet.co.ug/v1/wallets \
      -H "Content-Type: application/json" \
      -H "X-API-Key: fwk_test_a1b2c3d4e5f6..." \
      -H "Idempotency-Key: create-wallet-user-001" \
      -d '{
        "ownerType": "user",
        "ownerId": "user-001",
        "currencyCode": "UGX"
      }'

    Response:

    {
      "id": "wl_01JQHXYZ...",
      "tenantId": "tn_01JQHXYZ...",
      "ownerType": "user",
      "ownerId": "user-001",
      "currencyCode": "UGX",
      "balance": "0",
      "status": "active",
      "createdAt": "2026-03-18T10:00:02.000Z"
    }

    Note: the balance field is returned as a string to avoid JSON number precision issues.

  4. Fund the wallet (simulate a MoMo deposit)

    Simulate a mobile money provider webhook delivering funds to the wallet:

    Terminal window
    curl -X POST https://api.fwallet.co.ug/v1/deposits/momo-webhook \
      -H "Content-Type: application/json" \
      -H "X-API-Key: fwk_test_a1b2c3d4e5f6..." \
      -d '{
        "transactionId": "MOMO-ABC12345",
        "phoneNumber": "+256700100001",
        "amount": 500000,
        "currencyCode": "UGX",
        "walletId": "wl_01JQHXYZ...",
        "signature": "demo-signature",
        "timestamp": "2026-03-18T10:00:00Z"
      }'

    Response:

    {
      "id": "dep_01JQHXYZ...",
      "walletId": "wl_01JQHXYZ...",
      "amount": "500000",
      "currencyCode": "UGX",
      "source": "momo",
      "externalRef": "MOMO-ABC12345",
      "status": "completed",
      "journalEntryId": "je_01JQHXYZ...",
      "createdAt": "2026-03-18T10:00:03.000Z"
    }

    The deposit creates a journal entry in the ledger:

    DR  momo-float:ug-mtn     500,000 UGX   (external funds received)
    CR  wallet:user-001        500,000 UGX   (user balance increased)

  5. Transfer money between wallets

    First, create a second wallet (the recipient), then transfer funds:

    Terminal window
    # Create the recipient wallet
    curl -X POST https://api.fwallet.co.ug/v1/wallets \
      -H "Content-Type: application/json" \
      -H "X-API-Key: fwk_test_a1b2c3d4e5f6..." \
      -H "Idempotency-Key: create-wallet-user-002" \
      -d '{
        "ownerType": "user",
        "ownerId": "user-002",
        "currencyCode": "UGX"
      }'
    Terminal window
    # Transfer 100,000 UGX from user-001 to user-002
    curl -X POST https://api.fwallet.co.ug/v1/transfers \
      -H "Content-Type: application/json" \
      -H "X-API-Key: fwk_test_a1b2c3d4e5f6..." \
      -H "Idempotency-Key: transfer-001" \
      -d '{
        "fromWalletId": "wl_01JQHXYZ...",
        "toWalletId": "wl_02ABCDEF...",
        "amount": 100000,
        "currencyCode": "UGX"
      }'

    Response:

    {
      "id": "tx_01JQHXYZ...",
      "fromWalletId": "wl_01JQHXYZ...",
      "toWalletId": "wl_02ABCDEF...",
      "amount": "100000",
      "currencyCode": "UGX",
      "fee": "2000",
      "status": "completed",
      "journalEntryId": "je_02ABCDEF...",
      "createdAt": "2026-03-18T10:00:05.000Z"
    }

    The transfer creates a balanced journal entry:

    DR  wallet:user-001       100,000 UGX   (sender debited)
    DR  wallet:user-001         2,000 UGX   (fee debited from sender)
    CR  wallet:user-002       100,000 UGX   (receiver credited)
    CR  revenue:fees            2,000 UGX   (platform fee revenue)

What’s Next?