Escrow with Revenue Splits

A marketplace sells data from multiple providers. For each invoice:

• 90% goes to the data seller
• 10% goes to the marketplace
• Funds land in Meshpay's escrow wallet first, then are split automatically

What You'll Build

• Create an escrow-mode invoicing profile
• Configure payout splits (90% seller, 10% platform)
• Issue invoices on behalf of data providers
• Track payments and payouts

Prerequisites

Wallet addresses for marketplace and data provider should be available. For Solana wallets, you can connect them via the dashboard at Account → Wallets. For other networks (Base, Ethereum, etc.), you can use wallet addresses directly in invoicing profiles.

In this example:

• Marketplace: 0xMARKETPLACE_BASE_WALLET
• Data Provider: 0xDATA_PROVIDER_BASE_WALLET

Step 1: Create Profile with Escrow Mode

Create a profile that collects payments to the Meshpay escrow wallet:

import requests

url = "https://api.orvion.com/api/v1/invoicing-profiles"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {
  "name": "Data Marketplace – Base USDC – 10% fee",
  "network": "base-mainnet",
  "asset": "USDC",
  "collection_mode": "escrow",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE",
  "supports_partial_payments": True,
  "default_description": "Pay marketplace data invoice in Base USDC",
  "default_tags": ["data", "marketplace"]
}

response = requests.post(url, json=data, headers=headers)
profile = response.json()
print(f"Profile created: {profile['id']}")

Response:

{
  "id": "profile_01HABC456DEF",
  "name": "Data Marketplace – Base USDC – 10% fee",
  "network": "base-mainnet",
  "asset": "USDC",
  "collection_mode": "escrow",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE",
  "supports_partial_payments": true,
  "is_active": true,
  ...
}

Step 2: Configure Payout Splits

Set up the 90/10 revenue share:

import requests

url = "https://api.orvion.com/api/v1/invoicing-profiles/profile_01HABC456DEF/splits"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

splits = [
  {
      "beneficiary_address": "0xDATA_PROVIDER_BASE_WALLET",
      "beneficiary_org_id": "org_data_provider",
      "label": "merchant",
      "share_type": "percentage",
      "share_value": 90.0,
      "priority": 1
  },
  {
      "beneficiary_address": "0xMARKETPLACE_BASE_WALLET",
      "beneficiary_org_id": "org_marketplace",
      "label": "platform_fee",
      "share_type": "percentage",
      "share_value": 10.0,
      "priority": 2
  }
]

response = requests.put(url, json=splits, headers=headers)
result = response.json()
print(f"Configured {len(result)} splits")

Response:

[
  {
    "id": "split_01HXYZ111AAA",
    "profile_id": "profile_01HABC456DEF",
    "beneficiary_address": "0xDATA_PROVIDER_BASE_WALLET",
    "beneficiary_org_id": "org_data_provider",
    "label": "merchant",
    "share_type": "percentage",
    "share_value": "90.00",
    "priority": 1,
    "created_at": "2025-01-15T10:05:00Z"
  },
  {
    "id": "split_01HXYZ222BBB",
    "profile_id": "profile_01HABC456DEF",
    "beneficiary_address": "0xMARKETPLACE_BASE_WALLET",
    "beneficiary_org_id": "org_marketplace",
    "label": "platform_fee",
    "share_type": "percentage",
    "share_value": "10.00",
    "priority": 2,
    "created_at": "2025-01-15T10:05:00Z"
  }
]

Split Configuration Options

| Field | Description | |-------|-------------| | beneficiary_address | Wallet address to receive payout | | beneficiary_org_id | Optional organization ID for tracking | | label | Role identifier: merchant, platform_fee, partner | | share_type | percentage or fixed | | share_value | Percentage (0-100) or fixed amount | | priority | Order for deterministic rounding |

Step 3: Create Invoice on Behalf of Provider

The marketplace creates an invoice for the data provider:

curl -X POST https://api.orvion.com/api/v1/invoices \
-H "Authorization: Bearer marketplace-api-key" \
-H "Content-Type: application/json" \
-d '{
  "customer_name": "End Customer",
  "customer_email": "[email protected]",
  "amount": 20000.00,
  "currency": "EUR",
  "description": "Dataset Y annual access",
  "profile_id": "profile_01HABC456DEF",
  "status": "sent"
}'

Response:

{
  "id": "inv_01HMARKETPLACE",
  "number": "INV-2025-0003",
  "customer_name": "End Customer",
  "amount": "20000.00",
  "currency": "EUR",
  "status": "sent",
  ...
}

The invoice service automatically:

• Loads the escrow profile
• Snapshots x402 config to the invoice
• Copies profile splits to invoice_payout_splits
• Marks invoice as x402_payable = true

Step 4: Verify Profile with Splits

Get the complete profile configuration:

curl -X GET https://api.orvion.com/api/v1/invoicing-profiles/profile_01HABC456DEF/with-splits \
-H "Authorization: Bearer your-api-key"

Step 5: View Payments and Payouts

Coming Soon: Payment history endpoint

GET /api/v1/invoices/{invoice_id}/payments

Coming Soon: Payout ledger endpoint

GET /api/v1/payment-payouts

Current Workflow:

• View payments in dashboard: Money → Collections → Payments
• View payouts in dashboard: Money → Payouts → Payouts

Payment Flow Example

For a 20,000 EUR payment:

1. Buyer pays → 20,000 USDC to escrow wallet
2. Meshpay verifies → Creates invoice payment record
3. Splits applied → Based on profile configuration
4. Payouts sent:
   • 18,000 USDC → 0xDATA_PROVIDER_BASE_WALLET (90%)
   • 2,000 USDC → 0xMARKETPLACE_BASE_WALLET (10%)

The marketplace doesn't need to wire anything manually — profile holds the default splits, invoice freezes them per deal, payout flow uses the invoice splits.

Next Steps

• Changing Payout Configuration - Update splits
• Partial Payments - Accept instalments