Payment Receiving Guide

This guide walks through real-world scenarios for payment receivers using Meshpay to collect payments and manage payouts. Each scenario includes complete curl examples for all API operations.

Overview

Payment receivers use Meshpay to:

Accept payments for data products and subscriptions
Configure payout rules (direct or escrow with splits)
Track invoices, payments, and payouts
Generate analytics and reports

Prerequisites

Before following any tutorial, ensure you have:

An Orvion account and organization
An API key with invoices:create, invoices:read, and profiles:write permissions
Base URL: https://api.orvion.com (or your localhost for development)

Tutorials

Direct Payout Setup

Get paid directly to your wallet with no fee sharing

Create invoicing profile
Issue your first invoice
Track payment status

Escrow with Revenue Splits

Marketplace setup with automatic revenue sharing

Configure escrow collection
Set up payout splits (90/10)
Invoice on behalf of sellers

Changing Payout Configuration

Update how you get paid for future invoices

Switch from direct to escrow
Add platform fees
Update split percentages

Partial Payments

Accept instalments for large contracts

Enable partial payment support
Create instalment invoices
Track payment progress

Analytics & Reporting

Monitor your data sales performance

List and filter invoices
View revenue summaries
Generate timeseries reports

API Reference Summary

Invoicing Profiles

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/v1/invoicing-profiles | Create profile | | GET | /api/v1/invoicing-profiles | List profiles | | GET | /api/v1/invoicing-profiles/{id} | Get profile | | PUT | /api/v1/invoicing-profiles/{id} | Update profile | | DELETE | /api/v1/invoicing-profiles/{id} | Delete profile | | PUT | /api/v1/invoicing-profiles/{id}/splits | Set payout splits | | GET | /api/v1/invoicing-profiles/{id}/splits | Get splits | | GET | /api/v1/invoicing-profiles/{id}/with-splits | Get profile with splits |

Invoices

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/v1/invoices | Create invoice | | GET | /api/v1/invoices | List invoices | | GET | /api/v1/invoices/{id} | Get invoice | | POST | /api/v1/invoices/{id}/mark-paid | Mark as paid | | DELETE | /api/v1/invoices/{id} | Delete invoice | | POST | /api/v1/invoices/{id}/cancel | Cancel invoice |

Analytics

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/invoices/analytics/summary | Summary KPIs | | GET | /api/v1/invoices/analytics/revenue-timeseries | Revenue over time |

Coming Soon

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/invoices/{id}/payments | Invoice payment history | | GET | /api/v1/payment-payouts | Payout ledger |

Best Practices

Profile Organization: Create one profile per network/asset combination
Default Profiles: Set is_default: true for your most common profile
Split Configuration: Configure splits at profile level, not per invoice
Partial Payments: Enable only when needed (large contracts, instalments)
Escrow Mode: Use escrow when you need on-chain splits or complex payout logic
Direct Mode: Use direct for simple, single-wallet payouts