Payouts Overview

Payouts is the money out layer of Meshpay. It covers how collected funds are distributed to wallets after payments are received.

What are Payouts?

Payouts answer the question:

"Given collected funds from invoice payments, how do we distribute them to wallets?"

Payouts include:

Payout Ledger: Records of funds distributed to beneficiaries
Payout Splits: Configuration for dividing funds (merchant, platform, partners)
Payout Automations: Optional workflows for batched payouts, routing logic

Collection Modes and Payouts

Direct Mode

In direct collection mode:

Payments go directly to seller's pay_to_address
No payout splits applied on-chain
Meshpay just verifies and records the transaction

Escrow Mode

In escrow collection mode:

Buyer pays → funds land in Meshpay settlement wallet
Meshpay verifies transaction and creates Invoice Payment
Meshpay looks up payout rules (splits from profile)
Meshpay creates Payment Payouts (e.g., 90% to seller, 10% to platform)
Meshpay sends payouts to respective wallets

Escrow mode is required for on-chain splits or complex payout logic.

Payout Splits

Splits define how funds are divided:

Percentage splits: e.g., 90% merchant, 10% platform
Fixed splits: e.g., $5 platform fee, remainder to merchant
Multiple beneficiaries: Merchant, platform, partners

Splits are configured at the Invoicing Profile level and copied to invoices at creation. Once an invoice has a settled payment, its splits are locked.

Payment Payouts

Each payout leg is tracked as a Payment Payout:

Amount: Payout amount (calculated from split)
Beneficiary Address: Wallet address receiving funds
Label: Role identifier (merchant, platform_fee, partner)
Status: pending, settled, failed
Transaction Hash: On-chain payout transaction

Payout Automations

Payout automations are optional workflows built with flows (type: payout):

Batched Payouts: Group multiple payouts for efficiency
Threshold-based: Trigger payouts when balance reaches threshold
Multi-wallet Routing: Route payouts via different wallets/bridges
Dynamic Fee Logic: Adjust splits based on plans, tiers, or partner-specific rules

Basic payouts work without automations. Automations add advanced orchestration on top.