Understand payouts

Payouts are how available balance becomes actual money in your bank account or mobile wallet. Unlike balance snapshots which aggregate funds into categories, payouts represent actual transfer operations—withdrawal requests that bundle eligible balance transactions, route them to configured destinations, and track execution through retries and settlement. This guide answers common questions about payout timing, execution behavior, failure scenarios, and reconciliation patterns.

When do payouts run?

The timing depends entirely on your payout schedule—automatic weekly or manual on-demand.

Automatic weekly schedule

Payouts run every Sunday at midnight UTC. At that moment, the system scans your available balance, identifies all balance transactions that have aged at least 7 days (168 hours from settlement), and bundles them into payouts for each currency with a configured destination.

Why Sunday midnight UTC? This timing hits during low-traffic banking hours globally, reducing the chance of provider rate limits, network congestion, or processing delays. For most merchants, funds arrive Monday morning (mobile money) or Tuesday-Wednesday (bank transfers), creating a predictable weekly rhythm that your finance team can plan around.

What "7 days aged" means: A balance transaction created Monday at 3:00 PM becomes eligible for payout the following Monday at 3:00 PM (exactly 168 hours later). The next automatic payout after that eligibility moment will include it. If a transaction ages on Tuesday but payouts run Sunday, it waits until the following Sunday—so effective delay can be 7-13 days depending on when the transaction settles relative to the Sunday execution window.

This aging requirement isn't negotiable—it's the dispute protection buffer that keeps you solvent when chargebacks arrive days after the original transaction. Without it, you'd send funds that you later need to return, creating negative balances and cashflow problems.

Manual schedule

In manual mode, payouts run when you trigger them via the Schedule a payout endpoint. No automatic execution happens—funds accumulate in your available balance until you explicitly create a payout.

Balance transactions still must age 7 days before they're eligible (same requirement as automatic mode), but you control when within that eligibility window the payout executes. Set execute_after to trigger immediately or schedule for a specific future time (vendor payment deadline, payroll run, month-end closing).

When manual mode makes sense:

• Vendor payment schedules - Trigger payouts Thursday to arrive Friday for weekly supplier payments
• Audit windows - Freeze disbursements during month-end reconciliation, resume afterward
• Testing destinations - Send small test payouts to new financial accounts before enabling automatic mode
• Multi-currency timing - Pull USD early in the week (2-3 day bank settlement) while triggering GHS instantly (mobile money settles in minutes)
• Cashflow optimization - Align payout timing precisely with your operational cash needs

The tradeoff: You must remember to trigger payouts. Forget for a few weeks and funds pile up in your balance rather than reaching your operating accounts. Manageable for teams with strong financial operations, problematic for those who benefit from automatic weekly transfers.

See the Disable automatic payouts guide to switch to manual mode.

What happens when a payout runs?

Understanding the execution flow helps you anticipate timing, diagnose failures, and plan for retries.

1. Eligibility scan

The system queries your available balance for all balance transactions that have aged at least 7 days. Each transaction's settled_at timestamp determines eligibility—if now - settled_at >= 168 hours, it's eligible.

Transactions still in pending balance are excluded (not aged enough). Reserved and refund balances are also excluded—only available balance contributes to payouts.

2. Currency grouping and bundling

Eligible transactions are grouped by currency. For each currency with a configured destination (set via Set payout destinations), the system creates one payout bundling all eligible transactions in that currency.

If you accept both GHS and USD with different destinations, you'll see two payouts created—one for GHS transactions, one for USD transactions. Each payout bundles all eligible transactions for its currency up to your configured maximum amount.

Amount limits apply: If your payout settings specify a maximum of GHS 10,000 but you have GHS 15,000 eligible, the payout bundles GHS 10,000 worth of transactions. The remaining GHS 5,000 stays in available balance for the next payout run.

3. Transfer initiation

Commerce sends the transfer request to the payout provider (mobile money operator, bank, or internal ledger). This creates the first attempt record on the payout object—tracking amount, destination, reference, and status.

For mobile money transfers, this typically completes within minutes. For bank transfers, expect 1-3 business days depending on the receiving bank's processing schedule and country-specific banking rails.

The payout status becomes processing during this phase. Check latest_attempt.status for detailed attempt state.

4. Automatic retries on transient failures

If the transfer fails due to transient issues (network timeout, temporary provider outage, rate limit), Commerce automatically retries with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: After 5 minutes
• Attempt 3: After 15 minutes
• Attempt 4: After 45 minutes
• Attempt 5: After 2 hours

