--- title: "Balance transactions" description: "Trace the payments and refunds behind your Inttegro balance." canonical: "https://studio.inttegro.com/api/balance-transactions" format: inttegro-machine-docs/v1 language: "Go" sdk_version: "v11.0.1" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/go/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 699 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: ["list_balance_transactions","get_balances"] estimated_tokens: 3902 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Trace the payments and refunds behind your Inttegro balance. This Go representation uses the selected SDK's native names wherever Studio has a verified mapping. ### Five questions #### Q1. Is Balance transactions the right source for this task? Use this reference for trace the payments and refunds behind your inttegro balance. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order. #### Q2. What is the first decision rule for reconcile a balance from the ledger, not from signed amounts? Treat [Balances](https://studio.inttegro.com/machine/go/api/balances.md) as the point-in-time total and this resource as the evidence behind it. Do not rebuild a current balance from a partial page of transactions. #### Q3. What is the second decision rule for reconcile a balance from the ledger, not from signed amounts? [`Transaction.Amount.Value`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction)is non-negative. Determine direction from[`Transaction.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction), then follow the order plus either the payment or refund identifier to verify the business event. #### Q4. What is the third decision rule for reconcile a balance from the ledger, not from signed amounts? On payment transactions, verify that `amount = available_amount + pending_amount + spent_amount`. Use each allocation's nested amount to explain how the transaction was consumed. #### Q5. What is the fourth decision rule for reconcile a balance from the ledger, not from signed amounts? For payout reconciliation, match a nested `payout.id` in[`Transaction.Allocations`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction)to the [Payout](https://studio.inttegro.com/machine/go/api/payouts.md), and retain both the `bt_...` and `bta_...` IDs for support investigations. ### Recommended MCP assistance Use these through an authenticated Inttegro MCP connection. This document remains the contract source. - [`list_balance_transactions`](https://studio.inttegro.com/machine/go/inttegro-mcp/tools.md#list_balance_transactions) — read; no mutation confirmation. Lists a bounded page of balance activity with related order and payment IDs, all current refund and payout allocations, and exact familiar-unit amount summaries. - [`get_balances`](https://studio.inttegro.com/machine/go/inttegro-mcp/tools.md#get_balances) — read; no mutation confirmation. Gets current balance snapshots by currency with exact familiar-unit amounts and supplemental machine-readable minor units. This tool cannot move funds. ## Document content # 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](https://studio.inttegro.com/machine/go/api/balances.md) 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. ## Reconcile a balance from the ledger, not from signed amounts The four decision rules are in the machine preamble above. ## The balance transaction object Payment and refund balance transactions belong to an order. A payment transaction includes its [`Transaction.PaymentID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction); a refund transaction includes its [`Transaction.RefundID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction). A finalized payout debit includes [`Transaction.PayoutID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) and does not include an order. [`Transaction.Amount.Value`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) is always a non-negative value in the currency's smallest unit. Check [`Transaction.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) 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 - [`Amount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) Amount of the payment or refund in the currency's smallest unit. - [`Amount.Currency`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` Currency code for the transaction. - [`Amount.Value`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `integer` Non-negative amount in the currency’s smallest unit, such as pesewas for GHS. - [`Allocations`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `array` 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. - [`AvailableAmount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `object` Amount still available for a refund or payout. It uses the same currency and integer minor-unit shape as [`Transaction.Amount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction). Present only on payment transactions. - [`AvailableAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `timestamp` 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. - [`ClaimedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `timestamp` Deprecated legacy whole-transaction payout timestamp. New integrations should inspect [`Transaction.Allocations`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction). - [`CreatedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `timestamp` When the balance transaction was recorded. Transaction pages are ordered by this timestamp from newest to oldest. - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` Unique balance transaction identifier with the `bt_` prefix. Use it for lookup and as the reconciliation key in your own records. - [`OrderID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` Order associated with the source payment or refund. Omitted from payout debit transactions. - [`PaidAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `timestamp` Deprecated legacy whole-transaction payout timestamp. New integrations should inspect completed allocations and their `completed_at` values. - [`PaymentID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` Payment that created the balance transaction. Present when [`Transaction.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) is [`balancetransaction.TypePayment`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#TypePayment). - [`PayoutID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` 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. - [`PendingAmount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `object` Amount reserved by unresolved refund and payout allocations. Present only on payment transactions. - [`RefundID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `string` Refund that created the balance transaction. Present when [`Transaction.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) is [`balancetransaction.TypeRefund`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#TypeRefund). - [`SpentAmount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `object` Amount permanently consumed by completed refund and payout allocations. Present only on payment transactions. - [`Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#BalanceTransaction) — `enum` — required Why the transaction exists: [`balancetransaction.TypePayment`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#TypePayment) or [`balancetransaction.TypeRefund`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#TypeRefund) or [`balancetransaction.TypePayout`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#TypePayout). ## 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 - `transaction_id` — `string` — required — wire-only Balance transaction ID returned by Inttegro, beginning with `bt_`. **Request — POST /balance\_transactions/lookup** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) result, err := client.BalanceTransactions.Lookup(ctx, "bt_0123456789abcdefghijklmnopqrstuvwxyzABCD") if err != nil { log.Fatal(err) } _ = result } ``` ```json { "transaction": { "amount": { "currency": "ghs", "value": 22000 }, "allocations": [ { "id": "bta_0123456789abcdefghijklmnopqrstuvwxyzABCD", "type": "payout", "status": "pending", "payout": { "id": "po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN", "amount": { "currency": "ghs", "value": 12000 } }, "created_at": "2025-04-17T10:00:00.000Z", "updated_at": "2025-04-17T10:00:00.000Z" } ], "available_amount": { "currency": "ghs", "value": 10000 }, "available_at": "2025-04-10T12:03:17.000Z", "created_at": "2025-04-10T12:02:45.000Z", "id": "bt_0123456789abcdefghijklmnopqrstuvwxyzABCD", "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD", "pending_amount": { "currency": "ghs", "value": 12000 }, "payment_id": "py_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn", "spent_amount": { "currency": "ghs", "value": 0 }, "type": "payment" } } ``` ## 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. > Mcp Endpoint Tools is interactive content. Use the canonical page to view it. ### Request attributes - [`PageNumber`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#PageParams.PageNumber) — `int` — required 1-based page number to retrieve. Supported pages are `1` through `10`. - [`PageSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/balancetransaction#PageParams.PageSize) — `int` — required Maximum number of transactions to return. Minimum `1`, maximum `256`. The final page may contain fewer transactions. **Request — POST /balance\_transactions/page** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/balancetransaction" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := balancetransaction.PageParams{ PageNumber: 1, PageSize: 2, } result, err := client.BalanceTransactions.Page(ctx, params) if err != nil { log.Fatal(err) } _ = result } ``` ```json { "page": { "number": 1, "size": 2, "transactions": [ { "amount": { "currency": "ghs", "value": 12200 }, "allocations": [ { "id": "bta_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn", "type": "payout", "status": "completed", "payout": { "id": "po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN", "amount": { "currency": "ghs", "value": 10000 } }, "created_at": "2025-04-18T09:59:45.000Z", "updated_at": "2025-04-18T10:00:15.000Z", "completed_at": "2025-04-18T10:00:15.000Z" } ], "available_amount": { "currency": "ghs", "value": 2200 }, "available_at": "2025-04-11T09:35:02.000Z", "created_at": "2025-04-11T09:34:40.000Z", "id": "bt_0123456789abcdefghijklmnopqrstuvwxyzABCD", "order_id": "or_0123456789abcdefghijklmnopqrstuvwxyzABCD", "pending_amount": { "currency": "ghs", "value": 0 }, "payment_id": "py_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn", "spent_amount": { "currency": "ghs", "value": 10000 }, "type": "payment" }, { "amount": { "currency": "ghs", "value": 8800 }, "created_at": "2025-04-10T21:17:05.000Z", "id": "bt_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn", "order_id": "or_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn", "refund_id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd", "type": "refund" } ] } } ```