# Suspense & Reconciliation

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

URL: https://docs.shiwake.app/docs/banking/suspense











**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.

{/*
  IMAGE PROMPT (what suspense is: the parking tray):
  "A clean, minimal flat-design illustration of a financial 'suspense' account
  as a labeled parking tray. Center: a tray/inbox labeled 'SUSPENSE' holding a
  few money envelopes, each stamped with a question mark to show the recipient is
  unknown. On the left, arrows flow IN from three small source icons labeled
  'bank transfer', 'mobile money', 'bulk deposit'. On the right, two arrows flow
  OUT: one to a wallet icon labeled 'matched', one back to a bank icon labeled
  'refunded'. Convey 'temporary holding, always accounted for'. Thin line work,
  indigo accent, soft neutral #f8f9fb background, generous whitespace, developer-
  documentation aesthetic, 16:9."
  */}

<img alt="Suspense is a parking tray for inbound money that has no clear owner yet" src="__img0" />

Suspense lifecycle [#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 [#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.

{/*
  IMAGE PROMPT (suspense lifecycle state machine):
  "A minimal flat-design state diagram of a suspense item's lifecycle. Three
  labeled state nodes: 'Unresolved' (center-left, highlighted as the starting
  state), 'Matched' (top-right, green accent), 'Refunded' (bottom-right, muted
  amber accent). Arrows: 'CREATE' points into Unresolved; from Unresolved a
  'MATCH → to wallet' arrow goes to Matched, and a 'REFUND → to source' arrow
  goes to Refunded. Both Matched and Refunded are terminal (small lock icon).
  Under each transition, a tiny debit/credit tag: create = 'Dr FLOAT / Cr
  SUSPENSE', match = 'Dr SUSPENSE / Cr WALLET', refund = 'Dr SUSPENSE / Cr
  FLOAT'. Thin line work, indigo primary with small green + amber accents,
  neutral #f8f9fb background, documentation illustration style, 16:9."
  */}

<img alt="The suspense lifecycle: Unresolved, then either Matched to a wallet or Refunded to source" src="__img1" />

A real-life walkthrough [#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:

```bash
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:

```bash
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: &#x2A;*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:

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

Ledger: &#x2A;*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`.

<Callout type="info">
  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.
</Callout>

{/*
  IMAGE PROMPT (the Monday-morning timeline):
  "A minimal flat-design horizontal timeline illustration titled 'A morning of
  suspense'. Three time-stamped events along a single horizontal line:
  '8:02 AM: bank transfer, no reference' with an envelope dropping into a
  SUSPENSE tray; '10:30 AM: parent identified' with an arrow from the tray to a
  wallet labeled 'Ama'; '11:15 AM: not ours' with an arrow from the tray back to
  a bank labeled 'refund'. A running side note shows the SUSPENSE balance going
  0 → 75000 → 0, then 20000 → 0. Warm but clean, thin line work, indigo accent
  with small green (matched) and amber (refunded) touches, neutral #f8f9fb
  background, documentation illustration style, 16:9."
  */}

<img alt="A morning of suspense: park an unattributed transfer, match it once the parent is found, refund the one that wasn't yours" src="__img2" />

The SuspenseItem object [#the-suspenseitem-object]

```json
{
  "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
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Suspense item identifier&#x22; },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  channel: { type: &#x22;string&#x22;, required: true, description: <>How the money arrived (e.g. <code>&#x22;bank_transfer&#x22;</code>)</> },
  externalReference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Upstream reference for investigation&#x22; },
  status: { type: &#x22;string&#x22;, required: true, description: <><code>Unresolved</code>, <code>Matched</code>, <code>Refunded</code></> },
  resolvedBy: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Who resolved it&#x22; },
  resolution: { type: &#x22;string | null&#x22;, required: true, description: <><code>&#x22;matched_to_wallet&#x22;</code> or <code>&#x22;refunded_to_source&#x22;</code></> },
  matchedWalletId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;The wallet it was matched to&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Raw upstream payload for investigation&#x22; },
}"
/>

***

Create a suspense item [#create-a-suspense-item]

<Endpoint method="POST" path="/api/v1/banking/suspense" />

Request body [#request-body]

<TypeTable
  type="{
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code&#x22; },
  channel: { type: &#x22;string&#x22;, required: true, description: &#x22;How the money arrived&#x22; },
  externalReference: { type: &#x22;string&#x22;, description: &#x22;Upstream reference&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Raw payload for investigation&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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" }
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "sus_01HZ...",
        "amount": 75000,
        "currency": "GHS",
        "channel": "bank_transfer",
        "externalReference": "BANK-REF-12345",
        "status": "Unresolved",
        "journalEntryId": "jen_01HZ...",
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

Match to a wallet [#match-to-a-wallet]

<Endpoint method="POST" path="/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 [#request-body-1]

<TypeTable
  type="{
  walletId: { type: &#x22;string&#x22;, required: true, description: &#x22;Target wallet&#x22; },
  resolvedBy: { type: &#x22;string&#x22;, description: &#x22;Who performed the match&#x22; },
}"
/>

```bash
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 [#status-codes]

| Code  | When                              |
| ----- | --------------------------------- |
| `200` | Matched to wallet                 |
| `404` | Suspense item or wallet not found |
| `409` | Already matched or refunded       |

***

Refund to source [#refund-to-source]

<Endpoint method="POST" path="/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 [#request-body-2]

<TypeTable
  type="{
  resolvedBy: { type: &#x22;string&#x22;, description: &#x22;Who initiated the refund&#x22; },
}"
/>

```bash
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 [#list-suspense-items]

<Endpoint method="GET" path="/api/v1/banking/suspense" />

<TypeTable
  type="{
  status: { type: &#x22;string&#x22;, description: <><code>Unresolved</code>, <code>Matched</code>, <code>Refunded</code></> },
  channel: { type: &#x22;string&#x22;, description: &#x22;Filter by channel&#x22; },
  take: { type: &#x22;int&#x22;, description: &#x22;Page size (default 100)&#x22; },
}"
/>

***

Reconciliation report [#reconciliation-report]

<Endpoint method="GET" path="/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.

```json
{
  "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 [#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: &#x2A;*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.

<Callout type="warn">
  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.
</Callout>

{/*
  IMAGE PROMPT (daily reconciliation: two columns matching up):
  "A minimal flat-design illustration of daily reconciliation as a side-by-side
  comparison. Left column labeled 'Provider settlements' with three stacked rows:
  Paystack, MoMo, Bank, each showing an amount. Right column labeled 'Our ledger'
  with matching rows. Green equals-signs connect the rows that match; one row has
  a red 'not-equal' marker with a small callout pointing to a 'SUSPENSE:
  unresolved' chip at the bottom explaining the gap. Bottom banner reads 'gap =
  unresolved suspense'. Thin line work, indigo accent with green (match) and red
  (mismatch) touches, neutral #f8f9fb background, clean tabular feel, developer-
  documentation aesthetic, 16:9."
  */}

<img alt="Daily reconciliation: line up provider settlements against your ledger; the gap should equal unresolved suspense" src="__img3" />
