Key Concepts

This page explains the core concepts you need to understand when working with Orvion.

Organizations

Organizations are the top-level container for all resources in Orvion. They enable:

Multi-tenancy: Isolate data and resources per organization
Team collaboration: Share access with team members
Billing context: Track usage and billing per organization

Organization Members

Each user belongs to exactly one organization (enforced by database constraint). Each membership has:

Role: Owner, Admin, or Member
Permissions: Determined by role
Access: Scoped to the organization

Organization Scoping

All resources (invoices, flows, API keys) belong to an organization. When you make API calls:

Your API key is associated with an organization
All resources created belong to that organization
Row-level security (RLS) enforces organization boundaries

Flows & Routing

Flows are visual workflows that define how payments are processed. They enable:

Payment routing: Route payments to different connectors based on conditions
Automation: Trigger actions when events occur
Conditional logic: Handle different scenarios (success, failure, retry)

Flow Types

Payment routing: Route payments to connectors
Invoice automation: Automate invoice-related actions
Custom flows: Build your own workflows

Flow Components

Start nodes: Trigger when events occur
Route nodes: Route to different connectors
Condition nodes: Add conditional logic
Webhook nodes: Call external APIs
End nodes: Complete the flow

Agents & Wallets

Agents

Agents are autonomous systems that can:

Initiate payments: Create payment requests
Receive payments: Accept incoming payments
Execute workflows: Run flows based on events

Agents are identified by unique IDs and can be associated with wallets for settlement.

Wallets

Wallets store funds and enable:

Payment receipt: Receive payments from customers
Settlement: Transfer funds to agents or external wallets
Balance tracking: Monitor available funds

Wallets currently support Solana wallets via the dashboard UI. Additional payment rails are coming soon.

Payment Rails

Payment rails are the underlying payment networks. Orvion supports:

Lightning Network: Fast, low-cost Bitcoin payments
More coming soon: Additional rails are being added

Connectors

Connectors are integrations with specific payment rails. They:

Handle routing: Route payments to the correct rail
Manage credentials: Store API keys and secrets securely
Provide status: Report payment status and updates

Invoices

Invoices represent payment requests. They:

Track lifecycle: Draft → Sent → Paid/Overdue
Support multiple currencies: Fiat and cryptocurrency
Enable automation: Trigger flows and webhooks
Provide analytics: Track collection rates and trends

See the Invoices documentation for complete details.

Webhooks & Events

Webhooks deliver real-time events to your application:

Invoice events: created, sent, paid, overdue
Payment events: initiated, completed, failed
Flow events: started, completed, errored

Webhook Security

Webhooks are signed to ensure authenticity. Always verify signatures before processing events.

API Keys & Authentication

API keys authenticate your API requests:

Scoped to organization: Keys belong to a specific organization
Permissions: Control what the key can do
Rotation: Keys can be rotated for security

See API Keys documentation for details.

Environments

Orvion supports multiple environments:

Sandbox: For testing and development
Production: For live applications

Each environment has separate:

Organizations
API keys
Data
Connectors