---
title: "Payouts"
description: "Move available funds to your bank account or mobile money wallet and manage automatic settlement."
canonical: "https://studio.inttegro.com/api/payouts"
format: inttegro-machine-docs/v1
language: "TypeScript"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/typescript/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: 714
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: ["get_payout","get_payout_settings","get_payout_analytics"]
estimated_tokens: 8919
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Move available funds to your bank account or mobile money wallet and manage automatic settlement. This TypeScript representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Payouts?

Use this API reference when exact operations, fields, states, or errors are required.

#### Q2. What is authoritative on this page?

Types and enum members link to pinned SDK references; a response field may link only to its containing type. A “wire-only” request field is not a verified native SDK member.

#### Q3. What page-specific constraint matters most?

Prioritize the machine-only guidance “Plan and reconcile a payout without guessing its outcome”: Resolve the destination before scheduling. The financial account must be active, connected, able to receive funds, and denominated in the destination currency. Use Financial accounts and payout settings to verify this rather than deriving…

#### Q4. Can Inttegro MCP materially help with this task?

Yes, when the reader has an authenticated MCP connection and the task needs live context, guided planning, or a supported operation. The strongest matches are `get_payout`, `get_payout_settings`, `get_payout_analytics`; their exact roles and boundaries are listed below.

#### Q5. How should the reader verify the answer and continue?

