Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview
On this page

Daily statements

Download one day of your wallets, with opening and closing balances, as JSON or CSV.

GET /v1/statements?date=2026-10-05&format=json

The day is the Africa/Accra calendar day, which is UTC with no daylight saving: from 00:00 UTC on the date to 00:00 UTC the next day.

Ask for a statement

Parameter Meaning
date Required. The day, as YYYY-MM-DD.
walletId Only this wallet. Use the id from GET /v1/sub-accounts. Without it, every wallet of your business.
format json (the default) or csv. Accept: text/csv also asks for CSV.

A date in the future, or more than 366 days back, is 400. A day is ready five minutes after it ends. Ask sooner and you get 409 statement_not_ready, with the time it will be ready in message.

The JSON

{
  "date": "2026-10-05",
  "businessId": "6f1c2f0e-8f6e-4a54-9a3b-0f1d6a3c7b11",
  "wallets": [
    {
      "walletId": "11111111-1111-4111-8111-111111111111",
      "name": "Main",
      "currency": "GHS",
      "opening": { "available": "1000.00", "reserved": "50.00" },
      "closing": { "available": "1079.00", "reserved": "30.00" },
      "reconciled": true,
      "lines": [
        {
          "reference": "inv-1",
          "id": "txn_8d2f4a1c",
          "walletId": "11111111-1111-4111-8111-111111111111",
          "type": "collection",
          "direction": "in",
          "currency": "GHS",
          "amount": "120.00",
          "fee": "1.50",
          "feeBearer": "initiator",
          "status": "settled",
          "counterparty": { "type": "msisdn", "value": "233241234567", "provider": "mtn" },
          "createdAt": "2026-10-05T09:00:00Z"
        }
      ]
    }
  ]
}

The values above only show the shape. Amounts are decimal strings in major units. There is one entry for each wallet and currency, the primary wallet first.

  • opening and closing are the wallet’s balances just before the day starts and just before it ends. reserved is money held back, such as a payout in progress or an escrow hold. The closing balance of one day is the opening balance of the next.
  • A wallet that was closed before the day, or opened after it, is left out when you do not pass walletId.

Lines

Lines come oldest first. Each has:

Field Meaning
reference Yours. For a hold another business placed for you, that business chose it.
id The platform’s ID. Quote it to support. Absent on a hold you placed.
walletId The wallet this section is for.
type collection, payout, settlement, utility, wallet_transfer, wallet_move or hold.
direction in for money received, out for money sent, from this wallet’s side.
amount, fee, feeBearer As on transactions. feeBearer is initiator when the fee is on top of the amount and non_initiator when it comes out of it.
status The status as it stands now.
counterparty The other party. See Who was on the other side.
createdAt When the transaction was created, or when the hold changed status.

Holds

Each time an escrow hold is placed, paid out or returned, it is a line of its own with type hold and the status it took: held, paid_out or returned. A hold line also carries:

Field Meaning
beneficiary On a hold you placed: {type, walletId} for a sub-account, {type, businessName} for a business, or {type, provider, destination, accountName} for a mobile money number or bank account.
decidedBy Who decided it: payer, beneficiary, expiry or ismartpay.

A hold paid out to one of your own sub-accounts also shows as an in line in that wallet’s section. A hold another business paid out to you shows as an in line in the wallet it landed in. See Escrow holds.

Hold lines come from your webhook events, which are kept for 90 days. For an older day a hold line can be missing.

Does it add up

reconciled tells you whether the day’s lines explain the change in the wallet. It is checked for each wallet and currency in exact amounts: the opening balance, plus what the settled lines moved, equals the closing balance. Available and reserved are counted together, because money held for a payout or a hold is still in the wallet.

  • A collection or transfer in adds its amount, less the fee when feeBearer is non_initiator.
  • A payout or transfer out takes its amount, plus the fee when feeBearer is initiator.
  • A hold you placed takes its amount out when it is paid out. Held and returned hold lines change nothing.
  • A hold for a mobile money number or bank account takes its totalHeld out when its first payout starts (paying_out). If it is later returned, that line puts totalHeld back. Retries and the final paid_out change nothing.
  • A hold paid out to you adds its amount.
  • Lines that have not settled, or failed, change nothing.

When it does not add up you still get the statement, with reconciled false and a difference: the closing total minus what the opening and the lines explain. A negative difference means the lines add up to more than the wallet shows. The usual cause is a payment that started late on one day and settled on the next, which shows a difference on both days. Look at the lines near midnight first.

CSV

format=csv gives one header row and then, for each wallet and currency, an opening row, its line rows and a closing row.

wallet_id,wallet_name,currency,row,time,reference,id,type,direction,amount,fee,fee_bearer,status,counterparty_type,counterparty,beneficiary,decided_by,available,reserved,reconciled,difference

The row column says which kind it is. Balances are on the opening and closing rows, and reconciled and difference are on the closing row. A text cell that starts with =, +, -, @, a tab or a carriage return gets a leading ', so a spreadsheet does not run it as a formula.

Test and live

Statements work the same way in the sandbox, so you can build your reconciliation against test data.

Limits

A statement holds at most 10,000 lines. Past that you get 422 statement_too_large. Ask for one wallet at a time with walletId.

Permissions

To The key needs
Read a statement transactions.read and wallets.read

A business only ever sees its own wallets. A walletId that is not yours is 404.

Errors

As well as the common errors:

Status Code What to do
400 invalid_input date is missing, malformed, in the future or too old, or format or walletId is not valid. Read message.
403 forbidden The key lacks wallets.read.
404 not_found The walletId is not one of your wallets.
409 statement_not_ready The day is not over yet. Read message for when to ask again.
422 statement_too_large Ask for one wallet at a time with walletId.

Was this page helpful?