Payouts & Seller Settlements

1. Payout account management

Each seller connects a payout account that represents their relationship with the payment provider:

• Stores the seller’s external account ID in the provider system (for example, Stripe Connect account ID).
  
  
• Tracks account status such as pending, active, or disabled.
  
  
• Holds provider-specific data and an associated onboarding record.
  
  
• Maintains a history of payouts executed for that account.
  
  

Every seller must have a verified payout account with status active before funds are transferred.

‍

2. Payout account status

Payout accounts can transition through clear states:

• Pending
  
  • Account exists, but the seller has not finished verification.
    
    
  • Additional information such as business details, bank account, and identity must be provided.
    
    
• Active
  
  • Account is fully verified and authorized to receive payouts.
    
    
  • Seller has completed all onboarding steps with the payment provider.
    
    
• Disabled
  
  • Account has been deactivated by the seller, marketplace operator, or provider.
    
    
  • No payouts are allowed while disabled.
    
    

These states determine whether payouts can be created for a given seller.

‍

3. Seller onboarding flow

A guided onboarding process ensures that only verified sellers receive funds:

1. Create payout account: Seller starts the process from the vendor panel.‍
2. Initialize onboarding: System creates an onboarding record and generates an onboarding URL from the payment provider (for example, Stripe Connect onboarding link).‍
3. Complete verification: Seller completes identity and business verification on the provider’s platform.‍
4. Webhook callback: Provider sends a webhook notifying that the account has been authorized or requires additional actions.‍‍
5. ‍Account activation: Payout account status is updated to active via the webhook handler once verification is complete.
   
   

The onboarding record stores provider-specific data such as onboarding URL and session IDs, plus context like redirect URLs.

‍

4. Payout lifecycle

A payout represents a money transfer from the marketplace to a seller:

• Payouts are created automatically by the system, not manually by sellers.
  
  
• They are triggered when:
  
  • An order is completed,
    
    
  • The seller’s payout account is active,
    
    
  • The marketplace commission has been calculated.
    
    

A payout includes:

• Amount to be transferred to the seller.
  
  
• Currency code for the transfer.
  
  
• Provider transfers data, such as the Stripe transfer ID.
  
  
• A reference to the payout account and related orders or items.
  
  

This creates a clear audit trail that ties payouts back to business activity.

5. Payout reversals

Handle refunds and chargebacks without losing track of balances:

• When customers receive refunds, payout reversals are created to deduct the appropriate amount from the seller’s side of the transaction.
  
  
• Reversals reference the original payout and reflect adjustments necessary to keep seller balances correct.
  
  
• This is especially important when using providers like Stripe, where refunds and transfers interact in specific ways.
  
  

The result is a consistent, auditable balance for each seller, even in complex refund scenarios.

‍

6. Webhook processing and status sync

Stay in sync with your payment provider in real time:

• Webhooks from the provider are used to handle asynchronous payout events, such as:
  
  • account_authorized
    
    
  • account_deauthorized
    
    
  • account_requires_action
    
    
• Mercur’s payout-webhook subscriber listens for these events, validates payloads, and runs the right workflow to:
  
  • Update payout account status,
    
    
  • Handle disconnections or required actions.
    
    

This eliminates manual reconciliation and keeps your system aligned with Stripe Connect or other providers.

‍

7. Automated payout schedule

Let the system pay out sellers on autopilot:

• A scheduled job, such as daily-payouts, runs every day at midnight (or at your configured time) to process pending payouts.
  
  
• The job:
  
  1. Queries the database for orders that should result in payouts but do not have payouts yet.
     
     
  2. Batch orders in groups (for example, 100 at a time) to maintain performance.
     
     
  3. Emits payout events with staggered delays to avoid overwhelming the payment provider.
     
     
  4. Triggers the payout creation workflow for each batch.
     
     
  5. Retries failed events up to a configured number of times.
     
     

This ensures regular, predictable payouts without manual intervention.

‍

8. Multi-currency and international payouts

Support global marketplaces and local currencies:

• Payouts can be created in different currencies, as supported by your payment provider.
  
  
• Combined with Mercur’s Price Lists and regional setup, this allows international marketplaces to pay sellers in their local currency where possible.
  
  
• Multi-currency behavior is handled within the payout workflows and provider integration.
  
  

This is critical when you operate across multiple countries with different settlement currencies.