Enterprise Workflows

FWallet is designed for platform teams that operate more than one wallet business. The same backend supports super-admin platform controls, tenant-owner operations, tenant team roles, HMAC integrations, fee schedules, payout approvals, and ledger-backed reconciliation.

Use this page as the implementation checklist for an enterprise demo or first production integration.

Operating Model

Actor	Dashboard	API surface	Typical work
Super admin	`https://admin.fwallet.co.ug`	`/v1/system/*` with `X-System-Key`	Create organizations, invite tenant admins, review cross-tenant analytics, inspect wallets and ledger transactions, configure platform fee commission.
Tenant owner	`https://demo.fwallet.co.ug`	`/v1/admin/*` and tenant APIs with `X-API-Key`	Manage wallet balances, developers, team members, fees, approvals, tenant float deposits, tenant fee withdrawals, and reconciliation views.
Developer	Tenant dashboard Developers area	`/v1/developer/*`	Create apps, create restricted API keys, rotate/revoke keys, inspect request logs, and debug HMAC signatures.
Finance operator	Tenant dashboard Operations/Treasury areas	`/v1/wallets`, `/v1/deposits`, `/v1/payouts`, `/v1/admin/money/*`	Record deposits, initiate payouts, deposit tenant float, request tenant withdrawals, and review pending cases.
Approver	Tenant dashboard Approvals area	`/v1/payouts//approve`, `/v1/admin/money/withdrawals//approve`	Approve or reject payout and tenant withdrawal cases. Approver must differ from requester.
Observer	Tenant dashboard analytics/observer views	Read-only tenant APIs	Monitor activity, balances, errors, and request logs.

Tenant Onboarding

Create the organization.

A super admin creates the tenant with a default currency, allowed currencies, and transaction limit:

curl -X POST https://api.fwallet.co.ug/v1/system/organizations \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{
    "name": "Striker Market",
    "slug": "striker-market",
    "config": {
      "defaultCurrency": "UGX",
      "allowedCurrencies": ["UGX", "USD"],
      "maxTransactionAmount": 50000000
    },
    "admin": {
      "name": "Amina Finance",
      "email": "amina@example.com"
    }
  }'

This creates the tenant, creates or links an org-admin user, and sends an invite email when email delivery is configured.

Confirm system accounts exist.

Tenant creation provisions operating accounts per currency, including pool, MoMo clearing, bank clearing, cash clearing, payout clearing, suspense, tenant fee revenue, and FWallet commission accounts.
Create scoped integration keys.

Tenant admins can create keys from the dashboard Developers area or with POST /v1/developer/api-keys. Production keys should be scoped to the smallest resource set possible and should require request signing for server-to-server money movement.
Invite the operating team.

Add team members with roles that match the workflows they perform. Do not share one admin account across finance, developer, and approver users.

Team Roles

The tenant team API accepts these roles:

Role	Intended permissions
`org-admin`	Full tenant administration, including team, developer, fees, treasury, and approvals.
`operator`	Day-to-day wallet, deposit, payout, and reconciliation work.
`approver`	Maker-checker approval for payouts and tenant withdrawals.
`developer`	API apps, API keys, request logs, and integration debugging.
`finance-viewer`	Read-only finance, ledger, fee, payout, and reconciliation views.
`observer`	Read-only operational monitoring.
`user`	Basic tenant user account with no administrative assumptions.

Create team members with a tenant-scoped key that includes team:manage:

curl -X POST https://api.fwallet.co.ug/v1/team \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TENANT_ADMIN_KEY" \
  -d '{
    "name": "Daniel Approver",
    "email": "daniel@example.com",
    "password": "change-me-after-invite",
    "orgRole": "approver"
  }'

Fee Schedules

Fee schedules are tenant-scoped. Each schedule can contain multiple rules that match by transaction type, currency, amount band, flat fee, percentage fee, min fee, and max fee.

Super admins can set the platform commission share on system fee schedules with platformCommissionBps. Tenant owners can manage tenant fee rules from /v1/admin/fee-schedules. Published default schedules are used for deposits, transfers, payouts, and tenant fee analytics.

Example super-admin fee setup:

curl -X POST https://api.fwallet.co.ug/v1/system/organizations/$TENANT_ID/fee-schedules \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{
    "name": "UGX production fees",
    "isDefault": false,
    "platformCommissionBps": 1000
  }'

curl -X POST https://api.fwallet.co.ug/v1/system/organizations/$TENANT_ID/fee-schedules/$SCHEDULE_ID/rules \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{
    "transactionType": "payout",
    "currencyCode": "UGX",
    "flatFee": 500,
    "percentageFee": 150,
    "minFee": 500,
    "maxFee": 10000
  }'

curl -X POST https://api.fwallet.co.ug/v1/system/organizations/$TENANT_ID/fee-schedules/$SCHEDULE_ID/publish \
  -H "Content-Type: application/json" \
  -H "X-System-Key: $SYSTEM_KEY" \
  -d '{ "makeDefault": true }'

