Skip to main 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.

Use MCP to verify destination routing

An authenticated AI agent can read payout settings after you configure destinations and summarize which currencies route to which accounts. Connecting accounts and changing destinations still use the API or dashboard.

MCP tools: get_payout_settings

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.

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 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
curl https://api.inttegro.com/financial_accounts/connect \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet",
    "currency": "ghs",
    "label": "MTN Settlement Wallet",
    "reference": "SETTLEMENT-GHS-001",
    "owner": {
      "name": "Akua Mensah",
      "address": {
        "name": "Akua Mensah",
        "line_1": "23 Independence Avenue",
        "city": "Accra",
        "region": "Greater Accra",
        "country": "GH"
      }
    },
    "wallet": {
      "type": "mobile_money",
      "mobile_money": {
        "network": "mtn",
        "account_number": "0244123456"
      }
    },
    "push_configuration": {
      "enabled": true
    }
  }'

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

Key attributes explained​

  • currency: Use ghs, the currency currently accepted by financial-account connection and payout-destination configuration.
  • label: Human-readable name for your team and dashboard. Be descriptive: "MTN Settlement Wallet" beats "Wallet 1".
  • reference: Your internal identifier for reconciliation—use it to match this account in your systems.
  • push_configuration.enabled: true: Critical. This grants Inttegro permission to send funds to this account. Without it, the account can't receive payouts.
  • Response id: 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
curl https://api.inttegro.com/payouts/set_destinations \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": {
      "ghs": "fa_H3cNv7pQf9WbLt2mJs6yXrPq4Kz1Vd5G0aEiUo"
    }
  }'

Response

SDK versionv8.2.0
SettingsResponse {
  settings: { … },
}

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's currency (ghs) matches the map key (ghs)

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:

{
  "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:

{
  "destinations": {
    "ghs": ""
  }
}

Automatic payouts for GHS will stop until you configure a new destination. Manual payouts (via 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
curl https://api.inttegro.com/payouts/settings \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

SDK versionv8.2.0
SettingsResponse {
  settings: { … },
}

What to check​

  1. Schedule cadence: The schedule 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 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. 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. Transaction bundling: Inttegro identifies all settled balance transactions for that currency and bundles them into the payout. The total amount is the sum of all bundled transactions, capped at your configured maximum payout threshold (if set).

  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 for real-time status.

  6. Balance deduction: Once the payout succeeds, the transferred amount leaves your available balance. The balance transactions included in that payout are marked with the payout_id, 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. 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 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 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 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 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. If it's 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:

Questions? Check the Payouts reference for complete API details, or contact support at [email protected].