n8n Integration

The Orvion n8n community node enables you to add crypto payment collection to any n8n workflow. Perfect for monetizing AI agent workflows, automated services, and pay-per-use APIs.

What is n8n?

n8n is a workflow automation platform that lets you connect any app with any other app. With the Orvion node, you can add payment gates to your workflows and only execute expensive operations after payment is confirmed.

Installation

In n8n (Recommended)

1. Go to Settings → Community Nodes
2. Click Install
3. Enter @orvion/n8n-nodes-orvion
4. Click Install
5. Restart n8n if prompted

Manual Installation

npm install @orvion/n8n-nodes-orvion

Configuration

Create Credentials

1. In n8n, go to Credentials → Add Credential
2. Search for "Orvion API"
3. Enter:
   • API Key: Your Orvion API key from the dashboard
   • Base URL: https://orvion.sh
4. Click Test to verify
5. Click Save

Available Nodes

The package includes two nodes:

Orvion Charge Node

The main node for creating payment charges. It creates a charge, sends a checkout URL to the customer via email, and waits for payment completion before resuming your workflow.

How It Works

1. Workflow creates a charge and sends checkout email to customer
2. Workflow pauses (status: "Waiting...")
3. Customer pays on checkout page
4. Workflow resumes automatically with payment result
5. Use an IF node to route based on is_paid

Input Fields

Output Data

After the customer pays (or payment times out), the node outputs:

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

If payment fails or times out:

{
"charge_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"amount": "1.00",
"currency": "USDC",
"failure_reason": "Transaction timed out after 5 minutes",
"is_paid": false,
"is_failed": true
}

Key fields for routing:

• is_paid: true if payment succeeded
• is_failed: true if payment failed/expired/cancelled
• status: Raw status (succeeded, failed, pending)
• failure_reason: Explains why payment failed (if applicable)

Routing with IF Node

Since the Orvion Charge node has a single output, use an IF node to route based on payment status:

[Trigger] → [Orvion Charge] → [IF] → [Success actions]
                                ↓
                          [Failed actions]

IF node configuration:

• Condition: {{ $json.is_paid }} equals true
• Enable "Convert types where required" toggle (important!)
• True branch: Payment succeeded
• False branch: Payment failed

Orvion Trigger Node

Automatically receives webhook events when payment status changes. No manual webhook configuration needed - everything is handled automatically by the node.

How It Works

1. Add the node to your workflow and select which events to listen to
2. Activate the workflow - the node automatically registers a webhook with Orvion
3. Payment events trigger your workflow - when payments succeed/fail, your workflow executes
4. Deactivate - webhook is automatically removed

Events

Output Data

{
"event": "billing.transaction.succeeded",
"charge_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "succeeded",
"amount": "1.00",
"currency": "USDC",
"tx_hash": "5nwz8X3Lgf8dqwV8EKQ2...",
"payer_address": "0x1234...5678",
"customer_ref": "user_123",
"resource_ref": "image:prompt-text",
"is_paid": true,
"is_failed": false
}

Example Workflow

Payment Gate Pattern

The recommended pattern for payment gates - create charge, wait for payment, then continue:

┌─────────────────────────┐
│ When clicking           │
│ 'Execute workflow'      │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│     Orvion Charge       │
│  (creates charge &      │
│   waits for payment)    │
└───────────┬─────────────┘
            │
    [PAUSES - waiting]
            │
    Customer pays (or timeout)
            │
    [RESUMES automatically]
            │
            ▼
┌─────────────────────────┐
│          IF             │
│  is_paid equals true    │
└─────┬───────────┬───────┘
      │           │
   TRUE        FALSE
      │           │
      ▼           ▼
┌──────────┐ ┌──────────┐
│ Success  │ │  Failed  │
│ Actions  │ │  Actions │
└──────────┘ └──────────┘

How it works:

1. Workflow creates charge and sends email to customer
2. Workflow pauses (you'll see "Waiting..." status in n8n)
3. Customer completes payment on checkout page (or timeout occurs)
4. Workflow automatically resumes with payment data
5. IF node routes to success or failure actions

Expression Reference

Use these expressions to access data from the Orvion node:

Troubleshooting

Credential test fails

• Verify API key is correct
• Check Base URL: https://orvion.sh
• Test API directly:

curl -H "X-API-Key: YOUR_KEY" https://orvion.sh/v1/health

Workflow stays in "Waiting" state

• The workflow waits until payment completes or times out (default: 5 minutes)
• Check if customer received the checkout email
• Verify the charge exists in your Orvion dashboard

IF node shows type error

• Enable "Convert types where required" in the IF node settings
• Or compare {{ $json.status }} equals succeeded instead of is_paid

Orvion Trigger not firing

• Ensure the workflow is activated (toggle in top right)
• Check webhook registration in Orvion dashboard
• Verify event types match (e.g., Payment Succeeded)

Related Documentation

• Billing Charges - API reference for charges
• Webhooks - Webhook event types and signatures
• Python SDK - For backend integrations
• Node.js SDK - For JavaScript applications