n8n-nodes-orvion

This is an n8n community node for Orvion - the payment orchestration platform for AI agents.

Create payment charges and receive checkout_url for payment collection. Perfect for:

• AI agent workflows that need to charge for services
• Automated billing flows
• Pay-per-use API integrations
• Crypto/stablecoin payment collection

Installation

In n8n (Recommended)

1. Go to Settings > Community Nodes
2. Click Install
3. Enter n8n-nodes-orvion
4. Click Install

Manual Installation

npm install n8n-nodes-orvion

Prerequisites

1. An Orvion account (sign up here)
2. An API key from your Orvion dashboard (Settings > API Keys)

Credentials

1. In n8n, go to Credentials > New
2. Search for "Orvion API"
3. Enter your API key
4. (Optional) Override the Base URL if testing with a local backend instance

Nodes

This package provides 2 nodes:

| Node | Type | Description | |------|------|-------------| | Orvion | Action | Create charges with optional "Wait for Payment" feature | | Orvion Trigger | Trigger | Receive webhook events when payments succeed/fail |

Orvion Node (Action)

Wait for Payment (Recommended)

The Wait for Payment feature allows you to create a charge and automatically pause the workflow until the customer pays. This enables a single-workflow pattern where:

1. Your workflow creates a charge
2. Workflow pauses (status: "Waiting...")
3. Customer pays on the checkout page
4. Workflow resumes automatically with payment data
5. Your business logic continues

Enable "Wait for Payment":

| Field | Required | Description | |-------|----------|-------------| | Wait for Payment | No | Toggle ON to pause workflow until payment completes | | Amount | Yes | Charge amount (e.g., 0.50) | | Currency | Yes | Currency code (default: USDC) | | Flow Slug | No | Billing flow for x402 config | | Customer Ref | No | Your customer identifier | | Resource Ref | No | Resource being purchased | | Notify Email | Yes | Email to send checkout URL to |

Output after payment:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "charge_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "is_paid": true,
  "is_pending": false,
  "is_failed": false,
  "amount": "0.50",
  "currency": "USDC",
  "tx_hash": "5nwz8X3Lgf8dqwV8EKQ2...",
  "payer_address": "0x1234...5678",
  "confirmed_at": "2025-01-08T12:00:00Z"
}

Create Charge (Without Wait)

If "Wait for Payment" is OFF, the node creates a charge and immediately returns with the checkout_url. Use this when you prefer the 2-workflow pattern with Orvion Trigger.

Output (immediate):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "amount": "0.50",
  "currency": "USDC",
  "checkout_url": "https://pay.orvion.sh/checkout/550e8400-..."
}

2. Check Payment

Check payment status with optional reference validation. Returns is_paid boolean for easy workflow branching.

| Field | Required | Description | |-------|----------|-------------| | Charge ID | Yes | The charge ID to check (use {{ $json.charge_id }} from Create Charge) | | Expected Customer Ref | No | Optional: Validate customer reference matches | | Expected Resource Ref | No | Optional: Validate resource reference matches |

Output:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "is_paid": true,
  "is_terminal": true,
  "amount": "0.50",
  "currency": "USDC",
  "checkout_url": "https://pay.orvion.sh/checkout/550e8400-...",
  "tx_hash": "5nwz8X3Lgf8dqwV8EKQ2...",
  "payer_address": "0x1234...5678",
  "confirmed_at": "2025-01-08T12:00:00Z",
  "validation": {
    "valid": true,
    "customer_ref_match": true,
    "resource_ref_match": true
  }
}

Helper booleans:

• is_paid: true if status is succeeded
• is_terminal: true if status is succeeded, failed, or expired (no more polling needed)

3. Share Checkout URL

Send the checkout URL via email to a customer.

| Field | Required | Description | |-------|----------|-------------| | Charge ID | Yes | The charge ID to share (use {{ $json.charge_id }} from Create Charge) | | Recipient Email | Yes | Customer's email address |

Orvion Trigger Node (NEW)