Each retry creates a new attempt record. Check latest_attempt for the most recent execution and attempts_count to see how many retries happened.

Permanent failures (closed accounts, invalid account details, insufficient balance) are not retried—the payout fails immediately with detailed error information in latest_error.

5. Settlement and finalization

Once the provider confirms successful transfer, the payout status becomes succeeded. The amount field is set to the exact value transferred, executed_at captures when the transfer completed, and the balance transactions are marked as paid out.

The funds appear in your destination account's transaction history with a descriptor formatted as ZCMRZ*PAYOUT_ID. Use that payout ID to trace the deposit back to specific customer payments via the Commerce API.

Why did my payout fail?

Payout failures fall into three categories: configuration problems, balance issues, and provider errors.

Configuration problems

Invalid or closed destination account - The financial account you configured for this currency no longer exists, is archived, or has been closed by the provider. Solution: Update your payout destinations with Set payout destinations using an active financial account.

Missing destination mapping - You have available balance in a currency but no destination configured. Automatic payouts skip currencies without destinations; manual payouts reject the request. Solution: Connect a financial account for that currency and map it as the payout destination.

Payout limits exceeded - The bundled amount exceeds your configured maximum payout limit. This shouldn't happen for automatic payouts (they respect limits when bundling), but can occur in manual mode if you specify a max_amount above your settings limit. Solution: Reduce max_amount in manual payout requests or contact support to adjust your account limits.

Balance issues

Insufficient available balance - At execution time, your available balance is lower than expected. This happens when transactions move to reserved balance between payout creation and execution, or when refunds consume available funds before the payout executes. Solution: Check current balance state with the Balances API. For manual payouts, reduce max_amount to match current available balance.

Balance transactions no longer eligible - Rare, but possible: balance transactions included in the payout become ineligible between creation and execution due to chargebacks or platform holds. Solution: The payout automatically excludes ineligible transactions and transfers the reduced amount. Check the final amount value after execution—it may be less than originally bundled.

Provider errors

Rate limits - The payout provider (mobile money operator or bank) temporarily throttles Commerce due to high transfer volume. Commerce automatically retries with exponential backoff. Most rate limit failures resolve within the retry window (2-3 hours).

Provider outages - The destination provider's systems are down or experiencing disruptions. Commerce retries automatically. If the outage lasts longer than the retry window (2 hours), the payout fails and you'll need to reschedule manually once the provider recovers.

Account verification required - Some providers require additional verification before accepting large transfers. The payout fails with an error message indicating verification requirements. Solution: Complete the verification process with your provider, then reschedule the payout.

Regulatory holds - In some jurisdictions, transfers above certain thresholds trigger automatic regulatory review. The payout may be held pending review (1-3 business days). Commerce surfaces this as a pending status rather than a failure—wait for regulatory clearance.

How to diagnose failures:

1. Call Lookup a payout with the payout ID
2. Check status field—failed indicates permanent failure
3. Read latest_error.type for machine-readable error classification
4. Read latest_error.message for human-readable explanation
5. Check latest_error.cause for provider-specific details
6. Review attempts_count to see how many retries occurred

How do I track payout execution?

Commerce provides multiple mechanisms for monitoring payout progress from creation through settlement.

Poll with Lookup endpoint

Call Lookup a payout periodically with the payout ID returned when you scheduled the payout. The response includes current status, execution timing, attempt history, and error details if applicable.

Polling strategy:

• Immediate execution: Poll every 5 seconds for the first minute, then every 30 seconds
• Scheduled execution: Start polling 5 minutes before execute_after time
• Retry phase: Poll every 2 minutes during automatic retry window (2 hours)

Stop polling once status reaches terminal state (succeeded or failed).

Webhook notifications

Configure webhooks to receive real-time notifications when payout status changes:

• payout.scheduled - Payout created and queued
• payout.processing - Transfer initiated with provider
• payout.succeeded - Transfer completed successfully
• payout.failed - All retry attempts exhausted, payout failed

See the Webhooks documentation for setup instructions and payload schemas.

Status field interpretation

The status field follows this progression:

Attempt tracking

Each execution attempt is recorded separately. Check latest_attempt for the most recent try:

{
  "latest_attempt": {
    "id": "att_abc123",
    "status": "processing",
    "destination_id": "fa_def456",
    "amount": { "currency": "ghs", "value": 145000 },
    "reference": "PAYOUT-2024-01-15-001",
    "created_at": "2024-01-15T12:00:00Z"
  },
  "attempts_count": 3
}

