Read a daily statement
Returns the statement for one day, worked out when you ask. The day is the Africa/Accra calendar day, which is UTC with no daylight saving. For each wallet and currency it gives the opening and closing balance, every transaction of the day (collections, payouts, settlements, utility purchases, transfers and moves between your own wallets) and every hold placed, paid out or returned that day, with its beneficiary and who decided it. Without walletId it covers every wallet of your business, one section per wallet and currency. Ask for CSV with format=csv or Accept: text/csv; the default is JSON. Amounts are decimal strings in major units.
Opening and closing are the wallet’s balances just before the start and the end of the day. reconciled is true when the settled lines explain the change in the wallet’s total (available plus reserved) exactly. When they do not, the statement is still returned with reconciled false and the difference, which is the closing total minus what the opening and the lines add up to. A payment or payout that started on one day and settled on the next is a common cause.
A day is ready five minutes after it ends; before that the answer is 409 statement_not_ready. A future date, or a date more than 366 days back, is 400. A statement holds at most 10,000 lines (422 statement_too_large); ask for one wallet at a time. Hold lines are built from your webhook events, which are kept for 90 days. Requires the transactions.read and wallets.read permissions.
/v1/statementsAuthorizationBearer token (JWT) · headerrequiredA token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.
datestring<date>requiredThe day, as YYYY-MM-DD, in Africa/Accra time.
walletIdstring<uuid>Only this wallet. Without it, every wallet of your business.
formatstringjson (the default) or csv. Accept: text/csv also asks for CSV.
jsoncsvThe statement. A CSV has one header row, then for each wallet and currency an opening row, its line rows and a closing row that carries reconciled and difference.
datestring<date>requiredbusinessIdstring<uuid>requiredwalletsStatementWallet[]requiredShow propertiesHide properties
StatementWalletwalletIdstring<uuid>requirednamestringrequiredThe wallet's label.
currencystringrequiredopeningStatementBalancerequiredShow propertiesHide properties
availablestringrequiredWhat the wallet could spend, in major units.
reservedstringrequiredWhat was held back, for example a payout in progress or an escrow hold, in major units.
closingStatementBalancerequiredShow propertiesHide properties
availablestringrequiredWhat the wallet could spend, in major units.
reservedstringrequiredWhat was held back, for example a payout in progress or an escrow hold, in major units.
reconciledbooleanrequiredtrue when opening plus the settled lines equals closing, in available plus reserved.
differencestringOnly when reconciled is false: closing minus (opening plus the settled lines), in major units. Negative when the lines add up to more than the wallet shows.
linesStatementLine[]requiredOldest first.
Show propertiesHide properties
StatementLinereferencestringrequiredYour reference, or for a hold another business placed for you, the one that business chose.
idstringThe platform's id. Absent on a hold you placed.
walletIdstring<uuid>requiredThe wallet of the section this line is in.
typestringrequiredcollection, payout, settlement, utility, wallet_transfer, wallet_move or hold.
directionstringin for money received, out for money sent, from this wallet's side.
inoutcurrencystringrequiredamountstringrequiredIn major units.
feestringIn major units. Absent when there is none.
feeBearerstringinitiator when the fee is on top of the amount, non_initiator when it comes out of it.
statusstringrequiredThe status as it stands now. For a hold, held, paid_out or returned as of this line.
counterpartyCounterpartyThe other party: who paid you on money in, who you paid on money out. direction says which. Left out when the platform did not record one.
Show propertiesHide properties
typestringrequiredmsisdn, account or card for a mobile money wallet, bank account or card. handle for the iSmartPay handle that answered a payment request. business for another iSmartPay business on a wallet transfer. wallet for your own other wallet on a wallet_move.
msisdnaccountcardhandlebusinesswalletvaluestringThe phone number, account or card as recorded. Left out for a business. The wallet's id for a wallet.
providerstringThe provider that carried the money, when there was one.
namestringThe business's trading name, else its registered name, on a business, and left out when it is not known. The wallet's label on a wallet.
beneficiaryHoldPartyOn a hold you placed: who it is held for.
Show propertiesHide properties
typestringsub_accountbusinessexternalwalletIdstring<uuid>businessNamestringThe business's display name, when known.
providerstringOn an external beneficiary.
destinationobjectOn an external beneficiary.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
accountNamestringOn an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.
decidedBystringOn a hold: who decided it, payer, beneficiary, expiry or ismartpay.
createdAtstring<date-time>requiredWhen the transaction was created, or when the hold changed status.
The request is not valid. message says which field.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The token is missing, expired or not valid. Get a new one from the token endpoint.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
statement_not_ready: the day has not ended yet, or ended less than five minutes ago. The message says when it is ready.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
statement_too_large: the statement has more than 10,000 lines. Ask for one wallet at a time with walletId.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.