ShiwakeDocs

Suspense & Reconciliation

Handle unattributed inbound funds and generate daily channel-based reconciliation reports.

Suspense is a holding area for money that has arrived but cannot yet be attributed to a specific wallet. Common scenarios:

  • A bank transfer arrives with a reference that doesn't match any known user
  • A mobile money notification lands before the user's account is set up
  • A bulk deposit needs manual investigation to split across wallets

Think of it as the tray by the mailroom door where the mail clerk drops every envelope with no clear recipient. The money is safely inside the building and counted. It just hasn't reached the right desk yet. Suspense keeps those funds on the books (so they can never be "lost") until someone figures out where they belong.

Suspense is a parking tray for inbound money that has no clear owner yet

Suspense lifecycle

CREATE  →  Unresolved   (money parked in SUSPENSE account)
             ↓
MATCH   →  Matched      (money moved from SUSPENSE to wallet)
   or
REFUND  →  Refunded     (money moved from SUSPENSE back to PLATFORM-FLOAT)

Accounting

ActionDebitCredit
CreatePLATFORM-FLOAT-{CCY}SUSPENSE-{CCY}
MatchSUSPENSE-{CCY}CLIENT-{ownerId}
RefundSUSPENSE-{CCY}PLATFORM-FLOAT-{CCY}

Each action produces a balanced journal entry in the core ledger.

The suspense lifecycle: Unresolved, then either Matched to a wallet or Refunded to source

A real-life walkthrough

Picture a school-fees platform on a Monday morning. Parents pay their children's fees by bank transfer and mobile money, and each payment is supposed to carry the student's ID as a reference so it lands in the right wallet automatically. Reality is messier.

8:02 AM: a bank transfer arrives with a useless reference. GCB Bank settles GHS 750.00 into the platform's collection account. The reference field just reads "SCHOOL FEES", no student ID. Your reconciliation service can't tell whose wallet to credit, but the money is real and already in your bank. So it parks it in suspense:

curl -X POST ".../api/v1/banking/suspense" \
  -H "X-Api-Key: sk_live_..." \
  -d '{
    "amount": 75000,
    "currency": "GHS",
    "channel": "bank_transfer",
    "externalReference": "GCB-TXN-88421",
    "metadata": { "senderName": "KWAME ASANTE", "narration": "SCHOOL FEES" }
  }'

The ledger records debit PLATFORM-FLOAT-GHS 75000, credit SUSPENSE-GHS 75000. The money is on the books and provably safe. It just isn't in any student's wallet yet. Status: Unresolved.

10:30 AM: the parent calls the office. "I paid Ama's fees this morning, my name is Kwame Asante." Ops opens the unresolved suspense list, sees the KWAME ASANTE item, matches it to Ama's wallet, and the money moves out of suspense:

curl -X POST ".../api/v1/banking/suspense/sus_01HZ.../match" \
  -H "X-Api-Key: sk_live_..." \
  -d '{ "walletId": "wal_ama_...", "resolvedBy": "ops-admin@school.com" }'

Ledger: debit SUSPENSE-GHS 75000, credit CLIENT-ama 75000. Ama's wallet is now funded and her fees can settle. Suspense is back to empty for that item. Status: Matched.

11:15 AM: a payment that isn't yours. Another GHS 200.00 lands from a sender no one recognizes, with a phone number that matches no parent. After investigation, ops concludes it was sent to the wrong institution entirely. Rather than guess, they refund it to source:

curl -X POST ".../api/v1/banking/suspense/sus_02HZ.../refund" \
  -H "X-Api-Key: sk_live_..." \
  -d '{ "resolvedBy": "ops-admin@school.com" }'

Ledger: debit SUSPENSE-GHS 20000, credit PLATFORM-FLOAT-GHS 20000. The money returns to the float; your app then triggers the actual payout back to the sender through your provider. Status: Refunded.

Notice what suspense bought you: at no point was money invented, destroyed, or sitting in a variable somewhere. Every mystery payment was on the ledger from the second it arrived, and every resolution was a balanced journal entry. When you reconcile against GCB's statement at the end of the day, the GHS 950.00 that hit your bank is fully accounted for: 750 matched, 200 refunded, 0 unexplained.

