PaymentModal Component

The PaymentModal component provides a complete payment UI for your application. It handles token selection, balance checking, payment confirmation, and transaction processing.

Basic Usage

The easiest way to use PaymentModal is through the useVolrPay hook:

import { useVolrPay } from '@volr/react-ui';

function CheckoutButton() {
  const { pay } = useVolrPay();

  const handlePay = () => {
    pay({
      amount: '10.00',
      currency: 'USDC',
      onSuccess: () => {
        console.log('Payment successful!');
      },
      onError: (error) => {
        console.error('Payment failed:', error);
      },
    });
  };

  return <button onClick={handlePay}>Pay $10.00</button>;
}

useVolrPay Hook

The useVolrPay hook provides a simple API for opening the payment modal.

Payment Options

interface PaymentModalOptions {
  amount: string;           // Payment amount (e.g., "10.00")
  currency: string;        // Currency symbol (e.g., "USDC")
  item?: {                 // Optional item details
    name: string;
    description?: string;
    image?: string;
  };
  onSuccess?: () => void;  // Called when payment succeeds
  onError?: (error: Error) => void;  // Called when payment fails
  onCancel?: () => void;   // Called when user cancels
}

Example with Item Details

import { useVolrPay } from '@volr/react-ui';

function ProductCard({ product }) {
  const { pay } = useVolrPay();

  const handlePurchase = () => {
    pay({
      amount: product.price,
      currency: 'USDC',
      item: {
        name: product.name,
        description: product.description,
        image: product.imageUrl,
      },
      onSuccess: () => {
        console.log('Purchase successful!');
        // Redirect to success page, update cart, etc.
      },
      onError: (error) => {
        console.error('Purchase failed:', error);
        alert('Payment failed. Please try again.');
      },
    });
  };

  return (
    <div>
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <button onClick={handlePurchase}>
        Buy for {product.price} USDC
      </button>
    </div>
  );
}

Direct PaymentModal Usage

You can also use PaymentModal directly if you need more control:

import { PaymentModal } from '@volr/react-ui';
import { useState } from 'react';
import { useVolrModal } from '@volr/react-ui';

function CustomPaymentFlow() {
  const [showPayment, setShowPayment] = useState(false);
  const { openPayment } = useVolrModal();

  const handlePay = () => {
    openPayment({
      amount: '10.00',
      currency: 'USDC',
      onSuccess: () => {
        setShowPayment(false);
        console.log('Payment successful!');
      },
      onError: (error) => {
        console.error('Payment failed:', error);
      },
    });
  };

  return (
    <>
      <button onClick={handlePay}>Pay</button>
      {/* PaymentModal is rendered automatically via portal */}
    </>
  );
}

Payment States

The PaymentModal handles several states automatically:

1. Payment Info

Shows payment details and token selection:

• Payment amount
• Selected token
• Available tokens with balances
• Item details (if provided)

2. Wallet Choice

If user doesn't have a wallet:

• Create new Volr account
• Connect external wallet (MetaMask, etc.)

3. Deposit

If user has insufficient balance:

• Shows deposit option
• Opens DepositModal to add funds

4. Processing

During payment:

• Shows transaction status
• Displays transaction hash
• Handles errors

5. Result

After payment:

• Success: Shows success message
• Error: Shows error message with retry option

PaymentModal 상태 다이어그램

Error Handling

Handle payment errors:

import { useVolrPay } from '@volr/react-ui';

function PaymentButton() {
  const { pay } = useVolrPay();

  const handlePay = () => {
    pay({
      amount: '10.00',
      currency: 'USDC',
      onSuccess: () => {
        console.log('Payment successful!');
      },
      onError: (error) => {
        // Handle different error types
        if (error.message.includes('insufficient')) {
          alert('Insufficient balance. Please deposit funds.');
        } else if (error.message.includes('user rejected')) {
          // User cancelled, no action needed
        } else {
          alert('Payment failed. Please try again.');
          console.error('Payment error:', error);
        }
      },
    });
  };

  return <button onClick={handlePay}>Pay</button>;
}

Customization

Branding

PaymentModal uses your VolrUIProvider branding settings:

<VolrUIProvider
  config={{
    // ... other config
  }}
  branding={{
    logoUrl: 'https://example.com/logo.png',
    primaryColor: '#0066ff',
  }}
/>

Supported Tokens

Configure which tokens users can pay with in your Dashboard:

1. Go to Settings > Tokens
2. Select tokens for your project
3. Users will see these tokens in PaymentModal

Examples

E-commerce Checkout

import { useVolrPay } from '@volr/react-ui';
import { useCart } from './useCart';

function Checkout() {
  const { pay } = useVolrPay();
  const { items, total } = useCart();

  const handleCheckout = () => {
    pay({
      amount: total.toFixed(2),
      currency: 'USDC',
      item: {
        name: `${items.length} items`,
        description: items.map(i => i.name).join(', '),
      },
      onSuccess: () => {
        // Clear cart, redirect to success page
        console.log('Checkout successful!');
      },
      onError: (error) => {
        console.error('Checkout failed:', error);
      },
    });
  };

  return (
    <div>
      <h2>Checkout</h2>
      <p>Total: ${total} USDC</p>
      <button onClick={handleCheckout}>Pay Now</button>
    </div>
  );
}

Subscription Payment

import { useVolrPay } from '@volr/react-ui';

function SubscribeButton({ plan }) {
  const { pay } = useVolrPay();

  const handleSubscribe = () => {
    pay({
      amount: plan.price,
      currency: 'USDC',
      item: {
        name: `${plan.name} Subscription`,
        description: plan.description,
      },
      onSuccess: () => {
        console.log('Subscription activated!');
        // Update user subscription status
      },
      onError: (error) => {
        console.error('Subscription failed:', error);
      },
    });
  };

  return (
    <button onClick={handleSubscribe}>
      Subscribe for {plan.price} USDC/month
    </button>
  );
}

Next Steps

• Payment Flow - Understand the payment process in detail
• Configuration - Configure VolrUIProvider