Routing Flows

Routing Flows define how payments are processed and routed through your system. They can group charges, define conditions, configure receivers, and set up payout rules. Examples include "Image API Usage", "Premium Feature X", or "Data Processing". Flows control whether charges are active or paused.

How Routing Flows Work with Protected Routes

When you use Protected Routes (via the SDK's @require_payment decorator), routing flows can automatically provide payment configuration:

• Each protected route has its own amount stored in the protected_routes table
• If you have an active routing flow with an api_request_entry node, protected routes will automatically use that flow for payment configuration (network, asset, receiver)
• If there's no active routing flow, routes use standalone charges with their receiver_config_id

Key Point: The route's amount always comes from the protected_routes table. Routing flows only determine the payment configuration (network, asset, receiver), not the amount itself.

For more details, see the Protected Routes documentation.

Step 1 – Get an API Key

Go to the dashboard and open Developers / Settings → API keys (where you already manage keys). Create a server-side key if you don't have one. Store this key securely as ORVION_API_KEY in your backend.

You will use this key in the Authorization header:

Authorization: Bearer <ORVION_API_KEY>

Step 2 – Create a Routing Flow

You can create flows via dashboard or API.

Option A – Dashboard

1. Go to Routing Flows in the sidebar
2. Click New Flow
3. Fill in:
   • Name – e.g. "Image API Usage"
   • Description – optional
4. Click Create Routing Flow

You'll be redirected to the Flow detail page with the Builder tab open, where you can configure routing conditions and payout rules. You can also access API Access and Test Requests tabs.

Option B – API

Request Body

Code Examples

import requests
import os

url = "https://api.orvion.sh/v1/billing/flows"
headers = {
  "Authorization": f"Bearer {os.environ['ORVION_API_KEY']}",
  "Content-Type": "application/json"
}

data = {
  "name": "Image API Usage",
  "description": "Charges per processed image.",
  "accounting_currency": "EUR"  # Optional - for reporting only
}

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

Response

Returns the created flow object:

{
  "id": "flow_123",
  "name": "Image API Usage",
  "description": "Charges per processed image.",
  "accounting_currency": "EUR",
  "status": "active",
  "created_at": "2025-11-27T12:00:00Z"
}

Save the id (e.g. flow_123) – you'll use it as flow_id in charge calls.

Flow Properties

Status

Flows can be in one of two states:

• active (default) - Charges can be created for this flow
• paused - Charges are blocked (returns 403 when attempting to create charges)

Fields

• id - Unique identifier for the flow (e.g., flow_123)
• name - Display name for the flow
• description - Optional description
• accounting_currency - Optional currency code for reporting/analytics (does NOT constrain charge currencies). Can be set via API but not shown in dashboard UI.
• status - Current status (active or paused)
• organization_id - Organization that owns this flow
• created_at - Timestamp when the flow was created

Error Scenarios

400 Bad Request

• Missing required field (name)
• Invalid JSON in request body

401 Unauthorized

• Missing or invalid API key
• API key does not have permission to create flows

422 Unprocessable Entity

• Invalid accounting_currency format
• Validation errors

Next Steps

• Create your first charge using the flow ID
• View transactions for this flow
• Test charges from the dashboard

Related Documentation

• API Billing Overview - Core concepts
• Charges API - Creating charges for a flow
• Transactions - Viewing flow transactions