Skip to main content
View as Markdown

Enable automatic payouts

Switch from manual to automatic payout mode to restore scheduled weekly settlements. This guide walks you through enabling automatic payouts, verifying your configuration, and monitoring the first automatic payout cycle.

Use MCP before and after changing payout mode

An authenticated AI agent can inspect destination readiness, current payout mode, and recent payouts before or after your API change. Enabling automatic payouts itself still uses the Payouts API.

MCP tools: get_payout_settings or list_payouts

For complete details on automatic vs. manual payout modes, see Payouts product documentation.

When to enable automatic mode

Enable automatic payouts when you're ready to restore hands-off settlement flows:

  • After financial reconciliation — Month-end close or audit complete
  • After testing — New destinations validated with manual payouts
  • Manual control burden — Tired of remembering to trigger payouts weekly
  • Cashflow stabilized — Balance reached steady state after uncertain period
  • Destination issues resolved — New account connected and verified

See the Payouts product documentation for detailed explanations of when to use each mode.

Prerequisites

Before enabling automatic payouts:

1. Verify destinations are configured​

Automatic payouts require configured destinations for each currency you accept.

Check payout settings

POST/payouts/settings
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

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

Response

SDK versionv12.0.0
SettingsResponse {
  settings: { … },
}

If destinations is empty or missing currencies, use /payouts/set_destinations to configure them. See Manage payout destinations.

2. Understand the weekly schedule​

Automatic payouts run every Sunday at midnight UTC. Funds arrive Monday (mobile money) or Tuesday-Wednesday (bank transfers). See Payout schedules for details.

3. Check current mode​

If schedule.type is already "automatic", you're already in automatic mode—no action needed.

Enable automatic payouts

Switching to automatic mode is a single API call with an empty JSON object:

Enable automatic payouts

POST/payouts/enable
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

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

Response

SDK versionv12.0.0
SettingsResponse {
  settings: { … },
}

What changed​

Your payout schedule switched from manual to automatic:

Starting next Sunday, Inttegro creates automatic payouts for eligible balance transactions (aged 7+ days).

What happens next

Sunday midnight UTC: Inttegro creates payouts for each currency with eligible balance transactions (aged 7+ days) and a configured destination.

Sunday-Monday: Payouts execute. Monitor with /payouts/lookup.

Monday-Wednesday: Funds arrive in your destination accounts. Bank statements show descriptor INTG*PAYOUT_ID.

The cycle repeats weekly until you disable automatic payouts. See How payouts work for complete details.

Monitoring

Monitor automatic payouts to catch failures and verify amounts:

List recent payouts

POST/payouts/page
SDK versionv12.0.0
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: 10,
})

Focus on payouts whose status is Inttegro.PayoutStatuses.Failed, and on unusual amounts. Use failure.reason for the stable failure category.

Dashboard: business.inttegro.dev shows status badges, amounts, and balance trends.

Common scenarios

After month-end close: Call /payouts/enable on the 1st. First automatic payout creates the following Sunday for transactions aged 7+ days.

After testing: Enable automatic mode once manual payout tests succeed. Monitor the first few automatic cycles closely.

After destination changes: Test new destination with manual payout, then enable automatic mode once verified.

Best practices

  • Monitor the first 2-3 cycles — Verify payouts create on schedule, amounts match expectations, funds arrive correctly
  • Keep destinations updated — Update via /payouts/set_destinations when accounts change
  • Set up failure alerts — Use dashboard notifications for immediate failure notification
  • Document the schedule — Ensure your team knows payouts run Sundays at midnight UTC
  • Review quarterly — Check destinations, cadence, and aging rules still match business needs

Troubleshooting

Payouts not creating: Verify settings.schedule.type is "automatic", check destinations are configured, and ensure you have eligible transactions.

Payout failed: Use Lookup a payout and inspect failure. Branch on its stable reason, show its detail to an operator, and check its retryable value before creating another payout.

Payouts arriving late: Bank transfers take 1-3 business days. Mobile money should arrive Monday—if delayed, check with provider.

Wrong amount: Check the balanceTransactions array. Sum each item's allocated_amount; the original amount may be larger when refunds or earlier payouts already consumed part of a source transaction.

Need to disable: Call /payouts/disable before next Sunday to switch to manual mode.

Next steps

Now that automatic payouts are enabled, explore related concepts to optimize your settlement flows:

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