If attempts_count > 1, Commerce retried due to transient failures. This is normal—most payouts succeed within 2-3 attempts.

How do payouts appear on bank statements?

Every payout appears as a single line item with a descriptor formatted as ZCMRZ*PAYOUT_ID. This format is consistent across all banks, mobile money operators, and supported financial institutions.

Example: ZCMRZ*po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB

Components:

• Prefix: ZCMRZ (fixed, identifies Commerce transfers)
• Separator: *
• Payout ID: The unique identifier from the payout object (e.g., po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB)

Why this format matters

Automated reconciliation: Your accounting software can parse this descriptor, extract the payout ID, query the Commerce API for payout details (bundled balance transactions, customer payments, order IDs), and automatically match deposits to revenue—no manual work required.

Audit trails: When auditors ask "where did this deposit come from?", you provide the payout ID. That ID maps back to specific balance transactions, which map to specific orders, which map to specific customers. Complete lineage from bank statement through customer checkout.

Dispute resolution: A customer claims they were double-charged. You look up their order, find the related balance transaction, trace it to the payout that included it, and prove the funds were bundled with hundreds of other legitimate transactions. The payout ID on your bank statement corroborates the entire chain.

Reconciliation workflow

1. Export bank statement - Download CSV or connect via banking API
2. Extract payout IDs - Parse descriptors matching pattern ZCMRZ*po_*
3. Query Commerce API - Call Lookup a payout for each ID
4. Map to revenue - Use balance_transactions array to trace payout back to orders
5. Verify amounts - Confirm bank statement amount matches amount.value in API response
6. Mark reconciled - Record the match in your accounting system

For high-volume businesses processing dozens of payouts weekly, this automation saves hours of manual reconciliation and eliminates human error.

Can I cancel or modify a scheduled payout?

Yes, but only before execution begins.

Cancellation window

If payout status is scheduled (created but not yet processing), you can cancel it with Cancel a payout. The balance transactions are released back to your available balance immediately—they'll be eligible for the next payout run (automatic or manual).

After execution begins (processing or succeeded), cancellation is impossible. The transfer has been sent to the provider and cannot be recalled. If funds are transferred incorrectly, you must initiate a manual recovery transfer from the destination account back to Commerce.

No modification after creation

You cannot change payout parameters (amount, destination, timing) after creation. If you need different settings, cancel the original payout and schedule a new one with corrected parameters.

Why no modification? Payouts create immutable financial records. Allowing post-creation changes introduces audit complexity, reconciliation gaps, and potential for fraud. The cancel-and-recreate pattern maintains clear lineage and audit trails.

Cancellation use cases

Testing mistake - You scheduled a test payout to a production destination. Cancel it before execution, configure a test financial account, reschedule to the correct destination.

Amount error - You set max_amount to GHS 150,000 but meant GHS 15,000. Cancel before execution, reschedule with correct amount.

Timing change - You scheduled a payout for Friday but vendor payment deadline moved to Monday. Cancel, reschedule with updated execute_after time.

Destination change - You configured the wrong financial account as the currency destination. Cancel the payout, update destinations with Set payout destinations, trigger a new payout.

Why is my payout amount different than expected?

Several factors can cause the final payout amount to differ from your expectations.

Balance transaction eligibility

Only balance transactions that have aged at least 7 days are eligible. Recent payments (those that settled less than 7 days ago) remain in available balance but won't be included in the payout. Check includes_transactions_before in the Balances API response to see your snapshot cutoff—balance transactions created after that timestamp won't be included even if they're technically old enough.

Example: Today is Sunday (payout day). Transactions that settled Monday-Sunday last week are eligible (7+ days old). Transactions that settled this week aren't—they'll be included in next Sunday's payout.

Maximum amount limits

Your payout settings define minimum and maximum amounts per payout. If your available balance exceeds the maximum, the payout bundles transactions up to that limit and leaves the rest for the next payout run.

Check your limits with Lookup payout settings. If you consistently hit the maximum, consider requesting a limit increase by contacting support.

Balance state changes

Between payout creation and execution, balance state can change:

Reserved balance increases - Platform risk algorithms move funds from available to reserved, reducing the amount available for payout execution. This is automatic and based on real-time risk assessment.

Refunds processed - If you process customer refunds between payout scheduling and execution, those refunds consume available balance, reducing the amount transferred.

New payments settle - Payments that complete during the execution window might add to available balance, but they're excluded from the current payout if they haven't aged enough.

Currency conversion (FX payouts)

