Payouts

Payouts are the bridge between customer payments and the money your business can actually spend. When customers pay you through Commerce, those funds settle into your balance—but they don't automatically land in your bank account or mobile money wallet. Payouts handle that critical final step, moving settled funds from your Commerce balance to the financial accounts you've configured, following the timing rules and safeguards that protect both you and your customers.

Why payouts matter for your business

Getting paid is one thing. Getting paid predictably, safely, and on a schedule you can plan around—that's what makes the difference between cashflow chaos and cashflow confidence.

Predictable liquidity

When you know exactly when funds will arrive in your operating accounts, you can plan with precision. Need to pay suppliers on Friday? Schedule vendor payments knowing your payout hits your account Thursday evening. Managing payroll? Count on weekly settlements that arrive before pay day. Predictable payouts turn abstract balance numbers into real money you can deploy—at the right time, every time.

Risk protection that scales with you

Payouts aren't just about speed—they're about safety. By holding funds for a defined period before transferring them out, Commerce creates a buffer that protects you from late-arriving disputes, fraudulent chargebacks, and refund requests that surface days after the original transaction. This isn't an arbitrary delay—it's engineered protection that keeps your business solvent even when the unexpected happens.

Operational efficiency at scale

Imagine manually initiating a bank transfer for every customer payment. For high-volume businesses processing hundreds or thousands of transactions daily, that's impossible. Payouts solve this by bundling many small balance transactions into periodic disbursements. One payout might represent dozens or hundreds of customer payments, reducing banking fees, simplifying your financial records, and making month-end reconciliation something your accounting team can actually complete in a reasonable timeframe.

Compliance and audit trails

When auditors or regulators ask questions, you need answers—fast, complete, and unambiguous. Payouts provide that clarity. Every payout includes a complete list of the balance transactions it contains, creating an audit trail from customer payment through settlement. Your bank statement shows a single line item with a Commerce payout ID. That ID maps back to specific transactions, specific customers, specific orders. No guesswork, no gaps, no problems.

How payouts work

The payout lifecycle is designed to balance speed, safety, and simplicity. Understanding the flow helps you make informed decisions about scheduling, timing, and troubleshooting.

1. Customer payments settle

When a customer completes a payment, it begins as an authorized transaction. Within minutes to hours (depending on the payment method), that transaction settles—meaning the funds are confirmed, captured, and added to your available balance. These settled transactions become balance transactions, each tracked individually with its own ID, amount, and settlement timestamp.

2. Balance transactions age

Not all settled funds are immediately eligible for payout. Commerce enforces aging rules that require balance transactions to remain in your balance for a minimum period before they can be disbursed. This aging period—7 days for weekly payouts—creates the risk buffer that protects you from disputes, refunds, and chargebacks that might arrive after the original transaction.

The aging rule is strict: a transaction that settled today won't be eligible for payout until it has aged the full required period. This is intentional, non-negotiable protection for both your business and the platform.

3. Payouts are created (automatic mode) or triggered (manual mode)

In automatic mode, Commerce creates payouts on a schedule—every Sunday at midnight UTC for weekly payouts. The system checks your available balance, identifies all eligible balance transactions (those that have aged the minimum required period), and bundles them into a payout for each currency with a configured destination.

In manual mode, you control the timing. Call the /payouts/schedule API endpoint whenever you want to initiate a payout, specifying the destination, maximum amount, and optional execution time. Commerce validates your request, bundles eligible balance transactions up to your specified maximum, and queues the payout for execution.

4. Transfers execute with automatic retries

Once a payout is created and scheduled, Commerce initiates the actual transfer to your destination financial account. 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 the country-specific banking rails involved.

If a transfer fails due to transient issues (temporary network problems, provider timeouts), Commerce automatically retries with exponential backoff. Permanent failures (closed accounts, invalid account details) are surfaced immediately with detailed error information so you can resolve the underlying issue.

5. Reconciliation and audit

When the payout succeeds, you'll see the transfer appear in your destination account's transaction history with a descriptor formatted as ZCMRZ*PAYOUT_ID. The payout ID serves as your reconciliation key. Look up that payout via the Commerce API to see the exact list of balance transactions included, the total amount transferred, the execution timestamp, and any metadata relevant to your accounting processes.

For accounting teams, this means you can trace a specific bank deposit back through the payout to the individual customer payments that comprised it—complete lineage, complete clarity.

Payout schedules

Commerce offers two payout schedules, each optimized for different business needs and risk profiles. The schedule you choose determines when payouts run, how long funds must age before disbursement, and whether payouts happen automatically or only when you explicitly trigger them.

Weekly schedule (default)

The weekly schedule is the foundation of predictable cashflow for most Commerce merchants. Every Sunday at midnight UTC, Commerce creates automatic payouts for all eligible balance transactions—those that have aged at least 7 days. This means a transaction that settled on Monday becomes eligible for payout the following Monday (and will be included in the next payout that runs on Sunday).

Why weekly works for most businesses: The 7-day aging period strikes a careful balance between liquidity and risk protection. Seven days is long enough to catch the vast majority of disputes, refunds, and fraudulent chargebacks before funds leave your balance, but short enough that you're not left waiting weeks for access to your earnings. The Sunday execution timing takes advantage of quieter banking windows, reducing the chance of delays or processing issues.

