Changing Payout Configuration

A seller used to get paid directly. Now they want everything via escrow with a small platform fee. This change applies to future invoices only — existing invoices keep their original payout behavior.

What You'll Learn

• Update an existing profile's collection mode
• Add or modify payout splits
• Understand how changes affect existing vs new invoices

Step 1: Update Profile to Escrow Mode

Change the collection mode and escrow address:

import requests

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

data = {
  "collection_mode": "escrow",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE"
}

response = requests.put(url, json=data, headers=headers)
profile = response.json()
print(f"Updated profile: {profile['collection_mode']}")

Response:

{
  "id": "profile_01HXYZ123ABC",
  "name": "Data Sales – Base USDC",
  "collection_mode": "escrow",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE",
  "is_active": true,
  "updated_at": "2025-01-20T14:30:00Z",
  ...
}

Step 2: Add Payout Splits

Configure a 95/5 split (seller gets 95%, platform gets 5%):

import requests

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

splits = [
  {
      "beneficiary_address": "0xSELLER_BASE_WALLET",
      "label": "merchant",
      "share_type": "percentage",
      "share_value": 95.0,
      "priority": 1
  },
  {
      "beneficiary_address": "0xMESHPAY_PLATFORM_WALLET",
      "label": "platform_fee",
      "share_type": "percentage",
      "share_value": 5.0,
      "priority": 2
  }
]

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

Response:

[
  {
    "id": "split_01HNEWSPLIT1",
    "profile_id": "profile_01HXYZ123ABC",
    "beneficiary_address": "0xSELLER_BASE_WALLET",
    "label": "merchant",
    "share_type": "percentage",
    "share_value": "95.00",
    "priority": 1,
    "created_at": "2025-01-20T14:35:00Z"
  },
  {
    "id": "split_01HNEWSPLIT2",
    "profile_id": "profile_01HXYZ123ABC",
    "beneficiary_address": "0xMESHPAY_PLATFORM_WALLET",
    "label": "platform_fee",
    "share_type": "percentage",
    "share_value": "5.00",
    "priority": 2,
    "created_at": "2025-01-20T14:35:00Z"
  }
]

Step 3: Verify Configuration

Get the complete profile with splits:

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

Response:

{
  "id": "profile_01HXYZ123ABC",
  "name": "Data Sales – Base USDC",
  "network": "base-mainnet",
  "asset": "USDC",
  "collection_mode": "escrow",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE",
  "is_active": true,
  "splits": [
    {
      "beneficiary_address": "0xSELLER_BASE_WALLET",
      "label": "merchant",
      "share_type": "percentage",
      "share_value": "95.00",
      "priority": 1
    },
    {
      "beneficiary_address": "0xMESHPAY_PLATFORM_WALLET",
      "label": "platform_fee",
      "share_type": "percentage",
      "share_value": "5.00",
      "priority": 2
    }
  ]
}

How Changes Affect Invoices

Existing Invoices

Old invoices keep their original payout behavior:

• They have their own invoice_payout_splits snapshot
• Profile changes do not affect them
• Payments continue to flow as originally configured

New Invoices

New invoices use the updated configuration:

• Created with escrow collection mode
• Splits snapshot from the updated profile
• 95% to seller, 5% to platform

Alternative: Create a New Profile

Instead of modifying an existing profile, you can create a dedicated profile:

curl -X POST https://api.orvion.com/api/v1/invoicing-profiles \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Data Sales – Base USDC (Escrow 95/5)",
  "network": "base-mainnet",
  "asset": "USDC",
  "pay_to_address": "0xMESHPAY_ESCROW_BASE",
  "escrow_address": "0xMESHPAY_ESCROW_BASE",
  "collection_mode": "escrow",
  "supports_partial_payments": false,
  "is_default": true
}'

Then configure splits on the new profile. This approach:

• Keeps the old profile intact for reference
• Makes it easy to switch between configurations
• Provides clear separation between direct and escrow invoices

Modifying Splits Later

To update split percentages, call PUT /splits again with the new configuration:

curl -X PUT https://api.orvion.com/api/v1/invoicing-profiles/profile_01HXYZ123ABC/splits \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '[
  {
    "beneficiary_address": "0xSELLER_BASE_WALLET",
    "label": "merchant",
    "share_type": "percentage",
    "share_value": 92.0,
    "priority": 1
  },
  {
    "beneficiary_address": "0xMESHPAY_PLATFORM_WALLET",
    "label": "platform_fee",
    "share_type": "percentage",
    "share_value": 8.0,
    "priority": 2
  }
]'

This replaces all existing splits with the new configuration.

Next Steps

• Partial Payments - Accept instalments
• Analytics & Reporting - Monitor sales