If you've enabled FX conversion (cross-currency payouts), the final amount reflects exchange rates at execution time, not creation time. Rates fluctuate throughout the day—the actual transferred amount may be slightly higher or lower than estimated.

See Payouts FX conversion for details on how exchange rates are applied and how to estimate final amounts.

Bundling algorithm

Automatic payouts bundle balance transactions in chronological order (oldest first) up to the maximum amount. If your available balance is GHS 150,000 but your limit is GHS 100,000, the payout includes the oldest GHS 100,000 worth of transactions. The remaining GHS 50,000 (newer transactions) stay in available balance for the next run.

Why oldest first? This maximizes the time funds have been outside the dispute window, minimizing risk. It also ensures consistent FIFO (first in, first out) accounting treatment for tax and audit purposes.

Should I use automatic or manual mode?

The right schedule depends on your cashflow patterns, operational complexity, and team capabilities.

Use automatic (weekly) mode if:

You want predictable, hands-off settlements - Funds arrive every Monday morning without any action from you. Your finance team knows to expect deposits on a consistent schedule. This is ideal for businesses that value operational simplicity over timing precision.

Your cashflow is stable - Weekly cadence provides enough liquidity for normal operations. You're not racing payroll deadlines or vendor payment schedules that require specific timing. Money arrives regularly and that's sufficient.

You have limited finance operations - Small teams benefit from automatic mode because it eliminates the need to monitor balances, trigger payouts, and manage timing manually. One less thing to remember, one less failure point.

You're new to Commerce - Start with automatic mode. It's the safest default. Switch to manual later if you discover specific timing needs that weekly payouts don't satisfy.

Use manual mode if:

You need precise timing control - Vendor contracts require Friday payments. Payroll runs Tuesday. Inventory purchasing happens monthly. Manual mode lets you align payout timing exactly with these obligations, pulling funds when you need them rather than when Commerce decides.

You operate in multiple currencies with different settlement timing - USD bank transfers take 2-3 days; GHS mobile money settles in minutes. Manual mode lets you trigger USD early in the week while pulling GHS instantly when you need it. Automatic mode treats all currencies the same.

You're testing new destinations - Before enabling automatic payouts to a new financial account, send a small manual test payout. Verify it arrives correctly, check the bank statement descriptor, confirm the amount matches. Then switch to automatic with confidence.

You have audit windows - Month-end reconciliation often requires a temporary freeze on disbursements. Manual mode lets you pause payouts during accounting closes without disrupting transaction processing. Resume payouts once reconciliation completes.

You want maximum control - Some businesses simply prefer explicit control over every financial movement. Manual mode gives you that—no surprises, no automatic transfers, complete visibility before every disbursement.

The hybrid approach

Many businesses start automatic, switch to manual for specific periods (testing, audits, cashflow crunch), then return to automatic. This flexibility is built into the platform—change modes anytime with Disable automatic payouts or Enable automatic payouts.

You can also run manual payouts while in automatic mode. Need emergency liquidity mid-week? Trigger a manual payout Tuesday; the automatic payout still runs Sunday for remaining eligible transactions. Manual payouts don't disable automatic ones—they work together.

How do I reconcile payouts with my accounting system?

Reconciliation is the process of matching bank deposits to the customer payments that generated them. Commerce provides multiple data points to make this straightforward.

The reconciliation chain

Every payout includes:

• Payout ID - Your lookup key (appears on bank statement as ZCMRZ*po_abc123)
• Balance transactions - Array of balance transaction IDs included in this payout
• Amount - Exact transferred value
• Destination - Which financial account received the funds
• Execution timestamp - When the transfer completed

Each balance transaction links back to:

• Order ID - The order that generated the payment
• Customer ID - Who paid
• Settlement timestamp - When funds became available
• Amount - How much this transaction contributed to the payout

Automated reconciliation workflow

1. Export bank statement data
Download your bank's CSV export or connect via banking API (Plaid, Yodlee, etc.). Extract line items showing deposits from Commerce (descriptor pattern ZCMRZ*).

2. Parse payout IDs
Extract payout IDs from descriptors using regex: ZCMRZ\*([a-zA-Z0-9_]+)

3. Query Commerce API
For each payout ID, call Lookup a payout to retrieve:

• Exact transferred amount
• Balance transaction IDs
• Execution timestamp
• Destination account

4. Fetch balance transaction details
For each balance transaction ID, call Balance Transactions API to get:

• Order ID
• Customer ID
• Original payment amount
• Settlement timestamp

