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 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
| Action | Debit | Credit |
|---|---|---|
| Create | PLATFORM-FLOAT-{CCY} | SUSPENSE-{CCY} |
| Match | SUSPENSE-{CCY} | CLIENT-{ownerId} |
| Refund | SUSPENSE-{CCY} | PLATFORM-FLOAT-{CCY} |
Each action produces a balanced journal entry in the core ledger.

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.

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
/api/v1/banking/suspenseRequest 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
/api/v1/banking/suspense/{id}/matchAttributes 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
| Code | When |
|---|---|
200 | Matched to wallet |
404 | Suspense item or wallet not found |
409 | Already matched or refunded |
Refund to source
/api/v1/banking/suspense/{id}/refundReturns 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
/api/v1/banking/suspenseProp
Type
Reconciliation report
/api/v1/banking/reconciliation?date=2026-04-07¤cy=GHSReturns 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?
channelstotals should line up with each provider's own settlement figure. If Paystack says they settled GHS 50,000 but yourpaystackdepositTotalreads GHS 48,500, something is missing: a webhook that never arrived, or a payment still stuck in suspense.unresolvedSuspenseTotalis 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.

Last updated on