Payouts
Payouts move available funds from your Inttegro balance to a connected bank account or mobile money wallet. Schedule a transfer yourself or let Inttegro create payouts automatically, then follow each payout through completion. For the broader settlement model, see Payouts and Understand payouts.
The payout object
A payout records the destination, authorized amount, status, and balance transactions included in a transfer. Fields that depend on later processing are omitted until they have values.
Properties
- Name
balanceTransactions- Type
PayoutBalanceTransaction[]- Description
All source contribution objects. Each contains the balance transaction
id, its originalamount, and the exactallocated_amountselected for this payout. Itsstatusisreservedwhile the payout is open,completedafter success, orreleasedwhen the allocation is returned after failure or cancellation. Omitted until transactions are selected. The difference between the two amounts is not necessarily still available because other refunds or payouts can consume it.
- Name
balanceTransactionId- Type
string- Description
The payout's own immutable debit balance transaction. Present after the payout succeeds. This is distinct from
balanceTransactions, which lists the payment balance transactions that funded the payout.
- Name
canceledAt- Type
Date- Description
When the payout was canceled. Omitted otherwise.
customDataCustomDataClick or tap to expandYour string key-value metadata, when available.
- Name
destinationId- Type
string- Required
- required
- Description
Financial account selected as the destination.
errorPayoutErrorClick or tap to expandDeprecated compatibility view of a failed payout. Use
failurefor new integrations.- Name
executeAfter- Type
Date- Required
- required
- Description
Earliest time execution can begin.
- Name
executedBy- Type
string- Description
Actor that executed the payout, when available.
- Name
expectedAt- Type
Date- Description
Expected completion time, when available.
- Name
failedAt- Type
Date- Description
When the payout entered the
Inttegro.PayoutStatuses.Failedstate. Omitted otherwise.
failurePayoutFailureCaller-safe terminal failure information. Present only when status is failed.Click or tap to expand- Name
detail- Type
string- Description
- Safe explanation for an operator. Display or log it, but do not parse it.
- Name
reason- Type
PayoutFailureReason- Description
- Stable failure category. The possible values follow.
- Name
retryable- Type
boolean- Description
- Whether a newly created payout may succeed. Do not automatically repeat a payout solely because this value is true.
- Name
id- Type
string- Required
- required
- Description
Unique payout identifier.
- Name
initiatedAt- Type
Date- Required
- required
- Description
When the payout record was created.
- Name
initiatedBy- Type
string- Description
Actor that initiated the payout, when available.
- Name
reference- Type
string- Description
Your reconciliation reference, when provided.
- Name
scheduleId- Type
string- Description
Schedule associated with the payout, when available.
- Name
scheduledAt- Type
Date- Description
When the payout was scheduled, when available.
- Name
scheduledBy- Type
string- Description
Actor that scheduled the payout, when available.
- Name
sentAt- Type
Date- Description
When the transfer was sent, when available.
- Name
sourceId- Type
string- Description
Source identifier, when available.
- Name
status- Type
PayoutStatus- Required
- required
- Description
Current state:
Inttegro.PayoutStatuses.Initialized,Inttegro.PayoutStatuses.Scheduled,Inttegro.PayoutStatuses.Processing,Inttegro.PayoutStatuses.Executing,Inttegro.PayoutStatuses.Succeeded,Inttegro.PayoutStatuses.Failed, orInttegro.PayoutStatuses.Canceled.
- Name
succeededAt- Type
Date- Description
When the payout succeeded. Omitted otherwise.
Failure reason values
Inttegro.PayoutFailureReasons.ProviderDeclined— The provider declined the payout before it could be delivered.Inttegro.PayoutFailureReasons.DeliveryFailed— The transfer was sent for delivery but did not complete at the destination.Inttegro.PayoutFailureReasons.TemporarilyUnavailable— Payout processing was temporarily unavailable. Checkfailure.retryablebefore deciding whether to create a new payout.Inttegro.PayoutFailureReasons.Unknown— Inttegro could not safely classify the failure. Do not retry unless support advises you to.
maxAmount is a ceiling, not a guaranteed transfer amount.
The final payout can be lower when less money is available. For balance selection, refunds, and reconciliation examples, see How payouts use your balance.
Schedule a payout
Create a payout to a connected financial account. Omit executeAfter to begin as soon as possible, or provide a future time to delay the transfer.
The destination determines the payout currency. It must be active, able to receive funds, and cannot already have another payout in progress. The response includes a payout ID that you can use to check progress.
Request attributes
- Name
destinationId- Type
string- Required
- required
- Description
Financial account that receives the funds. Mobile money wallets and complete Ghana bank accounts are supported when push capability is enabled. Scheduling is rejected while another payout for this destination remains open.
- Name
executeAfter- Type
Date- Description
Earliest time Inttegro may begin the payout, as an ISO 8601 UTC timestamp. Omit it to begin as soon as possible.
- Name
maxAmount- Type
number- Description
Maximum amount you authorize, in the smallest currency unit. It must be at least 1 and cannot exceed your configured ceiling. If omitted, the configured ceiling is used. The final amount can be lower.
- Name
reference- Type
string- Required
- required
- Description
Your reference for matching the payout to your own records. It does not need to be unique.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.schedule({
destinationId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
reference: "PAYOUT-APR-15",
maxAmount: 250000,
executeAfter: new Date("2030-04-15T09:00:00Z"),
})
Response
- Object
- JSON
PayoutResponse {
payout: { … },
}
{
"payout": {
"id": "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
"destination_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
"reference": "PAYOUT-APR-15",
"status": "scheduled",
"max_amount": { "currency": "ghs", "value": 250000 },
"execute_after": "2030-04-15T09:00:00Z",
"scheduled_at": "2030-04-14T18:32:11.000Z",
"initiated_at": "2030-04-14T18:32:10.000Z"
}
}
Lookup a payout
Check a payout's current status and final transferred amount. Use this after scheduling or while reconciling a payout.
Optional lifecycle timestamps, failure, and balanceTransactions are omitted until they have values.
AI clients can use get_payout for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Request attributes
- Name
payoutId- Type
string- Required
- required
- Description
Payout ID returned when the payout was scheduled.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.lookup({
payoutId: "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
})
Response
- Object
- JSON
PayoutResponse {
payout: { … },
}
{
"payout": {
"id": "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
"destination_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
"max_amount": { "currency": "ghs", "value": 250000 },
"amount": { "currency": "ghs", "value": 240000 },
"status": "processing",
"execute_after": "2030-04-15T09:00:00.000Z",
"initiated_at": "2030-04-14T18:32:10.000Z",
"sent_at": "2030-04-15T09:01:05.000Z",
"balance_transactions": [ … ]
}
}
Cancel a payout
Stop a future payout before processing begins—for example, when the destination or amount ceiling is wrong.
Cancellation works only while the payout is Inttegro.PayoutStatuses.Scheduled and executeAfter is still in the future. The response returns the payout with status set to Inttegro.PayoutStatuses.Canceled and its canceledAt time.
Request attributes
- Name
payoutId- Type
string- Required
- required
- Description
ID of the scheduled payout to cancel.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.cancel({
payoutId: "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
})
Response
- Object
- JSON
PayoutResponse {
payout: { … },
}
{
"payout": {
"id": "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB",
"destination_id": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
"status": "canceled",
"initiated_by": "app",
"initiated_at": "2030-04-14T18:32:10.000Z",
"execute_after": "2030-04-15T09:00:00Z",
"scheduled_at": "2030-04-14T18:32:11.000Z",
"canceled_at": "2030-04-14T20:15:44.000Z",
"max_amount": { "currency": "ghs", "value": 250000 }
}
}
Get payout settings
See whether payouts are automatic or manual and which financial account receives GHS payouts. Send an empty JSON object; destinations is always present and can be empty.
If no schedule exists yet, Inttegro applies the default automatic schedule. Configure a destination before relying on automatic payouts. See Understand payout settings for the schedule fields.
AI clients can use get_payout_settings for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.settings()
Set payout destinations
Choose the financial account that receives your GHS payouts. Use this when you first set up settlements, switch the receiving account, or intentionally stop routing payouts to an account.
To remove the GHS destination, send an empty string for destinations.ghs. Omit that field to keep its existing value.
Rules
- The currently supported destination field is
"ghs"—see studio.inttegro.com/specs/currencies for supported currencies. - The financial account must be active, connected, and have push capability enabled.
- The financial account assigned to
"ghs"must be denominated in GHS. - Supported destinations are mobile money wallets and complete Ghana bank accounts.
Request attributes
destinationsPayoutDestinationsrequiredSupported payout destination assignments.Click or tap to expand- Name
ghs- Type
string- Description
- Financial account that receives Ghana cedi payouts. Pass an empty string to clear the assignment.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.setDestinations({
destinations: {
ghs: "fa_H3cNv7pQf9WbLt2mJs6yXrPq4Kz1Vd5G0aEiUo",
},
})
Disable automatic payouts
Switch to manual payouts. Inttegro stops creating new automatic payouts, but payouts that are already scheduled continue normally.
Your destinations do not change. You can still schedule a payout yourself or enable automatic payouts again later.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.disableAutomatic()
Enable automatic payouts
Resume automatic weekly payouts for eligible funds. Your existing destinations remain unchanged, so make sure GHS has a valid destination before enabling the schedule.
Payouts that are already scheduled continue normally.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.enableAutomatic()
Page through payouts
Browse payouts from newest to oldest. Use this for settlement history and reconciliation; use Lookup a payout when you already know the payout ID.
AI clients can use list_payouts for this operation. MCP read tools return minimized business data and do not change Inttegro state.
Request attributes
- Name
pageNumber- Type
number- Required
- required
- Description
1-based page index to fetch. Must be between 1 and 10 inclusive.
- Name
pageSize- Type
number- Description
Number of payouts per page (1–256). Defaults to 256 when omitted.
Response shape
The response contains number, the number of results in size, and a payouts array when the page is not empty. Every entry uses the payout object.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.payouts.page({
pageNumber: 1,
pageSize: 25,
})
Search payouts
Find payouts from remembered text or exact status and currency constraints. Results are discovery summaries; use the returned payout ID with Lookup a payout before cancellation, reconciliation, or any decision that depends on current transfer state.
Request attributes
- Name
cursor- Type
string- Description
Opaque continuation cursor returned by the previous page. Replay the same request and add this value for the next page.
facetsResourceSearchFacet[]Fields to group and count: currency or status.Click or tap to expandfiltersResourceSearchFilter[]Exact currency or status constraints.Click or tap to expand- Name
field- Type
string- Required
- required
- Description
- Route-local filter field.
- Name
operator- Type
ResourceSearchOperator- Required
- required
- Description
- eq for one value or in for any supplied value.
- Name
values- Type
string[]- Required
- required
- Description
- One value for eq; one through 20 values for in.
- Name
pageSize- Type
number- Description
Results per page, from
1through100. Defaults to20.
sortResourceSearchSortResult ordering.Click or tap to expand- Name
direction- Type
ResourceSearchSortDirection- Required
- required
- Description
- asc or desc. Relevance supports desc only.
- Name
field- Type
ResourceSearchSortField- Required
- required
- Description
- relevance or updated_at.
- Name
text- Type
string- Description
Search text, from 1 through 512 characters. Supply search text, exact filters, or both.
Response
Returns a typed search page with discovery summaries, requested facet
counts, page and total counts, an optional nextCursor,
and freshness metadata. Read the canonical payout before
acting on a result.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const request: Inttegro.ResourceSearchRequest = {
text: "po_abc123xyz",
}
const page = await inttegro.payouts.search(request)
Payout settings responses
Get payout settings returns the complete configuration. Endpoints that change payout settings return the fields they updated, using a slightly different schedule shape with public schedule and specification IDs.
Settings lookup response
destinationsPayoutDestinationsrequiredSupported GHS-to-financial-account destination assignment. Always present and may be empty.Click or tap to expand- Name
ghs- Type
string- Description
- Financial account that receives Ghana cedi payouts.
- Name
fxEnabled- Type
boolean- Description
Present when foreign exchange payouts are enabled.
schedulePayoutSettingsLookupScheduleActive payout schedule, when available.Click or tap to expand- Name
agingSpec- Type
PayoutSettingsLookupScheduleAgingSpec- Required
- required
View aging_spec attributesClick or tap to expand
- Name
description- Type
string- Required
- required
- Description
- Human-readable schedule description.
- Name
interval- Type
string- Required
- required
- Description
- Schedule frequency.
- Name
name- Type
string- Required
- required
- Description
- Schedule name.
- Name
scheduleOn- Type
string- Required
- required
- Description
- When payouts run within the interval.
- Name
type- Type
string- Required
- required
- Description
- Schedule type.
Settings mutation response
destinationsPayoutDestinationsUpdated supported destination assignments, when returned.Click or tap to expand- Name
ghs- Type
string- Description
- Financial account that receives Ghana cedi payouts.
- Name
fxEnabled- Type
boolean- Description
Updated foreign-exchange setting, when returned by an FX mutation.
- Name
id- Type
string- Description
Payout settings identifier.
schedulePayoutSettingsMutationScheduleUpdated payout schedule, when returned.Click or tap to expand- Name
description- Type
string- Required
- required
- Description
- Human-readable schedule description.
- Name
id- Type
string- Required
- required
- Description
- Schedule identifier.
- Name
interval- Type
string- Required
- required
- Description
- Schedule frequency.
- Name
name- Type
string- Required
- required
- Description
- Schedule name.
- Name
scheduleOn- Type
string- Required
- required
- Description
- When payouts run within the interval.
- Name
spec- Type
PayoutSettingsMutationScheduleSpec- Required
- required
View spec attributesClick or tap to expand
Rules that determine when funds become eligible.- Name
abide- Type
string- Required
- required
- Description
- How strictly the aging period is applied.
- Name
id- Type
string- Required
- required
- Description
- Schedule specification identifier.
- Name
label- Type
string- Required
- required
- Description
- Human-readable aging rule label.
- Name
tPlus- Type
string- Required
- required
- Description
- Required transaction age, such as
168h.
- Name
type- Type
string- Required
- required
- Description
- Schedule type.
Related resources
- Connect a financial account - Add the bank account or mobile money wallet that will receive funds.
- Enable push capability - Allow a connected account to receive payouts.
- Retrieve your balance - Check funds available for payout.
- Page through balance transactions - Reconcile the ledger entries included in a payout.