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

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.

GET/v1/statements
Authorization
AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Query parameters
datestring<date>required

The day, as YYYY-MM-DD, in Africa/Accra time.

walletIdstring<uuid>

Only this wallet. Without it, every wallet of your business.

formatstring

json (the default) or csv. Accept: text/csv also asks for CSV.

Allowed:jsoncsv
Responses
200

The 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>required
businessIdstring<uuid>required
walletsStatementWallet[]required
Show properties
Array of StatementWallet
walletIdstring<uuid>required
namestringrequired

The wallet's label.

currencystringrequired
openingStatementBalancerequired
Show properties
availablestringrequired

What the wallet could spend, in major units.

reservedstringrequired

What was held back, for example a payout in progress or an escrow hold, in major units.

closingStatementBalancerequired
Show properties
availablestringrequired

What the wallet could spend, in major units.

reservedstringrequired

What was held back, for example a payout in progress or an escrow hold, in major units.

reconciledbooleanrequired

true when opening plus the settled lines equals closing, in available plus reserved.

differencestring

Only 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[]required

Oldest first.

Show properties
Array of StatementLine
referencestringrequired

Your reference, or for a hold another business placed for you, the one that business chose.

idstring

The platform's id. Absent on a hold you placed.

walletIdstring<uuid>required

The wallet of the section this line is in.

typestringrequired

collection, payout, settlement, utility, wallet_transfer, wallet_move or hold.

directionstring

in for money received, out for money sent, from this wallet's side.

Allowed:inout
currencystringrequired
amountstringrequired

In major units.

feestring

In major units. Absent when there is none.

feeBearerstring

initiator when the fee is on top of the amount, non_initiator when it comes out of it.

statusstringrequired

The status as it stands now. For a hold, held, paid_out or returned as of this line.

counterpartyCounterparty

The 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 properties
typestringrequired

msisdn, 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.

Allowed:msisdnaccountcardhandlebusinesswallet
valuestring

The phone number, account or card as recorded. Left out for a business. The wallet's id for a wallet.

providerstring

The provider that carried the money, when there was one.

namestring

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

beneficiaryHoldParty

On a hold you placed: who it is held for.

Show properties
typestring
Allowed:sub_accountbusinessexternal
walletIdstring<uuid>
businessNamestring

The business's display name, when known.

providerstring

On an external beneficiary.

destinationobject

On an external beneficiary.

Show properties
typestringrequired
Allowed:msisdnaccount
valuestringrequired

The mobile money number or bank account number.

accountNamestring

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

decidedBystring

On a hold: who decided it, payer, beneficiary, expiry or ismartpay.

createdAtstring<date-time>required

When the transaction was created, or when the hold changed status.

400

The request is not valid. message says which field.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

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.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

404

Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

409

statement_not_ready: the day has not ended yet, or ended less than five minutes ago. The message says when it is ready.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

422

statement_too_large: the statement has more than 10,000 lines. Ask for one wallet at a time with walletId.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

502

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.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

503

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.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

504

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.

errorobjectrequired
Show properties
codestringrequired

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

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request
curl -X GET 'https://stgdeveloper-api.ismartghana.com/v1/statements?date=2019-08-24' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "date": "2019-08-24",
  "businessId": "50092e54-cd12-4059-9828-e8c4ee9a3cf5",
  "wallets": [
    {
      "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
      "name": "string",
      "currency": "string",
      "opening": {
        "available": "string",
        "reserved": "string"
      },
      "closing": {
        "available": "string",
        "reserved": "string"
      },
      "reconciled": true,
      "difference": "string",
      "lines": [
        {
          "reference": "string",
          "id": "string",
          "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
          "type": "string",
          "direction": "in",
          "currency": "string",
          "amount": "string",
          "fee": "string",
          "feeBearer": "string",
          "status": "string",
          "counterparty": {
            "type": "msisdn",
            "value": "233241234567",
            "provider": "string",
            "name": "string"
          },
          "beneficiary": {
            "type": "sub_account",
            "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
            "businessName": "string",
            "provider": "string",
            "destination": {
              "type": "msisdn",
              "value": "string"
            },
            "accountName": "string"
          },
          "decidedBy": "string",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}