Skip to main content
View as Markdown

Balance transactions

Balance transactions are the itemized record of money added to or returned from your Inttegro balance. Each entry connects an amount to its order and payment or refund, giving finance and support teams a clear trail for reconciliation.

Use Balances to see current totals. Use balance transactions to explain those totals, trace money back to a sale or refund, and build exports for your accounting system.

The balance transaction object

Payment and refund balance transactions belong to an order. A payment transaction includes its paymentId; a refund transaction includes its refundId. A finalized payout debit includes payoutId and does not include an order.

amount.value is always a non-negative value in the currency's smallest unit. Check type to determine whether the entry records a payment, refund, or payout. Payment entries include all current allocations plus available, pending, and spent amount summaries. Released allocations are omitted.

Properties​

TypeScript SDK responseBalanceTransactionv12.0.0
  • amountAmountAmount of the payment or refund in the currency's smallest unit.Click or tap to expand
    • Name
      currency
      Type
      Currency
      Description
      Currency code for the transaction.
    • Name
      value
      Type
      number
      Description
      Non-negative amount in the currency’s smallest unit, such as pesewas for GHS.
  • Name
    allocations
    Type
    BalanceTransactionAllocation[]
    Description

    All current pending and completed allocations of this payment transaction. Each item includes a stable bta_... ID, a refund or payout discriminator, public status and timestamps, and a matching nested object containing the consumer ID and exact allocated amount. Omitted from refund transactions.

  • availableAmountAmountClick or tap to expand

    Amount still available for a refund or payout. It uses the same currency and integer minor-unit shape as amount. Present only on payment transactions.

  • Name
    availableAt
    Type
    Date
    Description

    When payment funds are scheduled to become eligible for payout. This can be a future timestamp. Omitted when the entry does not follow the payment availability lifecycle.

  • Name
    claimedAt
    Type
    Date
    Description

    Deprecated legacy whole-transaction payout timestamp. New integrations should inspect allocations.

  • Name
    createdAt
    Type
    Date
    Description

    When the balance transaction was recorded. Transaction pages are ordered by this timestamp from newest to oldest.

  • Name
    id
    Type
    string
    Description

    Unique balance transaction identifier with the bt_ prefix. Use it for lookup and as the reconciliation key in your own records.

  • Name
    orderId
    Type
    string
    Description

    Order associated with the source payment or refund. Omitted from payout debit transactions.

  • Name
    paidAt
    Type
    Date
    Description

    Deprecated legacy whole-transaction payout timestamp. New integrations should inspect completed allocations and their completed_at values.

  • Name
    paymentId
    Type
    string
    Description

    Payment that created the balance transaction. Present when type is

    Inttegro.BalanceTransactionTypes.Payment

    .

  • Name
    payoutId
    Type
    string
    Description

    Payout that created a finalized payout debit. On legacy payment transactions this can instead be the deprecated whole-transaction payout relationship; new integrations should inspect allocations on payment entries.

  • pendingAmountAmountClick or tap to expand

    Amount reserved by unresolved refund and payout allocations. Present only on payment transactions.

  • Name
    refundId
    Type
    string
    Description

    Refund that created the balance transaction. Present when type is

    Inttegro.BalanceTransactionTypes.Refund

    .

  • spentAmountAmountClick or tap to expand

    Amount permanently consumed by completed refund and payout allocations. Present only on payment transactions.

  • Name
    type
    Type
    BalanceTransactionType | 'payment' | BalanceTransactionType | 'refund' | BalanceTransactionType | 'payout'
    Required
    required
    Description

    Why the transaction exists: Inttegro.BalanceTransactionTypes.Payment or Inttegro.BalanceTransactionTypes.Refund or Inttegro.BalanceTransactionTypes.Payout.

POST/balance_transactions/lookup

Look up a balance transaction

Retrieve one balance transaction by its ID. Use this when you already have a bt_... identifier from an order, payout, dashboard, or previous list response and need the complete record.

Request attributes​

TypeScript SDK requestLookupBalanceTransactionRequestv12.0.0
  • Name
    transactionId
    Type
    string
    Required
    required
    Description

    Balance transaction ID returned by Inttegro, beginning with bt_.

Request

POST/balance_transactions/lookup
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.balanceTransactions.lookup({
  transactionId: "bt_0123456789abcdefghijklmnopqrstuvwxyzABCD",
})

Response

SDK versionv12.0.0
TransactionResponse {
  transaction: { … },
}
POST/balance_transactions/page

Page through balance transactions

Browse balance activity from newest to oldest. Start with page 1, then request later pages until the response contains no transactions.

Available through MCP

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

Request attributes​

TypeScript SDK requestPageBalanceTransactionsRequestv12.0.0
  • Name
    pageNumber
    Type
    number
    Required
    required
    Description

    1-based page number to retrieve. Supported pages are 1 through 10.

  • Name
    pageSize
    Type
    number
    Required
    required
    Description

    Maximum number of transactions to return. Minimum 1, maximum 256. The final page may contain fewer transactions.

Request

POST/balance_transactions/page
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.balanceTransactions.page({
  pageNumber: 1,
  pageSize: 2,
})

Response

SDK versionv12.0.0
PageResponse {
  page: { … },
}