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.

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.

curl https://api.zebo.dev/payouts/settings \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

{
  "settings": {
    "schedule": {
      "name": "manual",
      "type": "manual",
      "interval": "manual",
      "schedule_on": "manual",
      "description": "Manual payout"
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

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—no parameters needed beyond authentication:

curl https://api.zebo.dev/payouts/enable \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

{
  "settings": {
    "schedule": {
      "id": "payout_sched_weekly",
      "name": "weekly",
      "type": "automatic",
      "interval": "weekly",
      "schedule_on": "sunday",
      "spec": {
        "id": "payout_spec_weekly",
        "t_plus": "7",
        "label": "7 days",
        "abide": "strict"
      },
      "description": "Automatic weekly payout. Default."
    },
    "destinations": {
      "ghs": "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0"
    }
  }
}

What changed

Your payout schedule switched from manual to automatic:

• schedule.type: manual → automatic
• schedule.name: manual → weekly
• schedule.schedule_on: Payouts create every Sunday at midnight UTC
• destinations: Unchanged

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

What happens next

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

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

Monday-Wednesday: Funds arrive in your destination accounts. Bank statements show descriptor ZCMRZ*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:

curl https://api.zebo.dev/payouts/page \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10
  }'

Focus on status: "failed" payouts and unusual amounts.

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

Webhooks: Configure payout.succeeded and payout.failed events for real-time alerts (documentation coming soon).

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 webhooks or 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 schedule.type is automatic via /payouts/settings, check destinations are configured, ensure you have transactions aged 7+ days.

Payout failed: Check latest_error in /payouts/lookup. Update destinations if account closed, contact provider if issue on their end.

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

Wrong amount: Check balance_transactions array in payout object. Only transactions aged 7+ days are included.

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:

• Understand payout schedules to learn about weekly vs. daily cadences and when to request changes
• Monitor balance transactions to understand what's eligible for the next automatic payout
• Manage payout destinations to keep your financial account mappings current
• Disable automatic payouts when you need temporary manual control

Questions? Check the Payouts API reference for complete endpoint documentation, or contact support at support@zebo.dev.