npm package: @orvion/n8n-nodes-orvion
Description: n8n community node for Orvion - Create payment-protected charges and wait for payment confirmation
Author: Orvion
Latest version: 0.2.0

# @orvion/n8n-nodes-orvion

n8n community node for [Orvion](https://orvion.sh) - the payment orchestration platform for AI agents.

Create payment charges, notify customers, and wait for payment completion. 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 `@orvion/n8n-nodes-orvion`
4. Click **Install**

### Manual Installation

```bash
npm install @orvion/n8n-nodes-orvion
```

## Prerequisites

1. An Orvion account ([sign up here](https://orvion.sh))
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. Set Base URL to `https://orvion.sh` (or your local instance)

## Nodes

This package provides **2 nodes**:

| Node | Type | Description |
|------|------|-------------|
| **Orvion Charge** | Action | Create charges, notify customers, wait for payment |
| **Orvion Trigger** | Trigger | Receive webhook events when payments succeed/fail |

---

## Orvion Charge Node

Creates a payment charge, sends a checkout email to the customer, and **waits for payment completion** before resuming your workflow.

### How It Works

1. Your workflow creates a charge
2. Customer receives checkout email
3. Workflow **pauses** (status: "Waiting...")
4. Customer pays on the checkout page
5. Workflow **resumes automatically** with payment data
6. Use an **IF node** to route based on `is_paid`

### Input Fields

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

### Output

After payment completes (or times out):

```json
{
  "charge_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "amount": "0.50",
  "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:

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

**Key fields:**
- `is_paid`: `true` if payment succeeded
- `is_failed`: `true` if payment failed/expired/cancelled
- `failure_reason`: Explains why payment failed

### Routing with IF Node

The Orvion Charge node has a single output. Use an **IF node** after to route based on payment status:

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

**IF node configuration:**
- Condition: `{{ $json.is_paid }}` equals `true`
- Enable **"Convert types where required"** toggle (important!)
- True branch = Success, False branch = Failed

**Alternative: Using Switch Node**

If you prefer multiple routing paths, use a **Switch node** instead:

```
[Trigger] → [Orvion Charge] → [Switch] → [Success (is_paid = true)]
                                      → [Failed (is_failed = true)]
                                      → [Pending (status = pending)]
```

**Switch node configuration:**
- Mode: "Rules"
- Rule 1: `{{ $json.is_paid }}` equals `true` → Success branch
- Rule 2: `{{ $json.is_failed }}` equals `true` → Failed branch
- Fallback: Default branch for other cases

**Troubleshooting IF Node:**

If the IF node routes incorrectly despite `is_paid: true`:
1. Ensure **"Convert types where required"** is enabled
2. Try using expression mode: `{{ Boolean($json.is_paid) }}` equals `true`
3. Or use direct comparison: Expression `{{ $json.is_paid === true }}`
4. Check the node output panel to verify the actual data type

---

## Orvion Trigger Node

Automatically receives webhook events when payment status changes.

### 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

```json
{
  "event": "billing.transaction.succeeded",
  "timestamp": "2025-01-08T12:00:00Z",
  "charge_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_paid": true,
  "is_failed": false,
  "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 registers its webhook URL with Orvion
2. When a payment event occurs, Orvion sends the event data to n8n
3. Your workflow continues with the payment data
4. When you deactivate the workflow, the webhook endpoint is automatically removed

---

## Example Workflow

### Payment Gate Pattern (Recommended)

```
[Manual Trigger] 
  → [Orvion Charge]
      Amount: 1.00
      Currency: USDC
      Notify Email: customer@example.com
  → [PAUSES - waiting for payment]
  → [RESUMES when customer pays or timeout]
  → [IF: is_paid equals true]
      → TRUE: [Success actions]
      → FALSE: [Handle failure]
```

### Complete Example: Order Processing

```
[Webhook Trigger: POST /order]
  → [Orvion Charge]
      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]
  → [IF: is_paid equals true]
      → TRUE:
          → [Update order status in database]
          → [Send confirmation email]
          → [Trigger fulfillment]
      → FALSE:
          → [Log failed payment]
          → [Send failure notification]
```

---

## Local Development

See the [n8n/dev](../dev) folder for Docker Compose setup for local testing.

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

## Support

- [Orvion Documentation](https://docs.orvion.sh)
- [GitHub Issues](https://github.com/orvion-sh/agent-pay/issues)

## License

MIT