Invoicing Profiles

Invoicing Profiles define how invoices should be collected and how funds should be distributed. They provide a reusable configuration template per network/asset combination.

What are Invoicing Profiles?

An Invoicing Profile is a configuration template that defines:

Payment rail settings: Network, asset, wallet addresses
Collection mode: Direct (payments go to seller) vs Escrow (payments go to Meshpay settlement wallet)
Features: Partial payment support
Payout splits: How funds are divided between beneficiaries (merchant, platform, partners)
Metadata: Default descriptions and tags for x402 payments

Why Use Profiles?

Profiles simplify invoice creation:

Reusable configuration: Set up payment rails once, use for many invoices
Consistent splits: All invoices using a profile share the same payout behavior
Network/asset organization: One profile per network/asset combination
Default profiles: Set a default profile to auto-select for new invoices

Profile Structure

Basic Information

Name: Human-readable profile name (e.g., "USDC Solana Mainnet Profile")
Network: Blockchain network (e.g., base-mainnet, solana-mainnet)
Asset: Token/currency (e.g., USDC, USDT)

Payment Rail Configuration

Pay-to Address: Seller's payout wallet (where funds go after collection)
Escrow Address: Meshpay settlement wallet (only for escrow mode)
Facilitator: x402 facilitator endpoint URL
Max Timeout: Maximum seconds to complete payment

Collection Mode

Profiles support two collection modes:

Direct Mode (collection_mode: "direct"):

Payments go directly to seller's pay_to_address
No escrow wallet needed
Faster settlement, simpler flow

Escrow Mode (collection_mode: "escrow"):

Payments go to Meshpay escrow_address
Funds are then distributed according to payout splits
Required for on-chain splits or complex payout logic

Payout Splits

Profiles define default payout splits that are copied to invoices at creation:

Beneficiary Address: Wallet address to receive payout
Label: Role identifier (e.g., "merchant", "platform_fee", "partner")
Share Type: Percentage or fixed amount
Share Value: The percentage (0-100) or fixed amount
Priority: Ordering for deterministic rounding

Example splits:

90% to merchant wallet
10% to platform fee wallet

Creating a Profile

Via Dashboard

Navigate to Invoices → Invoicing Profiles
Click Create Profile
Fill in network, asset, wallet addresses
Choose collection mode (direct or escrow)
Configure payout splits if needed
Set as default if desired

Via API

POST /v1/invoicing-profiles
{
  "name": "USDC Solana Mainnet Profile",
  "network": "base-mainnet",
  "asset": "USDC",
  "pay_to_address": "0x...",
  "escrow_address": "0x...",  // Required for escrow mode
  "collection_mode": "escrow",
  "supports_partial_payments": true,
  "is_default": true
}

Using Profiles with Invoices

When creating an invoice, specify a profile_id:

POST /v1/invoices
{
  "customer_name": "Acme Corp",
  "amount": "1000.00",
  "currency": "USDC",
  "profile_id": "profile_123..."
}

The invoice will:

Snapshot x402 config from the profile
Copy payout splits to the invoice (then lock after first payment)
Use profile's collection mode to determine x402 pay_to_address

Default Profiles

You can set one default profile per network/asset combination. When creating an invoice without specifying a profile_id, the system will use the default profile for that network/asset.

Profile Splits vs Invoice Splits

Profile splits: Template configuration, can be edited anytime
Invoice splits: Copied from profile at creation, locked after first settled payment

This ensures consistency: all invoices using a profile share the same split behavior, but each invoice's splits are frozen once payments start.