5. Match to revenue records
Map order IDs back to your revenue database. Confirm the sum of balance transaction amounts equals the payout amount. Verify the bank statement amount matches the payout amount. Mark both sides as reconciled.

Manual reconciliation workflow

For smaller businesses without automated tooling:

1. Check bank statement
Find Commerce deposits (look for ZCMRZ* prefix). Copy the payout ID.

2. Look up in Commerce dashboard
Paste payout ID into dashboard search. View payout details: amount, date, included transactions.

3. Export transaction list
Download CSV of included balance transactions. Each row shows order ID, customer, amount, date.

4. Match to internal records
Import CSV into spreadsheet. Cross-reference order IDs with your order management system. Confirm total matches bank deposit.

5. Mark reconciled
Update your accounting system to reflect successful reconciliation. Note payout ID as the reconciliation reference.

Handling discrepancies

Bank amount doesn't match payout amount:

• Check for currency conversion (if FX payouts enabled)
• Verify you're looking at the right payout (multiple payouts same day?)
• Look for bank fees (rare, but some banks deduct wire fees)
• Contact support if discrepancy remains unexplained

Missing balance transactions:

• Check that you're querying the correct payout ID
• Verify balance transactions weren't refunded after payout
• Look for chargebacks that reversed transactions post-payout

Extra balance transactions:

• Confirm all included transactions are valid and settled
• Check for duplicate order processing (investigate immediately)
• Verify transaction timestamps are within expected payout window

Common questions

Can I change payout frequency?

Not directly. Commerce supports weekly (automatic) or manual (on-demand) schedules. There's no daily, monthly, or custom frequency option. However, in manual mode, you can establish your own cadence by triggering payouts on whatever schedule suits your business—daily, bi-weekly, monthly, or ad-hoc.

What if my destination account is closed?

Payouts to closed accounts fail with invalid_destination error. Update your payout destinations with Set payout destinations using an active financial account. If an automatic payout fails due to a closed account, Commerce pauses automatic payouts for that currency—you'll need to fix the destination and manually trigger the next payout.

Can I split payouts across multiple accounts?

Not in a single payout. Each currency maps to one destination at a time. However, you can change destination mappings between payout runs. For example: trigger a payout to Account A, update destinations to Account B, trigger another payout. The funds split across accounts, just not in a single transaction.

For more complex routing (split by percentage, route based on order metadata, distribute to multiple accounts), contact support to discuss custom payout strategies.

Why do balance transactions age for 7 days?

This is the dispute protection window. Most disputes, chargebacks, and fraudulent refund requests surface within 7 days of the original transaction. By holding funds for this period before making them available for payout, Commerce ensures you don't send money that you'll later need to return.

Without aging, you'd payout immediately after settlement—then face negative balance when a chargeback arrives days later. The 7-day buffer keeps your account solvent and your cashflow healthy.

Can I reduce the aging period for faster payouts?

No. The 7-day aging requirement is a risk management policy that protects both your business and the platform. Reducing it would increase chargeback exposure, dispute losses, and negative balance incidents.

Businesses with exceptional payment quality (low dispute rates, strong fraud prevention) can contact support to discuss customized aging rules, but this requires demonstrated history and additional risk assessment.

What happens if a payout fails after multiple retries?

The payout status becomes failed, failed_at timestamp is set, and latest_error contains diagnostic details. Balance transactions included in the failed payout are released back to your available balance—they'll be eligible for the next payout run (automatic or manual).

Review the error, resolve the underlying issue (fix destination account, wait for provider to recover, etc.), then either wait for the next automatic payout or manually trigger a new one.

Do payouts work on weekends and holidays?

Yes and no. Commerce creates payouts on schedule regardless of weekends or holidays (automatic payouts run every Sunday at midnight UTC). However, execution depends on your destination provider.

Mobile money: Usually processes 24/7 including weekends and holidays—expect normal settlement timing.

Banks: Often delay processing until the next business day. A payout initiated Sunday might not settle until Monday or Tuesday depending on the bank's schedule. Commerce initiates the transfer on time; the bank controls when funds actually arrive.

Public holidays: Banking holidays in the destination country can delay bank transfers by 1-2 days. Mobile money is usually unaffected.

Related resources

• Payouts API reference - Complete endpoint documentation
• Product Payouts - Conceptual overview of how payouts work
• Balances API - Understand available balance before triggering payouts
• Manage payout destinations - Connect and configure financial accounts
• Disable automatic payouts - Switch to manual mode
• Enable automatic payouts - Return to automatic weekly schedule