The Orvion Trigger node automatically registers a webhook endpoint with Orvion and triggers your workflow when payment events occur.

Events

| Event | Description | |-------|-------------| | Payment Succeeded | Triggered when payment is confirmed on blockchain | | Payment Failed | Triggered when payment fails | | Payment Cancelled | Triggered when payment is cancelled |

Output

{
  "event": "billing.transaction.succeeded",
  "timestamp": "2025-01-08T12:00:00Z",
  "charge_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_paid": true,
  "is_failed": false,
  "is_cancelled": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "amount": "0.50",
  "currency": "USDC",
  "tx_hash": "5nwz8X3Lgf8dqwV8EKQ2...",
  "payer_address": "0x1234...5678",
  "customer_ref": "user_123",
  "resource_ref": "article:42"
}

How It Works

1. When you activate your workflow, the trigger automatically registers its webhook URL with Orvion
2. When a payment event occurs, Orvion sends the event data to your n8n instance
3. Your workflow continues with the payment data
4. When you deactivate the workflow, the webhook endpoint is automatically removed

Recommended Workflow Patterns

Pattern 1: Single Workflow with Wait for Payment (Recommended)

Best for: Most use cases. Everything in one workflow!

[Manual Trigger] 
  → [Orvion: Create Charge]
      - Wait for Payment: ON
      - Notify Email: [email protected]
  → [PAUSES - waiting for payment]
  → [RESUMES when customer pays]
  → [Your business logic]

The workflow pauses after creating the charge, and automatically resumes when the customer completes payment. No need for a second workflow or polling!

Pattern 2: Two Workflows with Orvion Trigger

Best for: When you need separate workflows for charge creation and fulfillment.

Workflow 1: Collect Payment

[Your Trigger] 
  → [Orvion: Create Charge + Notify Email]
  → [Respond with checkout_url]

Workflow 2: Handle Payment (separate workflow)

[Orvion Trigger: Payment Succeeded]
  → [Your business logic]

The Orvion Trigger node automatically registers itself as a webhook, so when the customer pays, your second workflow fires immediately.

Pattern 3: API/Agent Integration

Best for: APIs, apps, or agents that call your n8n workflow and need the checkout_url back.

[Webhook Trigger] 
  → [Orvion: Create Charge]
      - Wait for Payment: ON
  → [PAUSES - waiting for payment]
  → [RESUMES when customer pays]
  → [Respond to Webhook with payment result]

Your app/agent calls the n8n webhook URL → waits → gets payment confirmation in the response.

Complete Example: Order Processing

Single Workflow Pattern (Recommended)

[Webhook Trigger: POST /order]
  → [Orvion: Create Charge]
      Wait for Payment: ON
      Amount: {{ $json.total }}
      Currency: USDC
      Customer Ref: {{ $json.customer_id }}
      Resource Ref: order:{{ $json.order_id }}
      Notify Email: {{ $json.customer_email }}
  → [PAUSES - waiting for payment]
  → [RESUMES when customer pays]
  → [IF] {{ $json.is_paid }}
      → [Update order status in your database]
      → [Send confirmation email]
      → [Trigger fulfillment]
  → [ELSE]
      → [Handle payment failure]

Two Workflow Pattern (Legacy)

Workflow 1: Create Order (triggered by your app)

[Webhook Trigger: POST /order]
  → [Orvion: Create Charge]
      Wait for Payment: OFF
      Amount: {{ $json.total }}
      Notify Email: {{ $json.customer_email }}
  → [Respond to Webhook]
      { "checkout_url": "{{ $json.checkout_url }}" }

Workflow 2: Fulfill Order (triggered by Orvion webhook)

[Orvion Trigger: Payment Succeeded]
  → [Update order status in your database]
  → [Send confirmation email]
  → [Trigger fulfillment]

Local Development

See the n8n/dev folder for Docker Compose setup for local testing.

cd n8n/dev
cp .env.example .env
# Edit .env with your values
docker-compose up

Support

• Orvion Documentation
• GitHub Issues
• Discord Community

License

MIT