For a read, compare the returned resource with the requested identifier and scope. For a write, preserve its identifier and retrieve authoritative current state before declaring the business outcome complete. Continue with [Page through balance transactions](https://studio.inttegro.com/machine/typescript/api/balance-transactions.md#page-through-balance-transactions) and [Retrieve your balance](https://studio.inttegro.com/machine/typescript/api/balances.md#retrieve-your-balance) when those concerns enter scope.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_payout`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_payout) — read; no mutation confirmation. Gets one payout by ID with status, amount, timing, and minimized reconciliation detail. This tool cannot move funds.
- [`get_payout_settings`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_payout_settings) — read; no mutation confirmation. Gets automatic payout schedule, FX status, and currency-to-destination mappings without changing them.
- [`get_payout_analytics`](https://studio.inttegro.com/machine/typescript/inttegro-mcp/tools.md#get_payout_analytics) — analytics read; no mutation confirmation. Compares payout starts, successes, failures, cancellations, lateness, and exact requested, disbursed, and failed amounts.

## Document content

# 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](https://studio.inttegro.com/machine/typescript/products/payouts.md) and [Understand payouts](https://studio.inttegro.com/machine/typescript/guides/understand-payouts.md).

## Plan and reconcile a payout without guessing its outcome

- **Resolve the destination before scheduling.** The financial account must be
  active, connected, able to receive funds, and denominated in the destination
  currency. Use [Financial accounts](https://studio.inttegro.com/machine/typescript/api/financial-accounts.md) and [payout
  settings](#get-payout-settings) to verify this rather than deriving currency
  from an amount supplied by the caller.
- **Treat the requested maximum as authorization, not the final transfer.**
  `maxAmount`
  is a ceiling; the settled
  [`payout.amount`](https://typescript.inttegro.dev/v12.0.0)
  can be lower.
- **Lookup is the source of truth after scheduling.** Preserve the returned
  payout ID and read it until the state is terminal. Cancellation is available
  only while the payout remains scheduled and its execution time is still in
  the future.
- **Reconcile with balance transactions, not payout amount alone.** Follow
  [`payout.balanceTransactions`](https://typescript.inttegro.dev/v12.0.0)
  to see every source transaction's original `amount` and its
  payout-specific `allocated_amount`. The allocated amounts,
  rather than the original amounts, sum to the payout amount.
- **Handle terminal failures through the structured failure.** When
  [`payout.status`](https://typescript.inttegro.dev/v12.0.0)
  is [`Inttegro.PayoutStatuses.Failed`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#failed),
  record [`payout.failedAt`](https://typescript.inttegro.dev/v12.0.0), branch on
  [`payout.failure.reason`](https://typescript.inttegro.dev/v12.0.0), and treat
  [`payout.failure.detail`](https://typescript.inttegro.dev/v12.0.0) as explanatory text rather than a
  value to parse. Create another payout only when your workflow has
  established that doing so is safe;
  [`payout.failure.retryable`](https://typescript.inttegro.dev/v12.0.0) is useful guidance, not an
  instruction to retry automatically.

## 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

- [`amount`](https://typescript.inttegro.dev/v12.0.0)

  Actual payout amount when known. Omitted before the amount is determined.

  - [`amount.currency`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Lowercase currency code.

  - [`amount.value`](https://typescript.inttegro.dev/v12.0.0) — `integer` — required

    Amount in the smallest currency unit.

- [`balanceTransactions`](https://typescript.inttegro.dev/v12.0.0) — `array`

  All source contribution objects. Each contains the balance transaction
  `id`, its original `amount`, and the exact
  `allocated_amount` selected for this payout. Its
  `status` is `reserved` while the payout is
  open, `completed` after success, or
  `released` when 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.

- [`balanceTransactionId`](https://typescript.inttegro.dev/v12.0.0) — `string`

  The payout's own immutable debit balance transaction. Present after the
  payout succeeds. This is distinct from
  [`payout.balanceTransactions`](https://typescript.inttegro.dev/v12.0.0), which lists the payment
  balance transactions that funded the payout.

- [`canceledAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the payout was canceled. Omitted otherwise.

- [`customData`](https://typescript.inttegro.dev/v12.0.0) — `object`

  Your string key-value metadata, when available.

- [`destinationId`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

  Financial account selected as the destination.

- [`error`](https://typescript.inttegro.dev/v12.0.0) — `object`

  Deprecated compatibility view of a failed payout. Use
  [`payout.failure`](https://typescript.inttegro.dev/v12.0.0) for new integrations.

- [`executeAfter`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` — required

  Earliest time execution can begin.

- [`executedBy`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Actor that executed the payout, when available.

- [`expectedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  Expected completion time, when available.

- [`failedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the payout entered the
  [`Inttegro.PayoutStatuses.Failed`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#failed) state.
  Omitted otherwise.

- [`failure`](https://typescript.inttegro.dev/v12.0.0)

  Caller-safe terminal failure information. Present only when status is failed.

  - [`failure.detail`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Safe explanation for an operator. Display or log it, but do not parse it.

  - [`failure.reason`](https://typescript.inttegro.dev/v12.0.0) — `enum`

    Stable failure category. The possible values follow.

  - [`failure.retryable`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

    Whether a newly created payout may succeed. Do not automatically repeat a payout solely because this value is true.

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

  Unique payout identifier.

- [`initiatedAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp` — required

  When the payout record was created.

- [`initiatedBy`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Actor that initiated the payout, when available.

- [`maxAmount`](https://typescript.inttegro.dev/v12.0.0) — required

  Maximum authorized payout amount.

  - [`maxAmount.currency`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Lowercase currency code.

  - [`maxAmount.value`](https://typescript.inttegro.dev/v12.0.0) — `integer` — required

    Amount in the smallest currency unit.

- [`reference`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Your reconciliation reference, when provided.

- [`scheduleId`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Schedule associated with the payout, when available.

- [`scheduledAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the payout was scheduled, when available.

- [`scheduledBy`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Actor that scheduled the payout, when available.

- [`sentAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the transfer was sent, when available.

- [`sourceId`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Source identifier, when available.

- [`status`](https://typescript.inttegro.dev/v12.0.0) — `enum` — required

  Current state:
  [`Inttegro.PayoutStatuses.Initialized`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#initialized),
  [`Inttegro.PayoutStatuses.Scheduled`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#scheduled),
  [`Inttegro.PayoutStatuses.Processing`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#processing),
  [`Inttegro.PayoutStatuses.Executing`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#executing),
  [`Inttegro.PayoutStatuses.Succeeded`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#succeeded), [`Inttegro.PayoutStatuses.Failed`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#failed), or
  [`Inttegro.PayoutStatuses.Canceled`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#canceled).

- [`succeededAt`](https://typescript.inttegro.dev/v12.0.0) — `timestamp`

  When the payout succeeded. Omitted otherwise.

#### Failure reason values

- `"provider_declined"`— The
  provider declined the payout before it could be delivered.
- `"delivery_failed"`— The
  transfer was sent for delivery but did not complete at the destination.
- `"temporarily_unavailable"`—
  Payout processing was temporarily unavailable. Check
  [`payout.failure.retryable`](https://typescript.inttegro.dev/v12.0.0) before deciding whether to create
  a new payout.
- `"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](https://studio.inttegro.com/machine/typescript/guides/understand-payouts.md).

## 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](#lookup-a-payout).

### Request attributes

- `destinationId` — `string` — required

  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.

- `executeAfter` — `Time`

  Earliest time Inttegro may begin the payout, as an ISO 8601 UTC timestamp. Omit it to begin as soon as possible.

- `maxAmount` — `number`

  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.

- `reference` — `string` — required

  Your reference for matching the payout to your own records. It does not need to be unique.

**Request — POST /payouts/schedule**

```typescript
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"),
})
```

```json
{
  "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, [`payout.failure`](https://typescript.inttegro.dev/v12.0.0), and [`payout.balanceTransactions`](https://typescript.inttegro.dev/v12.0.0) are omitted until they have values.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `payout_id` — `string` — required — wire-only

  Payout ID returned when the payout was scheduled.

**Request — POST /payouts/lookup**

```typescript
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",
})
```

```json
{
  "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": [
      {
        "id": "bt_Za2bL9kPxV1c4Gs7Ju0DrQhn",
        "amount": { "currency": "ghs", "value": 150000 },
        "allocated_amount": { "currency": "ghs", "value": 140000 },
        "status": "reserved"
      },
      {
        "id": "bt_Ps8wC1nDf5m9Qh2Vt6YkRgLb",
        "amount": { "currency": "ghs", "value": 100000 },
        "allocated_amount": { "currency": "ghs", "value": 100000 },
        "status": "reserved"
      }
    ]
  }
}
```

## 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`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#scheduled) and [`payout.executeAfter`](https://typescript.inttegro.dev/v12.0.0) is still in the future. The response returns the payout with [`payout.status`](https://typescript.inttegro.dev/v12.0.0) set to [`Inttegro.PayoutStatuses.Canceled`](https://typescript.inttegro.dev/v12.0.0/variables/types_payouts.PayoutStatuses.html#canceled) and its [`payout.canceledAt`](https://typescript.inttegro.dev/v12.0.0) time.

### Request attributes

- `payout_id` — `string` — required — wire-only

  ID of the scheduled payout to cancel.

**Request — POST /payouts/cancel**

```typescript
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",
})
```

```json
{
  "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`](https://typescript.inttegro.dev/v12.0.0) 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](https://studio.inttegro.com/machine/typescript/guides/understand-payout-settings.md) for the schedule fields.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

**Request — POST /payouts/settings**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

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

```json
{
  "settings": {
    "schedule": {
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "aging_spec": {
        "t_plus": "168h",
        "label": "168_hours",
        "abide": "strictly"
      },
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}
```

## 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](https://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

- `destinations` — required — wire-only

  Supported payout destination assignments.

  - `destinations.ghs` — `string` — wire-only

    Financial account that receives Ghana cedi payouts. Pass an empty string to clear the assignment.

**Request — POST /payouts/set\_destinations**

```typescript
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",
  },
})
```

```json
{
  "settings": {
    "schedule": {
      "id": "weekly_default",
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "spec": {
        "id": "standard_aging",
        "t_plus": "168h",
        "label": "168_hours",
        "abide": "strictly"
      },
      "description": "Automatic weekly payout. Default."
    },
    "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](#schedule-a-payout) yourself or enable automatic payouts again later.

**Request — POST /payouts/disable**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

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

```json
{
  "settings": {
    "schedule": {
      "id": "manual",
      "name": "manual",
      "type": "manual",
      "interval": "never",
      "schedule_on": "never",
      "spec": {
        "id": "standard_aging",
        "t_plus": "168h",
        "label": "168_hours",
        "abide": "strictly"
      },
      "description": "Manual payout schedule. Payouts are created only when you schedule them."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}
```

## 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 — POST /payouts/enable**

```typescript
import * as Inttegro from '@inttegro/inttegro-sdk'

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

```json
{
  "settings": {
    "schedule": {
      "id": "weekly_default",
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "spec": {
        "id": "standard_aging",
        "t_plus": "168h",
        "label": "168_hours",
        "abide": "strictly"
      },
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}
```

## Page through payouts

Browse payouts from newest to oldest. Use this for settlement history and reconciliation; use [Lookup a payout](#lookup-a-payout) when you already know the payout ID.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `pageNumber` — `number` — required

  1-based page index to fetch. Must be between 1 and 10 inclusive.

- `pageSize` — `number`

  Number of payouts per page (1–256). Defaults to 256 when omitted.

### Response shape

The response contains [`page.number`](https://typescript.inttegro.dev/v12.0.0), the number of results in [`page.size`](https://typescript.inttegro.dev/v12.0.0), and a [`page.payouts`](https://typescript.inttegro.dev/v12.0.0) array when the page is not empty. Every entry uses [the payout object](#the-payout-object).

**Request — POST /payouts/page**

```typescript
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,
})
```

```json
{
  "page": {
    "number": 1,
    "size": 2,
    "payouts": [
      {
        "id": "po_abc123def456",
        "destination_id": "fa_dest001",
        "max_amount": {
          "currency": "ghs",
          "value": 75000
        },
        "amount": {
          "value": 50000,
          "currency": "ghs"
        },
        "status": "succeeded",
        "initiated_by": "scheduler",
        "initiated_at": "2025-12-15T10:30:00Z",
        "execute_after": "2025-12-15T10:30:00Z",
        "sent_at": "2025-12-15T10:35:00Z",
        "succeeded_at": "2025-12-15T10:35:30Z",
        "balance_transactions": [
          {
            "id": "bt_001",
            "amount": { "currency": "ghs", "value": 30000 },
            "allocated_amount": { "currency": "ghs", "value": 20000 },
            "status": "completed"
          },
          {
            "id": "bt_002",
            "amount": { "currency": "ghs", "value": 20000 },
            "allocated_amount": { "currency": "ghs", "value": 20000 },
            "status": "completed"
          },
          {
            "id": "bt_003",
            "amount": { "currency": "ghs", "value": 10000 },
            "allocated_amount": { "currency": "ghs", "value": 10000 },
            "status": "completed"
          }
        ]
      },
      {
        "id": "po_def456ghi789",
        "destination_id": "fa_dest002",
        "max_amount": {
          "currency": "ghs",
          "value": 100000
        },
        "amount": {
          "value": 75000,
          "currency": "ghs"
        },
        "status": "failed",
        "initiated_by": "app",
        "failure": {
          "reason": "delivery_failed",
          "detail": "The payout could not be delivered to the destination.",
          "retryable": false
        },
        "initiated_at": "2025-12-14T15:00:00Z",
        "execute_after": "2025-12-14T15:00:00Z",
        "failed_at": "2025-12-14T15:20:00Z",
        "expected_at": "2025-12-14T15:00:00Z",
        "balance_transactions": [
          {
            "id": "bt_004",
            "amount": { "currency": "ghs", "value": 50000 },
            "allocated_amount": { "currency": "ghs", "value": 50000 },
            "status": "released"
          },
          {
            "id": "bt_005",
            "amount": { "currency": "ghs", "value": 50000 },
            "allocated_amount": { "currency": "ghs", "value": 25000 },
            "status": "released"
          }
        ]
      }
    ]
  }
}
```

## 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](#lookup-a-payout) before cancellation, reconciliation, or
any decision that depends on current transfer state.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

## Use payout search for discovery, then read the payout

- Send `text`,
  `filters`,
  or both. Filters and facets accept only the wire field names
  `currency` and `status`; field names are
  unqualified.
- Treat each result as a discovery summary. Read the canonical payout by
  [`results[].resource.id`](https://typescript.inttegro.dev/v12.0.0)
  before relying on status, amount, destination, or timing.
- Replay the identical request with
  [`nextCursor`](https://typescript.inttegro.dev/v12.0.0)
  as the request cursor when
  [`hasMore`](https://typescript.inttegro.dev/v12.0.0)
  is true. The cursor is opaque and request-bound.
- [`total`](https://typescript.inttegro.dev/v12.0.0)
  and facets describe the full result set;
  [`resultCount`](https://typescript.inttegro.dev/v12.0.0)
  describes this page. Check
  [`total.relation`](https://typescript.inttegro.dev/v12.0.0)
  before treating a total as exact.
- Inspect [`freshness`](https://typescript.inttegro.dev/v12.0.0);
  use payout lookup whenever delayed, partial, unknown, or unavailable search
  data could change an operational decision.

### Request attributes

- `cursor` — `string`

  Opaque continuation cursor returned by the previous page. Replay the
  same request and add this value for the next page.

- `facets` — `array`

  Fields to group and count: currency or status.

  - `facets.field` — `array` — required

    Route-local facet field.

  - `facets.limit` — `array`

    Maximum buckets, from 1 through 50. Defaults to 10.

- `filters` — `array`

  Exact currency or status constraints.

  - `filters.field` — `array` — required

    Route-local filter field.

  - `filters.operator` — `array` — required

    eq for one value or in for any supplied value.

  - `filters.values` — `array` — required

    One value for eq; one through 20 values for in.

- `pageSize` — `integer`

  Results per page, from `1` through `100`. Defaults to `20`.

- `sort` — `object`

  Result ordering.

  - `sort.direction` — `object` — required

    asc or desc. Relevance supports desc only.

  - `sort.field` — `object` — required

    relevance or updated\_at.

- `text` — `string`

  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`](https://typescript.inttegro.dev/v12.0.0),
and [`freshness`](https://typescript.inttegro.dev/v12.0.0) metadata. Read the canonical payout before
acting on a result.

**Request — POST /payouts/search**

```typescript
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)
```

```json
{
  "search": {
    "results": [
      {
        "resource": { "type": "payout", "id": "po_abc123xyz" },
        "title": "Payout po_abc123xyz",
        "status": "scheduled",
        "amount": { "currency": "ghs", "value": 125000 },
        "updated_at": "2026-09-21T10:30:00Z"
      }
    ]
  }
}
```

## Payout settings responses

[Get payout settings](#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

- [`destinations`](https://typescript.inttegro.dev/v12.0.0) — required

  Supported GHS-to-financial-account destination assignment. Always present and may be empty.

  - [`destinations.ghs`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Financial account that receives Ghana cedi payouts.

- [`fxEnabled`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

  Present when foreign exchange payouts are enabled.

- [`schedule`](https://typescript.inttegro.dev/v12.0.0)

  Active payout schedule, when available.

  - [`schedule.agingSpec`](https://typescript.inttegro.dev/v12.0.0) — `object` — required

    Rules that determine when funds become eligible.

    - [`schedule.agingSpec.abide`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      How strictly the aging period is applied.

    - [`schedule.agingSpec.label`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      Human-readable aging rule label.

    - [`schedule.agingSpec.tPlus`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      Required transaction age, such as 168h.

  - [`schedule.description`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Human-readable schedule description.

  - [`schedule.interval`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule frequency.

  - [`schedule.name`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule name.

  - [`schedule.scheduleOn`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    When payouts run within the interval.

  - [`schedule.type`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule type.

### Settings mutation response

- [`destinations`](https://typescript.inttegro.dev/v12.0.0)

  Updated supported destination assignments, when returned.

  - [`destinations.ghs`](https://typescript.inttegro.dev/v12.0.0) — `string`

    Financial account that receives Ghana cedi payouts.

- [`fxEnabled`](https://typescript.inttegro.dev/v12.0.0) — `boolean`

  Updated foreign-exchange setting, when returned by an FX mutation.

- [`id`](https://typescript.inttegro.dev/v12.0.0) — `string`

  Payout settings identifier.

- [`schedule`](https://typescript.inttegro.dev/v12.0.0)

  Updated payout schedule, when returned.

  - [`schedule.description`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Human-readable schedule description.

  - [`schedule.id`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule identifier.

  - [`schedule.interval`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule frequency.

  - [`schedule.name`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule name.

  - [`schedule.scheduleOn`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    When payouts run within the interval.

  - [`schedule.spec`](https://typescript.inttegro.dev/v12.0.0) — `object` — required

    Rules that determine when funds become eligible.

    - [`schedule.spec.abide`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      How strictly the aging period is applied.

    - [`schedule.spec.id`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      Schedule specification identifier.

    - [`schedule.spec.label`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      Human-readable aging rule label.

    - [`schedule.spec.tPlus`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

      Required transaction age, such as 168h.

  - [`schedule.type`](https://typescript.inttegro.dev/v12.0.0) — `string` — required

    Schedule type.

## Related resources

- [Connect a financial account](https://studio.inttegro.com/machine/typescript/api/financial-accounts.md#connect-a-financial-account) - Add the bank account or mobile money wallet that will receive funds.
- [Enable push capability](https://studio.inttegro.com/machine/typescript/api/financial-accounts.md#enable-push-capability) - Allow a connected account to receive payouts.
- [Retrieve your balance](https://studio.inttegro.com/machine/typescript/api/balances.md#retrieve-your-balance) - Check funds available for payout.
- [Page through balance transactions](https://studio.inttegro.com/machine/typescript/api/balance-transactions.md#page-through-balance-transactions) - Reconcile the ledger entries included in a payout.