API Billing (v1 – Simple Charges API)

API Billing lets your backend create billable charges for your customers with a single HTTP call.

You:

• Configure where to receive payments (Receiver Configs)
• Get an API key
• Call POST /v1/charges with the final amount you want to charge
• Verify payments with POST /v1/charges/verify before showing content
• Receive webhooks when payments succeed or fail
• See all charges under API Billing → Transactions and in your payout ledger

Meshpay does not calculate your prices. Your backend always decides the amount.

Core Concepts

Organization

Your account / company in Meshpay. All charges and transactions belong to an organization.

Receiver Configs

Configure where and how you want to receive payments. Define blockchain network, asset, and wallet address. You can create multiple configs and set a default.

Transaction (billing_transactions)

A single charge created for one of your customers via the billing API. Each charge returns x402 payment requirements that buyers use to pay on-chain.

API Key (api_keys)

Secret key used to authenticate your server → Meshpay calls. There is no sandbox/live split in v1. If you want to "test", just use small amounts or your staging Meshpay account.

Billing Flows (Coming Soon)

Advanced grouping with flowcharts and conditional logic. For now, you can create standalone charges without flows.

Quick Start

Four-Step Workflow

1. Get an API Key - Go to Developers / Settings → API keys and create a server-side key
2. Create a Receiver Config - Configure where to receive payments (or use connected Solana wallet)
3. Create Charges - Call POST /v1/charges with amount, currency, and payment config
4. Verify & Deliver - Call POST /v1/charges/verify to confirm payment before showing content

Payment & Payout Flow

Your backend calls POST /v1/charges with the final amount. Meshpay:

1. Resolves x402 payment configuration (receiver config → default → connected wallet)
2. Returns x402 payment requirements to your API
3. Buyer pays on-chain using the x402 requirements
4. Facilitator webhook confirms the payment
5. Transaction status updates to succeeded
6. Your backend receives webhook (billing.transaction.succeeded)
7. Your backend verifies via POST /v1/charges/verify before showing content
8. Payouts module uses these transactions for settlement

You don't need to manage ledgers or reconciliation manually – just create charges; Meshpay handles aggregation and payout logic.

Seller Integration Patterns

402 Mode (API Clients)

User Request → 402 Payment Required → User Pays → Verify Payment → Show Content
                     ↓                              ↓
              Create Charge                  /v1/charges/verify
              (returns x402)                 (returns verified: true)

Hosted Checkout Mode (Web Apps)

User Request → Redirect to pay.orvion.sh → User Pays → Redirect Back → Verify → Show Content
                        ↓                                    ↓
                  Wallet Connect                      ?charge_id=xxx
                  USDC Payment                        &status=succeeded

For sellers accepting payments:

• 402 Mode: Best for API clients and programmatic access
• Hosted Checkout: Best for web apps with browser-based users
• Real-time verification: Call /v1/charges/verify before showing paid content
• Background processing: Receive billing.transaction.succeeded webhooks for bookkeeping

See the Seller Integration Guide and Hosted Checkout Guide for complete examples.

Documentation Pages

Related Documentation

• API Keys & Auth - Managing API keys
• Payouts Overview - Understanding payout distribution
• Collections Overview - Payment collection concepts