Crypto Payments

Overview

OpenInvoice supports cryptocurrency payments via the XRP Ledger (XRPL). This allows customers to pay invoices using XRP.

Prerequisites

• XRPL account (for receiving payments)
• CoinGecko API key (optional, for higher rate limits)

Configuration

1. Environment Variables

# CoinGecko (for exchange rates)
COINGECKO_API_KEY=... # Optional
COINGECKO_API_URL=https://api.coingecko.com/api/v3

# Crypto Payment Settings
CRYPTO_TEST_MODE=false
CRYPTO_USE_TESTNET=false

2. Enable Crypto Payments

Crypto payments are enabled by default. Configure in organization settings if needed.

XRP Payment Flow

1. Payment Initiation

When customer selects crypto payment:

1. Invoice amount converted to XRP
2. Exchange rate fetched from CoinGecko
3. Rate locked for 15 minutes
4. Payment address generated

2. Address Generation

import { Client, Wallet } from 'xrpl';

const client = new Client('wss://s1.ripple.com');
await client.connect();

// Generate address (handled internally)
const address = generatePaymentAddress();

3. Payment Monitoring

// WebSocket connection to XRPL
const client = new Client('wss://s1.ripple.com');
await client.connect();

// Monitor for payments
client.on('transaction', (tx) => {
  if (tx.TransactionType === 'Payment') {
    // Verify payment
    // Update invoice status
  }
});

4. Payment Confirmation

• Payment detected on blockchain
• Amount verified
• Destination tag verified
• Confirmations counted
• Invoice status updated

Exchange Rates

CoinGecko Integration

const response = await fetch(
  `https://api.coingecko.com/api/v3/simple/price?ids=xrp&vs_currencies=usd`,
  {
    headers: {
      'x-cg-api-key': process.env.COINGECKO_API_KEY,
    },
  }
);

const rate = response.data.xrp.usd;

Rate Locking

• Rates locked when payment initiated
• Lock duration: 15 minutes
• Prevents rate fluctuations
• Customer sees locked rate

Address Management

Address Generation

• Unique address per payment
• Address rotation for security
• Reuse cooldown period
• Destination tags for XRP

Security

• Addresses generated securely
• Private keys never stored
• Address rotation prevents reuse
• Time-limited addresses

Payment Confirmation

Confirmation Requirements

• Minimum confirmations (default: 1 for XRP)
• Blockchain verification
• Amount validation
• Destination tag verification

Confirmation Process

1. Payment detected
2. Amount verified
3. Destination tag verified
4. Confirmations counted
5. Invoice updated

Testing

Testnet

Use XRPL testnet for testing:

CRYPTO_USE_TESTNET=true

Testnet features:

• Free test XRP
• No real value
• Same functionality
• For development only

Test Mode

Simulate payments without blockchain:

CRYPTO_TEST_MODE=true

Troubleshooting

Payment Not Detected

• Verify address is correct
• Check destination tag
• Ensure payment amount matches
• Check payment hasn't expired

Exchange Rate Issues

• Verify CoinGecko API key
• Check rate limits
• Review API responses
• Handle rate errors gracefully

Best Practices

1. Test Thoroughly - Use testnet for development
2. Monitor Payments - Track payment status
3. Handle Errors - Implement error handling
4. Secure Addresses - Rotate addresses regularly
5. Rate Locking - Lock rates to prevent issues

Next Steps

• Cron Jobs Setup - Automated tasks
• Architecture - Codebase structure