Tenant Float Deposits

Tenant float is operating money the tenant deposits into the platform for downstream wallet operations. Record tenant float with POST /v1/admin/money/float-deposits.

curl -X POST https://api.fwallet.co.ug/v1/admin/money/float-deposits \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TENANT_ADMIN_KEY" \
  -H "Idempotency-Key: tenant-float-20260426-001" \
  -d '{
    "amount": 5000000,
    "currencyCode": "UGX",
    "rail": "momo",
    "externalReference": "MTN-DEP-20260426-001",
    "depositedBy": "finance-ops-001",
    "note": "Initial operating float"
  }'

The ledger records:

DR asset:pool:UGX
CR asset:momo-clearing:UGX

Use GET /v1/admin/money/balances to show operating float, tenant fee revenue, FWallet commission, suspense, and payout clearing balances by currency.

Tenant Fee Withdrawals

Tenants can withdraw earned fee revenue or operating float through a maker-checker flow.

The requester calls POST /v1/admin/money/withdrawals.
FWallet moves the requested amount into suspense.
A different approver calls POST /v1/admin/money/withdrawals/{caseId}/approve.
Approved funds settle into payout clearing for delivery through MoMo, bank, cash, or another payout rail.
Rejected cases reverse the hold back to the original source account.

curl -X POST https://api.fwallet.co.ug/v1/admin/money/withdrawals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TENANT_ADMIN_KEY" \
  -H "Idempotency-Key: tenant-fee-withdrawal-001" \
  -d '{
    "source": "tenant_fees",
    "amount": 200000,
    "currencyCode": "UGX",
    "payoutMethod": "momo",
    "requestedBy": "finance-user-001",
    "destination": {
      "phoneNumber": "+256700100001",
      "network": "MTN"
    }
  }'

curl -X POST https://api.fwallet.co.ug/v1/admin/money/withdrawals/$CASE_ID/approve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TENANT_APPROVER_KEY" \
  -d '{ "actorId": "finance-approver-001" }'

User Payout Lifecycle

User payouts use the same maker-checker pattern:

Step	Endpoint	Ledger behavior
Request	`POST /v1/payouts`	Holds wallet funds and fee in suspense.
List cases	`GET /v1/payouts/cases?status=pending`	Shows pending approval cases.
Approve	`POST /v1/payouts/{caseId}/approve`	Settles suspense into payout clearing.
Reject	`POST /v1/payouts/{caseId}/reject`	Posts a reversing entry back to the wallet.

Every payout request must include an Idempotency-Key, and the approver’s actorId must differ from the requestedBy value.

Request Signing

Production server-to-server integrations should use HMAC keys. Create them with:

{
  "name": "Striker Market backend",
  "authMode": "hmac",
  "scopes": ["wallets:read", "wallets:create", "transfers:create", "payouts:create", "request_logs:read"],
  "environment": "live",
  "restrictions": {
    "requireRequestSigning": true,
    "requireActorHeaders": true
  }
}

Signed requests include X-FWallet-Key-Id, X-FWallet-Timestamp, X-FWallet-Nonce, X-FWallet-Content-SHA256, and X-FWallet-Signature. See Request Signing for the canonical request format and code examples.

Reconciliation

FWallet reconciliation starts from the ledger and compares it with external rail evidence:

Flow	Evidence	What to compare
MoMo deposits	Provider webhook or settlement export	External transaction ID, phone number, amount, currency, timestamp, wallet credit journal entry.
Bank deposits	Uploaded bank statement or verified slip	Bank reference, account, amount, currency, verification user, pool or wallet credit.
Payouts	Provider disbursement report	Approval case ID, payout clearing movement, provider payout reference, final status.
Tenant float	Deposit receipt, MoMo reference, bank statement, or cash receipt	`tenant_float_deposit` journal entry, clearing rail, `externalReference`, operator.
Tenant fee withdrawals	Approval case and payout rail evidence	Suspense hold, approval action, payout clearing settlement, destination.

Use tenant analytics, request logs, audit events, and journal queries together:

GET /v1/admin/analytics for tenant fee revenue, volume, liquidity, pending payouts, and request errors.
GET /v1/developer/request-logs for API caller, signature, idempotency, status, and correlation IDs.
GET /v1/team/audit-events for team and approval audit trails.
GET /v1/journal and GET /v1/journal/{id} for immutable ledger entries and lines.

Demo Checklist

To reproduce the enterprise demo:

Create or select a tenant from the super-admin dashboard.
Configure at least one published default fee schedule.
Invite an org-admin, operator, approver, developer, and observer.
Create an HMAC key for the sample app and a read-only observer key.
Deposit tenant float from the Treasury view or POST /v1/admin/money/float-deposits.
Create user wallets, run deposits, transfers, and payout requests.
Approve or reject payout and tenant withdrawal cases with a different actor.
Review tenant analytics, request logs, audit events, and journal lines.