---
title: "Manage payout destinations"
description: "Configure where your earnings land with currency-specific payout destinations."
canonical: "https://studio.inttegro.com/guides/manage-payout-destinations"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/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: 427
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_integration_guide","check_integration_readiness","get_payout"]
estimated_tokens: 5399
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Choose an active, push-enabled account for the supported payout currency, save the destination mapping, and read settings back.

### Five questions

#### Q1. What must exist before a destination can be configured?

Connect an existing financial account and retain its ID. Check active lifecycle, matching currency, and push capability in the [Financial Accounts reference](https://studio.inttegro.com/machine/python/api/financial-accounts.md); connection alone is not destination configuration.

#### Q2. What does the destination map contain?

[Set payout destinations](https://studio.inttegro.com/machine/python/api/payouts.md#set-payout-destinations) maps the supported currency to a financial account ID. The current guide describes GHS routing; do not invent additional currency routes from the map shape.

#### Q3. How is routing verified after an update?

Read [Get payout settings](https://studio.inttegro.com/machine/python/api/payouts.md#get-payout-settings) and compare the saved currency-to-account mapping with the intended account. A successful mutation response alone is not enough for an operational setup check.

#### Q4. Does changing a destination move an in-flight payout?

No. The setting affects future payouts; scheduled, executing, or completed payouts retain their existing destination. Track a particular transfer by payout ID.

#### Q5. Where does MCP help?

With an authenticated connection, [get_payout_settings](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_payout_settings) can read routing after setup. Account connection and destination changes remain API or dashboard operations; do not infer a catalog mutation tool.

## Document content

# Manage payout destinations

Control where your money goes. This guide walks you through setting up payout destinations—the financial accounts that receive your earnings when Inttegro automatically settles your balance. You'll connect your existing accounts to Inttegro, configure them as destinations, and verify everything routes correctly.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

## Understanding payout destinations

When customers pay you through Inttegro, those funds accumulate in your available balance. Periodically—weekly by default, though you can trigger manual payouts anytime—Inttegro bundles settled transactions and transfers them to your financial accounts. That's a payout.

Each payout needs a destination: a financial account that receives the funds. The current destination contract accepts `'ghs'`, which must map to a GHS financial account. Configure one supported account for that currency before enabling automatic payouts.

Think of payout destinations as your standing settlement instructions. Once configured, automatic payouts just work—funds flow from your balance to the right account without manual intervention. You'll typically set these up once during onboarding, then only touch them when opening accounts in new currencies or switching to different financial accounts.

For complete details on payout mechanics, timing, and how balance transactions bundle into payouts, see the [Payouts reference](https://studio.inttegro.com/machine/python/api/payouts.md).

## Before you start

You'll need:

- **Financial accounts** in each currency you want to receive payouts for—these must already exist with your financial service provider and be active (not disconnected)
- **Push capability** enabled on those accounts (so Inttegro can send funds to them)

If you don't have financial accounts connected yet, you'll connect them in Step 1. If you already have them connected, skip straight to Step 2.

## Step 1: connect your financial accounts

Payout destinations must be financial accounts you own and control. Before configuring destinations, you need to connect each existing account to Inttegro—this tells the platform where to route funds and establishes push permissions.

### Why connect accounts first?

Inttegro validates every destination to ensure funds can actually reach it. When you set a payout destination, the API checks:

1. The financial account exists in your Inttegro account
2. The account is active (not disconnected)
3. The account's currency matches the payout currency
4. Push operations are enabled (Inttegro can send money out to it)

Attempting to configure an unconnected or disconnected account as a destination fails immediately with a clear error—saving you from discovering routing problems when your first payout runs.

### Connecting a financial account

Connect the financial account you want to use for payouts. Choose the account type that matches your needs:

### Mobile money

Mobile money wallets provide fast, convenient payouts directly to your phone. Popular for daily operations and small to medium transactions.

**Connect financial account — POST /financial\_accounts/connect**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.financial_accounts.connect(inttegro.financial_account.WalletRequest(
  type=inttegro.financial_account.Type.WALLET,
  currency="ghs",
  label="MTN Settlement Wallet",
  reference="SETTLEMENT-GHS-001",
  owner=inttegro.bank_account.OwnerParams(
    name="Akua Mensah",
    address=inttegro.bank_account.OwnerAddressParams(
      name="Akua Mensah",
      line_1="23 Independence Avenue",
      city="Accra",
      region="Greater Accra",
      country="GH",
    ),
  ),
  wallet=inttegro.wallet.Params(
    type=inttegro.wallet.Type.MOBILE_MONEY,
    mobile_money=inttegro.wallet.MobileMoneyParams(
      network=inttegro.payment_method.MobileMoneyNetwork.MTN,
      account_number="0244123456",
    ),
  ),
  push_configuration=inttegro.financial_account.WalletRequestPushConfiguration(
    enabled=True,
  ),
))
```

**Supported networks**: `'airtel'`, `'mtn'`, `'telecel'`, and `'vodafone'`. The account number should be the registered mobile number in local or international format.

### Bank account

Bank accounts require an account number and either a sort code or SWIFT code. Holder and address details are optional.

**Connect bank account — POST /financial\_accounts/connect**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.financial_accounts.connect(inttegro.financial_account.BankRequest(
  type=inttegro.financial_account.Type.BANK_ACCOUNT,
  currency="ghs",
  label="GCB Business Account",
  reference="SETTLEMENT-GHS-001",
  bank_account=inttegro.bank_account.Params(
    type=inttegro.bank_account.Type.GHANA_BANK_ACCOUNT,
    ghana_bank_account=inttegro.bank_account.GhanaBankAccountParams(
      number="1234567890",
      sort_code="040127",
      holder=inttegro.bank_account.OwnerParams(
        name="John Doe",
        address=inttegro.bank_account.OwnerAddressParams(
          name="Business Address",
          line_1="123 High Street",
          city="Accra",
          region="Greater Accra",
          country="Ghana",
        ),
      ),
    ),
  ),
  push_configuration=inttegro.financial_account.BankRequestPushConfiguration(
    enabled=True,
  ),
))
```

**Required fields**: Account number and at least one of sort code or SWIFT code. Holder details are optional.

### Key attributes explained

- **[`account.currency`](https://python.inttegro.dev/v12.0.0/inttegro/financial_account.html#FinancialAccount)**: Use `'ghs'`, the currency currently accepted by financial-account connection and payout-destination configuration.
- **[`label`](https://python.inttegro.dev/v12.0.0/inttegro/financial_account.html#FinancialAccount)**: Human-readable name for your team and dashboard. Be descriptive: "MTN Settlement Wallet" beats "Wallet 1".
- **[`reference`](https://python.inttegro.dev/v12.0.0/inttegro/financial_account.html#FinancialAccount)**: Your internal identifier for reconciliation—use it to match this account in your systems.
- **[`push_configuration.enabled`](https://python.inttegro.dev/v12.0.0/inttegro/financial_account.html#WalletRequestPushConfiguration.enabled): `True`**: Critical. This grants Inttegro permission to send funds to this account. Without it, the account can't receive payouts.
- **Response [`id`](https://python.inttegro.dev/v12.0.0/inttegro/payout.html#SettingsMutation)**: Save this—you'll use it when configuring the destination in Step 2.

## Step 2: configure payout destinations

With your financial accounts connected to Inttegro, you're ready to map currencies to destinations. This tells Inttegro exactly where to send funds for each currency.

**Set payout destinations — POST /payouts/set\_destinations**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.payouts.set_destinations(inttegro.payout.SetDestinationsRequest(
  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"
    }
  }
}
```

### What just happened

Inttegro validated three things:

1. **Currency support**: `'ghs'` is a supported payout currency
2. **Account ownership**: Financial account `fa_H3cNv7...` exists in your Inttegro account and belongs to you
3. **Currency match**: The account currency matches the destination map key

If any check failed, you'd get an immediate error with specific details about what's wrong. Since everything passed, the destination is now active. Your next automatic GHS payout will route to this account.

### Current currency support

Inttegro currently accepts a GHS destination mapping. Your GHS payouts route to the configured GHS account. Do not send additional currency keys unless the endpoint reference explicitly lists them as accepted.

### Updating destinations

Need to switch accounts? Call the same endpoint with the new financial account ID:

```python
inttegro.payout.SetDestinationsRequest(
  destinations={
    "ghs": "fa_NewAccountID",
  },
)
```

Inttegro overwrites the previous value. Your next payout uses the new GHS destination.

### Removing destinations

To remove a currency's destination (disabling automatic payouts for that currency), send an empty string:

```python
inttegro.payout.SetDestinationsRequest(
  destinations={
    "ghs": "",
  },
)
```

Automatic payouts for GHS will stop until you configure a new destination. Manual payouts (via [schedule a payout](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout)) still work—you just need to specify the destination explicitly in each request.

## Step 3: verify your configuration

Always confirm destinations are set correctly before relying on automatic payouts. This prevents surprises when your first settlement runs.

**Get payout settings — POST /payouts/settings**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.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_H3cNv7pQf9WbLt2mJs6yXrPq4Kz1Vd5G0aEiUo"
    }
  }
}
```

### What to check

1. **Schedule cadence**: The [`schedule`](https://python.inttegro.dev/v12.0.0/inttegro/payout.html#SettingsLookup) object shows when automatic payouts run. Default is weekly on Sundays. If you need daily or monthly settlements, contact support to adjust your schedule.

2. **Destinations map**: Verify each currency you accept appears in [`destinations`](https://python.inttegro.dev/v12.0.0/inttegro/payout.html#SetDestinationsRequest.destinations) with the correct financial account ID. Missing currencies won't receive automatic payouts.

3. **Account IDs match**: Cross-reference the financial account IDs against your records. A typo here means funds route to the wrong account (though Inttegro validates ownership, so they'll still land at one of your accounts—just maybe not the right one).

### Viewing in the dashboard

Your payout configuration also appears in the Inttegro Business dashboard at [business.inttegro.dev](https://business.inttegro.dev). Navigate to **Settings → Payouts** to see:

- Active payout schedule (when settlements run)
- Configured destinations by currency
- Recent payout history with status and amounts
- Financial account details (masked account numbers for security)

The dashboard gives your team a visual confirmation that everything's wired correctly, without needing API access. Use it for quick sanity checks and to onboard non-technical teammates who need visibility into settlement flows.

## How automatic payouts work

With destinations configured, here's what happens during each settlement cycle:

1. **Balance accumulation**: As customers pay you, successful payments create balance transactions. These transactions settle (usually within minutes to hours) and become part of your available balance.

2. **Payout scheduling**: On your configured schedule (e.g., every Sunday at midnight UTC), Inttegro checks your available balance for each currency. For each currency with a positive balance and configured destination, Inttegro creates a payout.

3. **Amount allocation**: Inttegro evaluates settled balance transactions for that currency in FIFO order and allocates their available amounts. If the configured maximum falls inside the final source transaction, only the required amount is allocated from that source.

4. **Transfer execution**: Inttegro initiates the transfer to your destination financial account. For mobile money, this typically completes within minutes. For bank transfers, allow 1-3 business days depending on the receiving bank and country.

5. **Status updates**: The payout status progresses from `'scheduled'` → `'executing'` → `'succeeded'`. You can poll [lookup a payout](https://studio.inttegro.com/machine/python/api/payouts.md#lookup-a-payout) for real-time status.

6. **Balance deduction**: Once the payout succeeds, the transferred amount leaves your available balance. Each source balance transaction retains a completed `payout` allocation with the exact amount it contributed, creating a clear audit trail from payment to settlement.

### Manual payouts

Don't want to wait for the next scheduled payout? Trigger one manually with [schedule a payout](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout). This is useful for:

- **Cash flow needs**: Pull funds immediately when you need working capital
- **Testing**: Verify your destination works before the first automatic settlement
- **Threshold-based settlements**: Trigger payouts when your balance hits a certain amount

Manual payouts follow the same flow as automatic ones but execute on-demand rather than on a schedule. See the [Schedule a payout](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout) documentation for details.

## Security and best practices

### Validate account ownership

Inttegro enforces strict ownership checks—you can only configure financial accounts tied to your Inttegro account as destinations. This prevents accidentally (or maliciously) routing funds to someone else's account. If you try to use an account you don't own, the API rejects the request immediately.

### Use descriptive labels

Future you will thank present you for clear financial account labels. "MTN Settlement - GHS" beats "Account 1" when you're debugging a routing issue at 2am or explaining settlement flows to your finance team.

### Monitor payout status

Don't assume payouts always succeed. Network issues, account closures, and provider outages can cause failures. Monitor payout status via:

- **API polling**: Use [lookup a payout](https://studio.inttegro.com/machine/python/api/payouts.md#lookup-a-payout) periodically for critical payouts
- **Dashboard**: Check the Business dashboard for visual status and failure alerts

When a payout fails, Inttegro provides a detailed error (account closed, insufficient balance, provider timeout, etc.) so you can diagnose and fix the issue quickly.

### Separate operating and settlement accounts

Consider using separate financial accounts for daily operations versus payout settlements. This isolates settlement flows from operating expenses, simplifies bookkeeping, and makes reconciliation easier. Your mobile money account might handle settlements while a separate account covers business expenses.

### Test before going live

Before your first production payout, test the full flow:

1. Connect a test financial account (use a real account you control)
2. Configure it as a destination for test mode
3. Trigger a manual payout with a small amount
4. Verify funds arrive at the correct account

This catches configuration errors, validates your financial account details, and builds confidence in the settlement flow before real customer funds move.

## Common issues and solutions

### "Currency not supported" error

**Cause**: You're trying to configure a destination for a currency Inttegro doesn't support yet.

**Solution**: Check the [supported currencies](https://studio.inttegro.com/specs/currencies) list. If you need a specific currency, contact support—we regularly add new currencies based on demand.

### "Financial account not found" error

**Cause**: The financial account ID doesn't exist in your Inttegro account, or you've made a typo.

**Solution**: List your financial accounts via [lookup a financial account](https://studio.inttegro.com/machine/python/api/financial-accounts.md#lookup-a-financial-account) and verify the ID.

### "Currency mismatch" error

**Cause**: The destination key or connected account currency is not accepted by the current GHS destination contract.

**Solution**: Connect a financial account in the correct currency first. Each destination must match its map key—GHS destinations need GHS accounts.

### "Push configuration not enabled" error

**Cause**: The financial account exists but doesn't have push permissions enabled.

**Solution**: Update the financial account to enable push configuration. You can't receive payouts to an account that doesn't allow outbound transfers from Inttegro.

### Payout fails with "account closed" error

**Cause**: The destination financial account was closed at your financial service provider.

**Solution**: Connect a different financial account and update the destination mapping. If you recently closed the account, the provider may take 24-48 hours to fully process the closure—wait until that completes before attempting new payouts.

### Payout takes longer than expected

**Cause**: Bank transfers inherently take time—1-3 business days is normal for many banks, especially international transfers.

**Solution**: Check the payout status via [lookup a payout](https://studio.inttegro.com/machine/python/api/payouts.md#lookup-a-payout). If it is still `'executing'` after the expected timeframe, the provider may be experiencing delays. Mobile money transfers typically complete within minutes; bank transfers take longer. Contact support if a payout has been executing for more than 5 business days.

## Next steps

With payout destinations configured, you're ready to receive settlements automatically. Here's what to explore next:

- **[Schedule manual payouts](https://studio.inttegro.com/machine/python/api/payouts.md#schedule-a-payout)** when you need funds on-demand
- **[Monitor balance transactions](https://studio.inttegro.com/machine/python/api/balance-transactions.md)** to understand what's bundled into each payout
- **[Understand payout schedules](https://studio.inttegro.com/machine/python/api/payouts.md#get-payout-settings)** and when automatic settlements run

Questions? Check the [Payouts reference](https://studio.inttegro.com/machine/python/api/payouts.md) for complete API details, or contact support at support@inttegro.com.