A morning of suspense: park an unattributed transfer, match it once the parent is found, refund the one that wasn't yours

The SuspenseItem object

{
  "id": "sus_01HZ...",
  "amount": 75000,
  "currency": "GHS",
  "channel": "bank_transfer",
  "externalReference": "BANK-REF-12345",
  "journalEntryId": "jen_01HZ...",
  "resolutionJournalEntryId": null,
  "status": "Unresolved",
  "resolvedAt": null,
  "resolvedBy": null,
  "resolution": null,
  "matchedWalletId": null,
  "metadata": { "bankName": "GCB", "senderName": "KWAME ASANTE" },
  "createdAt": "2026-04-07T12:00:00Z",
  "updatedAt": null
}

Prop

Type


Create a suspense item

POST/api/v1/banking/suspense

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/suspense" \
  -H "X-Api-Key: sk_live_..." \
  -H "X-Created-By: reconciliation-service" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 75000,
    "currency": "GHS",
    "channel": "bank_transfer",
    "externalReference": "BANK-REF-12345",
    "metadata": { "bankName": "GCB", "senderName": "KWAME ASANTE" }
  }'

Match to a wallet

POST/api/v1/banking/suspense/{id}/match

Attributes the suspense funds to a wallet. The full amount is credited to the wallet's account.

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/suspense/sus_01HZ.../match" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "wal_01HZ...",
    "resolvedBy": "ops-admin@example.com"
  }'

Status codes

CodeWhen
200Matched to wallet
404Suspense item or wallet not found
409Already matched or refunded

Refund to source

POST/api/v1/banking/suspense/{id}/refund

Returns the funds to the platform float. Your application handles the actual refund to the sender via the upstream provider.

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/banking/suspense/sus_01HZ.../refund" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolvedBy": "ops-admin@example.com" }'

List suspense items

GET/api/v1/banking/suspense

Prop

Type


Reconciliation report

GET/api/v1/banking/reconciliation?date=2026-04-07&currency=GHS

Returns a daily summary of completed banking transactions grouped by channel, plus the current unresolved suspense total.

{
  "code": 200,
  "data": {
    "reportDate": "2026-04-07",
    "currency": "GHS",
    "channels": [
      {
        "channel": "paystack",
        "reportDate": "2026-04-07",
        "depositTotal": 5000000,
        "depositCount": 42,
        "withdrawalTotal": 1500000,
        "withdrawalCount": 15,
        "netFlow": 3500000,
        "currency": "GHS"
      },
      {
        "channel": "momo",
        "reportDate": "2026-04-07",
        "depositTotal": 2000000,
        "depositCount": 120,
        "withdrawalTotal": 800000,
        "withdrawalCount": 35,
        "netFlow": 1200000,
        "currency": "GHS"
      }
    ],
    "totalDeposits": 7000000,
    "totalWithdrawals": 2300000,
    "netFlow": 4700000,
    "unresolvedSuspenseCount": 3,
    "unresolvedSuspenseTotal": 225000
  }
}

Use this to compare against your payment provider's settlement reports. If the totals don't match, investigate the unresolved suspense items.

How ops actually uses this each day

Back to the school. At close of business the finance officer pulls this report for the day and lays it next to the settlement statements from Paystack, the MoMo provider, and GCB Bank. The job is one question: does the money we recorded match the money that actually moved?

  • channels totals should line up with each provider's own settlement figure. If Paystack says they settled GHS 50,000 but your paystack depositTotal reads GHS 48,500, something is missing: a webhook that never arrived, or a payment still stuck in suspense.
  • unresolvedSuspenseTotal is the size of the "we don't know yet" pile. On a healthy day it trends to zero as ops matches items. A number that keeps growing means references are consistently bad and worth fixing upstream (e.g. making the student ID a required field on the parent portal).
  • The gap between your provider's total and your recorded deposits should be exactly explained by the unresolved suspense total. If it isn't, that difference is the thing to chase.

The single most useful daily number is unresolvedSuspenseTotal. It's the money that has entered your world but hasn't reached a wallet. Zero is the goal; a persistent non-zero figure is your early-warning signal that something upstream is dropping references.

Daily reconciliation: line up provider settlements against your ledger; the gap should equal unresolved suspense

Edit on GitHub

Last updated on

On this page