Crypto Payments

Overview

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

Supported Cryptocurrencies

Currently supported:

• XRP (Ripple) - Via XRP Ledger

Planned support:

• Bitcoin
• Ethereum
• USDC
• And more

How Crypto Payments Work

Payment Flow

1. Customer selects Pay with Crypto option
2. Chooses cryptocurrency (e.g., XRP)
3. Sees payment amount in cryptocurrency (converted from invoice currency)
4. Receives wallet address and QR code
5. Sends payment from their crypto wallet
6. Payment is monitored in real-time
7. Invoice updates automatically when payment is confirmed

Real-Time Conversion

• Invoice amount is converted to cryptocurrency using current exchange rates
• Rates are fetched from CoinGecko API
• Conversion happens at payment time
• Amount is locked for a period to prevent rate fluctuations

Setting Up Crypto Payments

Prerequisites

• Crypto payment feature enabled in your organization
• CoinGecko API key (optional, for higher rate limits)

Configuration

1. Go to Settings → Payments
2. Enable Crypto Payments
3. Configure:
   • Supported cryptocurrencies
   • Minimum confirmations
   • Exchange rate provider
   • Payment timeout

XRP Payment Process

For Customers

1. Select Payment Method
   • Choose "Pay with Crypto" or "Pay with XRP"
   • View invoice amount in XRP
2. View Payment Details
   • Wallet address (destination tag)
   • QR code for mobile wallets
   • Payment amount in XRP
   • Exchange rate used
   • Payment expiration time
3. Send Payment
   • Scan QR code or copy address
   • Send XRP from wallet
   • Include destination tag (important!)
4. Wait for Confirmation
   • Payment is monitored automatically
   • Status updates in real-time
   • Confirmation email sent when complete

Payment Monitoring

OpenInvoice monitors payments:

• Real-Time Tracking - WebSocket connection to XRPL
• Polling Fallback - Regular checks if WebSocket fails
• Confirmation Tracking - Monitors blockchain confirmations
• Automatic Updates - Invoice status updates on confirmation

Payment Addresses

Address Generation

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

Address Security

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

Payment Confirmation

Confirmation Requirements

• Minimum Confirmations - Configurable (default: 1 for XRP)
• Blockchain Confirmation - Verified on-chain
• Amount Validation - Must match invoice amount
• Destination Tag - Must match (for XRP)

Confirmation Process

1. Payment detected on blockchain
2. Amount verified
3. Destination tag verified (XRP)
4. Confirmations counted
5. Invoice status updated
6. Confirmation email sent

Exchange Rates

Rate Sources

• CoinGecko API - Primary source
• Free Tier - 10-50 calls/minute
• Pro Tier - Higher limits with API key

Rate Locking

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

Payment Status

Status Types

• Pending - Payment initiated, waiting for blockchain confirmation
• Confirming - Payment detected, counting confirmations
• Confirmed - Payment confirmed, invoice updated
• Expired - Payment not received within timeout
• Failed - Payment failed or invalid

Payment History

View crypto payment history:

1. Open the invoice
2. Go to Payments tab
3. View crypto payments:
   • Payment date
   • Cryptocurrency type
   • Amount (crypto and fiat)
   • Transaction hash
   • Confirmations
   • Status

Troubleshooting

Payment Not Detected

• Check wallet address is correct
• Verify destination tag (XRP)
• Ensure payment amount matches
• Check payment hasn't expired
• Verify network (mainnet vs testnet)

Payment Stuck

• Check blockchain status
• Verify network connectivity
• Review confirmation requirements
• Check for network congestion

Wrong Amount

• Verify exchange rate at payment time
• Check for rate fluctuations
• Contact support if needed

Best Practices

1. Verify Addresses - Always double-check wallet addresses
2. Use QR Codes - Reduces address entry errors
3. Monitor Payments - Keep payment page open
4. Set Timeouts - Configure appropriate payment timeouts
5. Test First - Use testnet for testing

Security Considerations

• Address Verification - Always verify addresses
• Destination Tags - Critical for XRP payments
• Private Keys - Never share private keys
• Phishing - Be aware of phishing attempts
• Network Selection - Use correct network (mainnet/testnet)

Next Steps

• Stripe Payments - Traditional payment processing
• Payment Tracking - Track all payment types
• Payment Plans - Payment installments