For businesses with stable payment volumes, the weekly cadence creates a predictable rhythm. You know funds will arrive Monday morning (mobile money) or Tuesday-Wednesday (bank transfers). Your finance team can schedule obligations accordingly. Your accounting software can expect deposits on a consistent schedule. This predictability compounds over time into operational efficiency your team can rely on.

The weekly schedule is the default for all new Commerce accounts. We recommend staying with weekly unless you have specific needs that justify switching to manual mode.

Manual schedule

The manual schedule gives you complete control over payout timing by disabling automatic payout creation entirely. Funds accumulate in your balance until you explicitly trigger a payout via the Commerce API. Balance transactions still must age 7 days before they're eligible (same as weekly payouts), but you decide when within that eligibility window the payout actually happens.

When manual mode makes sense: Manual mode excels in situations requiring explicit timing control. Financial audits and month-end reconciliation often require a temporary freeze on disbursements—manual mode lets you pause outflows without disrupting transaction processing. Testing new financial accounts or payout destinations is safer in manual mode: trigger a small test payout, verify it arrives correctly, then resume normal operations. If your business has specific cashflow events (vendor payment schedules, payroll runs, inventory purchasing windows), manual mode lets you align payout timing precisely with those events.

Manual mode is also valuable for businesses operating in multiple currencies with different settlement timing needs. Trigger USD bank transfers early in the week to account for 2-3 day settlement, while pulling GHS mobile money instantly when you need it. This level of control isn't possible with automatic schedules.

The manual mode tradeoff: Control comes at the cost of convenience. You must remember to trigger payouts, monitor your balance for eligible transactions, and manage the timing yourself. Forget to trigger payouts for a few weeks and funds accumulate in your balance rather than reaching your operating accounts. This is manageable for businesses with strong financial operations, but can be problematic for teams that benefit from automatic weekly transfers.

How to enable manual mode: Call the /payouts/disable API endpoint to switch from automatic to manual mode. Your next automatic payout won't be created—instead, you'll trigger payouts on-demand with /payouts/schedule. Switch back to automatic mode anytime with /payouts/enable. See the Disable automatic payouts guide for complete instructions.

How payouts appear on bank statements

When a payout arrives in your destination account, you'll see it listed in your transaction history with a descriptor formatted as ZCMRZ*PAYOUT_ID. The prefix (ZCMRZ) is fixed across all payouts and identifies the transfer as coming from Commerce. The suffix is the unique payout ID—the same ID you'll see in the Commerce API when you look up payout details.

This stable, predictable format makes reconciliation straightforward. Your bank statement shows ZCMRZ*po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB. You search your Commerce records for payout ID po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB. The API returns the exact list of balance transactions included in that payout, the total amount, the execution timestamp, and any metadata you attached. You can trace that payout back to the individual customer payments that comprised it—complete audit trail, zero ambiguity.

For businesses with accounting software that supports automated reconciliation, this descriptor format is parsable and consistent. Build integrations that read bank statements, extract payout IDs, query the Commerce API for payout details, and automatically match deposits to the underlying transactions. What would otherwise be hours of manual reconciliation becomes minutes of automated verification.

Payout destinations and currency routing

Payouts need to know where to send funds. In Commerce, this is handled through destination mappings: for each currency you accept, you specify which financial account should receive payouts in that currency. A destination is simply a financial account you've connected to Commerce—a mobile money wallet, a bank account, or another type of financial account Commerce supports.

Setting up destinations

Before automatic payouts can run (or before you can trigger manual payouts), you need to configure at least one destination. This is a two-step process:

Step 1: Connect your financial accounts. Use the /financial_accounts/connect API endpoint to add your existing financial accounts to Commerce. This establishes ownership (Commerce verifies the account belongs to you) and enables push operations (so Commerce can send funds to the account).

Step 2: Map currencies to accounts. Use the /payouts/set_destinations endpoint to specify which financial account should receive payouts for each currency. For example, map ghs to your MTN Mobile Money account, map usd to your USD bank account. Each currency can have one active destination at a time.

Once destinations are configured, payouts route automatically. Automatic payouts use the destination mappings without additional input from you. Manual payouts default to the configured destinations, though you can override the destination for a specific payout by specifying a destination_id explicitly in the /payouts/schedule call.

Currency matching is enforced: You can't route a GHS payout to a USD bank account. Commerce validates that the destination account's currency matches the payout currency—if they don't match, the configuration is rejected. This prevents costly currency conversion mistakes and ensures funds always arrive in the expected currency.

Supported currencies and expansion

Today, Commerce actively supports Ghanaian cedi (ghs) for payout operations. As we expand to additional markets and currencies, each new currency will follow the same pattern: connect a financial account denominated in that currency, map the currency code to the account, and payouts flow automatically.

When new currencies launch, you'll receive notification through the Commerce dashboard and API changelog. Adding support for a new currency requires no changes to your payout logic—the same destination mapping pattern applies regardless of which currencies you operate in.

Cross-currency payouts: If you need to consolidate multiple currencies into a single account or hold funds in a different currency than the transaction currency, see the Payouts FX conversion guide for information on enabling foreign exchange conversion.

For complete details on connecting financial accounts and configuring destinations, see the Manage payout destinations guide.