Skip to main content
View as Markdown

Balances

The Balances API reports how funds are classified and how much is currently committed to payout or refund operations. Use it to power finance dashboards, plan payouts, and reconcile the funds collected through Inttegro.

The four root amount fields come from the latest completed transaction snapshot. balances.ghs.held is a live overlay showing funds committed to in-flight or unresolved payouts and refunds. It is not a fifth balance bucket.

The balance object

Balances are grouped by currency. Every amount is an integer in that currency's smallest unit, such as pesewas for GHS.

balances.ghs.available, balances.ghs.pending, balances.ghs.refund, and balances.ghs.reserved classify funds at the transaction snapshot cutoff. balances.ghs.held separately reports live operational commitments.

Properties​

TypeScript SDK responseBalanceSnapshotv12.0.0
  • ghsBalanceBreakdownLatest GHS snapshot. Amounts are expressed in pesewas.Click or tap to expand
    • Name
      available
      Type
      BalanceAmount
      View available attributesClick or tap to expand
      Funds classified as available by the latest completed transaction snapshot.
      • Name
        amount
        Type
        number
        Description
        Available amount in minor units (pesewas for GHS).
    • Name
      held
      Type
      Record<string, unknown>
      View held attributesClick or tap to expand
      Live operational commitments against the balance. Do not add this object to the four snapshot buckets.
      • Name
        asOf
        Type
        Date
        Description
        Time at which Inttegro successfully read the hold amounts. This is not the last time a hold changed.
      • Name
        payout
        Type
        Record<string, unknown>
        View payout attributesClick or tap to expand
        Funds committed to in-flight or unresolved payouts.
        • Name
          amount
          Type
          number
          Description
          Amount currently held for payouts, in pesewas.
      • Name
        refund
        Type
        Record<string, unknown>
        View refund attributesClick or tap to expand
        Funds committed to in-flight or unresolved refunds.
        • Name
          amount
          Type
          number
          Description
          Amount currently held for refunds, in pesewas.
    • Name
      includesTransactionsBefore
      Type
      Date
      Description
      Transaction cutoff for the snapshot classifications. Transactions created before this time are included; transactions at or after it are not.
    • Name
      pending
      Type
      BalanceAmount
      View pending attributesClick or tap to expand
      Funds recognized by the snapshot but not yet available, usually because they are still aging.
      • Name
        amount
        Type
        number
        Description
        Pending amount in pesewas.
    • Name
      refund
      Type
      BalanceAmount
      View refund attributesClick or tap to expand
      Funds intentionally earmarked for future refund obligations at the snapshot cutoff.
      • Name
        amount
        Type
        number
        Description
        Refund-earmarked amount in pesewas.
    • Name
      reserved
      Type
      BalanceAmount
      View reserved attributesClick or tap to expand
      Funds intentionally reserved for policy, risk, or remediation purposes at the snapshot cutoff.
      • Name
        amount
        Type
        number
        Description
        Policy-reserved amount in pesewas.
POST/balances

Retrieve your balance

Retrieve the latest GHS balance classifications and current operational holds. Read balances.ghs.held.payout.amount to see how much is committed to payouts and balances.ghs.held.refund.amount to see how much is committed to refunds.

A new account with no completed balance activity returns zero amounts. The response still includes both freshness timestamps.

Available through MCP

AI clients can use get_balances for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Request body​

Send an empty JSON object. No balance ID or other request attributes are needed.

Request

POST/balances
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.balances.get()

Response

SDK versionv12.0.0
BalanceResponse {
  balances: { … },
}