Deposits

Deposits are how money enters the FWallet system. There are two deposit methods, each designed for a different real-world funding channel common in East African markets.

Deposit Methods

Method	Source	Verification	Credit Timing
MoMo (Mobile Money)	MTN MoMo, Airtel Money, etc.	Webhook signature	Automatic (immediate)
Bank Slip	Bank transfer	Branch manager verifies against imported statement	Manual (after verification)

MoMo Deposits

Mobile money is the dominant payment method in Uganda, Kenya, and Tanzania. FWallet integrates with MoMo providers via webhooks.

Flow

1. User sends money from their MoMo wallet to the platform’s MoMo number
2. Provider sends webhook to FWallet with transaction details and a cryptographic signature
3. FWallet verifies the signature to ensure the webhook is authentic
4. Idempotency check — if this transactionId has already been processed, return the existing result (no double-credit)
5. Risk check — verify the amount and currency are within tenant limits
6. Ledger credit — post a journal entry crediting the user’s wallet and debiting the MoMo float account

API Call

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": "hmac-sha256-signature-here",
    "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"
}

Note

The amount in the response is returned as a string ("500000", not 500000). All monetary amounts in API responses are strings to prevent JSON number precision loss. See Money Representation for details.

Ledger Entries

A MoMo deposit of 500,000 UGX produces:

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

• The debit to momo-float records that money has entered the system from an external MoMo provider. This account’s balance represents total MoMo funds the platform holds.
• The credit to the user’s wallet increases their available balance.

Idempotency

MoMo providers sometimes retry webhook deliveries. FWallet uses the transactionId field as an idempotency key. If a deposit with the same transactionId has already been processed, the API returns the existing deposit record without creating a duplicate ledger entry.

Bank Slip Deposits

In markets where mobile money is not available or for larger amounts, users deposit at a bank and present a receipt (slip) at a branch. This flow requires human verification.

Flow

1. Import bank statements — The platform regularly imports bank statements (CSV or API) that list all incoming transfers
2. User presents slip — A user visits a branch and shows their bank deposit receipt
3. Branch manager verifies — The branch manager searches imported bank data for a matching transaction (amount, date, reference)
4. Credit if match — If a match is found, the branch manager approves the deposit, which posts a journal entry

Ledger Entries

A verified bank deposit of 1,000,000 UGX produces:

DR  bank-float:ug-stanbic  1,000,000 UGX   (external funds received via bank)
CR  wallet:user-001         1,000,000 UGX   (user balance increased)

Why Two Steps?

Bank transfers are not real-time and do not have webhook infrastructure in most East African markets. The two-step flow (import statement, then verify slip) provides:

• Fraud prevention — A user cannot claim a deposit that does not appear on the bank statement
• Reconciliation — The imported statement serves as the external record for reconciliation
• Audit trail — The branch manager’s approval is recorded, creating accountability

Deposit States

State	Description
completed	Funds have been credited to the wallet. Ledger entry is posted.
pending	Bank slip has been submitted but not yet verified.
rejected	Bank slip verification failed (no matching statement entry).

MoMo deposits go directly to completed (or are rejected at the signature verification step). Bank slip deposits start as pending and move to completed or rejected after branch manager review.

Reconciliation

Both deposit methods create clear reconciliation paths:

• MoMo: Compare momo-float account balance against MoMo provider settlement reports
• Bank: Compare bank-float account balance against bank statements

If the float account balance matches the external records, all deposits are accounted for.