Stablecoin Payments & Subscriptions

When to Use

Activate this skill when:

• Implementing subscription billing for BlockDrive tiers
• Processing one-time or recurring stablecoin payments
• Setting up payment webhooks for event handling
• Minting NFT memberships tied to subscription tiers
• Implementing refund or cancellation flows
• Configuring multi-chain payment acceptance
• Building checkout flows with crypto payments
• Integrating payment analytics and reporting
• Handling failed payment retries
• Managing subscription upgrades and downgrades

Core Architecture

Payment & Subscription Flow

┌─────────────────────────────────────────────────────────────────────┐
│              CROSSMINT PAYMENT & SUBSCRIPTION FLOW                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────┐     ┌──────────────┐     ┌──────────────┐           │
│  │   USER   │────▶│  CROSSMINT   │────▶│   SUPABASE   │           │
│  │  (Payer) │     │  Payment API │     │   Database   │           │
│  └──────────┘     └──────────────┘     └──────────────┘           │
│       │                  │                     │                   │
│       │                  │                     │                   │
│  1. Select tier    2. Process payment   3. Update subscription     │
│     & checkout        & mint NFT           & grant access          │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  PAYMENT PROCESSING                                          │  │
│  │  • User selects Pro/Enterprise tier                         │  │
│  │  • Crossmint creates checkout session                       │  │
│  │  • User pays with USDC/USDT on any chain                    │  │
│  │  • Crossmint mints membership NFT                           │  │
│  │  • Webhook triggers access grant                            │  │
│  │  • Subscription activated in database                       │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  RECURRING BILLING                                           │  │
│  │  • Crossmint automatically charges monthly                   │  │
│  │  • Payment webhook confirms transaction                      │  │
│  │  • NFT remains valid (no re-mint needed)                    │  │
│  │  • Failed payments trigger retry logic                      │  │
│  │  • After 3 failures, subscription downgraded                │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Subscription Tier Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    BLOCKDRIVE SUBSCRIPTION TIERS                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  FREE TIER                                                           │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  • No payment required                                 │        │
│  │  • 5GB storage limit                                   │        │
│  │  • Basic file upload/download                          │        │
│  │  • No NFT membership                                   │        │
│  │  • Community support only                              │        │
│  └────────────────────────────────────────────────────────┘        │
│                          ↓ UPGRADE                                  │
│  PRO TIER ($9.99/month USDC)                                        │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  • Recurring monthly billing                           │        │
│  │  • 100GB storage limit                                 │        │
│  │  • Advanced file sharing                               │        │
│  │  • Version history (30 days)                           │        │
│  │  • Pro NFT badge minted                                │        │
│  │  • Priority support                                    │        │
│  │  • API access                                          │        │
│  └────────────────────────────────────────────────────────┘        │
│                          ↓ UPGRADE                                  │
│  ENTERPRISE TIER ($99.99/month USDC)                                │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  • Recurring monthly billing                           │        │
│  │  • Unlimited storage                                   │        │
│  │  • Team collaboration features                         │        │
│  │  • Unlimited version history                           │        │
│  │  • Enterprise NFT badge minted                         │        │
│  │  • White-label options                                 │        │
│  │  • Dedicated support & SLA                             │        │
│  │  • Advanced API & webhooks                             │        │
│  └────────────────────────────────────────────────────────┘        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Webhook Event Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    PAYMENT WEBHOOK EVENT FLOW                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  PAYMENT SUCCESS                                                     │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  1. Crossmint → BlockDrive webhook endpoint            │        │
│  │  2. Verify webhook signature                           │        │
│  │  3. Extract payment & user data                        │        │
│  │  4. Update subscription in Supabase                    │        │
│  │  5. Mint NFT membership badge                          │        │
│  │  6. Send confirmation email                            │        │
│  │  7. Grant tier-specific features                       │        │
│  └────────────────────────────────────────────────────────┘        │
│                                                                      │
│  PAYMENT FAILED                                                      │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  1. Crossmint → BlockDrive webhook endpoint            │        │
│  │  2. Verify webhook signature                           │        │
│  │  3. Log failure reason                                 │        │
│  │  4. Increment retry counter                            │        │
│  │  5. Send payment failed notification                   │        │
│  │  6. Schedule retry (after 3 days)                      │        │
│  │  7. Downgrade after 3 failed attempts                  │        │
│  └────────────────────────────────────────────────────────┘        │
│                                                                      │
│  SUBSCRIPTION CANCELLED                                              │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  1. Crossmint → BlockDrive webhook endpoint            │        │
│  │  2. Verify webhook signature                           │        │
│  │  3. Mark subscription as cancelled                     │        │
│  │  4. Allow access until period end                      │        │
│  │  5. Burn NFT membership (optional)                     │        │
│  │  6. Send cancellation confirmation                     │        │
│  │  7. Downgrade to Free tier on next billing date        │        │
│  └────────────────────────────────────────────────────────┘        │
│                                                                      │
│  REFUND PROCESSED                                                    │
│  ┌────────────────────────────────────────────────────────┐        │
│  │  1. Crossmint → BlockDrive webhook endpoint            │        │
│  │  2. Verify webhook signature                           │        │
│  │  3. Update subscription status                         │        │
│  │  4. Calculate prorated access period                   │        │
│  │  5. Burn NFT membership                                │        │
│  │  6. Send refund confirmation                           │        │
│  │  7. Revoke tier-specific features immediately          │        │
│  └────────────────────────────────────────────────────────┘        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Implementation Pattern

Required Packages

npm install @crossmint/client-sdk-react-ui
npm install @crossmint/server-sdk
npm install stripe # For subscription management patterns
npm install crypto # For webhook signature verification

Environment Configuration

// .env.local
NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY=your_client_key
CROSSMINT_SERVER_API_KEY=your_server_key
CROSSMINT_WEBHOOK_SECRET=your_webhook_secret
NEXT_PUBLIC_PRO_TIER_PRICE_ID=price_pro_monthly
NEXT_PUBLIC_ENTERPRISE_TIER_PRICE_ID=price_enterprise_monthly
NEXT_PUBLIC_APP_URL=https://blockdrive.app

Payment Service Core

// lib/payments/crossmint-payment-service.ts
import { CrossmintPaymentAPI } from '@crossmint/server-sdk';

export type TierName = 'free' | 'pro' | 'enterprise';

export interface SubscriptionTier {
  name: TierName;
  displayName: string;
  priceMonthly: number; // USDC
  currency: 'usdc' | 'usdt';
  chain: 'solana' | 'ethereum' | 'base' | 'polygon';
  features: string[];
  storageGB: number;
  nftMetadata?: {
    name: string;
    description: string;
    image: string;
    attributes: Record<string, string>;
  };
}

export const SUBSCRIPTION_TIERS: Record<TierName, SubscriptionTier> = {
  free: {
    name: 'free',
    displayName: 'Free',
    priceMonthly: 0,
    currency: 'usdc',
    chain: 'solana',
    features: [
      '5GB storage',
      'Basic file upload/download',
      'Community support',
    ],
    storageGB: 5,
  },
  pro: {
    name: 'pro',
    displayName: 'Pro',
    priceMonthly: 9.99,
    currency: 'usdc',
    chain: 'solana',
    features: [
      '100GB storage',
      'Advanced file sharing',
      '30-day version history',
      'Priority support',
      'API access',
    ],
    storageGB: 100,
    nftMetadata: {
      name: 'BlockDrive Pro Member',
      description: 'Pro tier membership for BlockDrive decentralized storage',
      image: 'https://blockdrive.app/nft/pro-badge.png',
      attributes: {
        tier: 'Pro',
        storage: '100GB',
        features: 'Advanced',
      },
    },
  },
  enterprise: {
    name: 'enterprise',
    displayName: 'Enterprise',
    priceMonthly: 99.99,
    currency: 'usdc',
    chain: 'solana',
    features: [
      'Unlimited storage',
      'Team collaboration',
      'Unlimited version history',
      'White-label options',
      'Dedicated support & SLA',
      'Advanced API & webhooks',
    ],
    storageGB: -1, // Unlimited
    nftMetadata: {
      name: 'BlockDrive Enterprise Member',
      description: 'Enterprise tier membership for BlockDrive decentralized storage',
      image: 'https://blockdrive.app/nft/enterprise-badge.png',
      attributes: {
        tier: 'Enterprise',
        storage: 'Unlimited',
        features: 'Premium',
      },
    },
  },
};

export interface CreateCheckoutParams {
  userId: string;
  tier: TierName;
  email: string;
  walletAddress: string;
  successUrl?: string;
  cancelUrl?: string;
}

export interface CheckoutSession {
  id: string;
  url: string;
  expiresAt: Date;
}

export class CrossmintPaymentService {
  private api: CrossmintPaymentAPI;

  constructor(apiKey: string) {
    this.api = new CrossmintPaymentAPI(apiKey);
  }

  /**
   * Create a checkout session for subscription upgrade
   */
  async createCheckoutSession(
    params: CreateCheckoutParams
  ): Promise<CheckoutSession> {
    try {
      const tier = SUBSCRIPTION_TIERS[params.tier];

      if (tier.name === 'free') {
        throw new Error('Cannot create checkout for free tier');
      }

      const session = await this.api.checkout.create({
        lineItems: [{
          name: `BlockDrive ${tier.displayName} Subscription`,
          description: tier.features.join(', '),
          price: tier.priceMonthly,
          currency: tier.currency.toUpperCase(),
          quantity: 1,
        }],
        payment: {
          method: 'crypto',
          crypto: {
            chains: [tier.chain],
            currencies: [tier.currency.toUpperCase()],
          },
          recurring: {
            interval: 'month',
            intervalCount: 1,
          },
        },
        recipient: {
          email: params.email,
          walletAddress: params.walletAddress,
        },
        metadata: {
          userId: params.userId,
          tier: params.tier,
          subscriptionType: 'recurring',
        },
        locale: 'en-US',
        successCallbackUrl: params.successUrl || `${process.env.NEXT_PUBLIC_APP_URL}/subscription/success`,
        cancelCallbackUrl: params.cancelUrl || `${process.env.NEXT_PUBLIC_APP_URL}/subscription/cancel`,
      });

      console.log('Checkout session created:', {
        sessionId: session.id,
        tier: params.tier,
        user: params.userId,
      });

      return {
        id: session.id,
        url: session.url,
        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
      };
    } catch (error) {
      console.error('Failed to create checkout session:', error);
      throw error;
    }
  }

  /**
   * Process one-time payment (e.g., for yearly subscriptions)
   */
  async processOneTimePayment(params: {
    userId: string;
    amount: number;
    currency: 'usdc' | 'usdt';
    chain: string;
    description: string;
    metadata?: Record<string, string>;
  }): Promise<{ paymentId: string; status: string }> {
    try {
      const payment = await this.api.payments.create({
        amount: params.amount,
        currency: params.currency.toUpperCase(),
        chain: params.chain,
        description: params.description,
        metadata: {
          userId: params.userId,
          ...params.metadata,
        },
      });

      console.log('One-time payment created:', {
        paymentId: payment.id,
        amount: params.amount,
        currency: params.currency,
      });

      return {
        paymentId: payment.id,
        status: payment.status,
      };
    } catch (error) {
      console.error('Failed to process one-time payment:', error);
      throw error;
    }
  }

  /**
   * Get subscription details
   */
  async getSubscription(subscriptionId: string) {
    try {
      const subscription = await this.api.subscriptions.get(subscriptionId);

      return {
        id: subscription.id,
        status: subscription.status,
        tier: subscription.metadata?.tier as TierName,
        currentPeriodStart: new Date(subscription.currentPeriodStart),
        currentPeriodEnd: new Date(subscription.currentPeriodEnd),
        cancelAtPeriodEnd: subscription.cancelAtPeriodEnd,
        userId: subscription.metadata?.userId,
      };
    } catch (error) {
      console.error('Failed to get subscription:', error);
      throw error;
    }
  }

  /**
   * Cancel subscription (at period end)
   */
  async cancelSubscription(
    subscriptionId: string,
    immediate: boolean = false
  ): Promise<void> {
    try {
      await this.api.subscriptions.cancel(subscriptionId, {
        immediate,
      });

      console.log('Subscription cancelled:', {
        subscriptionId,
        immediate,
      });
    } catch (error) {
      console.error('Failed to cancel subscription:', error);
      throw error;
    }
  }

  /**
   * Update subscription (upgrade/downgrade tier)
   */
  async updateSubscription(
    subscriptionId: string,
    newTier: TierName
  ): Promise<void> {
    try {
      const tier = SUBSCRIPTION_TIERS[newTier];

      await this.api.subscriptions.update(subscriptionId, {
        priceAmount: tier.priceMonthly,
        metadata: {
          tier: newTier,
        },
      });

      console.log('Subscription updated:', {
        subscriptionId,
        newTier,
      });
    } catch (error) {
      console.error('Failed to update subscription:', error);
      throw error;
    }
  }

  /**
   * Process refund
   */
  async processRefund(
    paymentId: string,
    amount?: number,
    reason?: string
  ): Promise<{ refundId: string; status: string }> {
    try {
      const refund = await this.api.refunds.create({
        paymentId,
        amount, // If not provided, full refund
        reason,
      });

      console.log('Refund processed:', {
        refundId: refund.id,
        paymentId,
        amount: refund.amount,
      });

      return {
        refundId: refund.id,
        status: refund.status,
      };
    } catch (error) {
      console.error('Failed to process refund:', error);
      throw error;
    }
  }

  /**
   * Get payment history for a user
   */
  async getPaymentHistory(userId: string) {
    try {
      const payments = await this.api.payments.list({
        metadata: { userId },
        limit: 100,
      });

      return payments.data.map(payment => ({
        id: payment.id,
        amount: payment.amount,
        currency: payment.currency,
        status: payment.status,
        createdAt: new Date(payment.created),
        description: payment.description,
      }));
    } catch (error) {
      console.error('Failed to get payment history:', error);
      throw error;
    }
  }

  /**
   * Verify webhook signature
   */
  verifyWebhookSignature(
    payload: string,
    signature: string,
    secret: string
  ): boolean {
    try {
      const crypto = require('crypto');
      const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

      return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expectedSignature)
      );
    } catch (error) {
      console.error('Failed to verify webhook signature:', error);
      return false;
    }
  }
}

Webhook Handler

// app/api/webhooks/crossmint/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { CrossmintPaymentService } from '@/lib/payments/crossmint-payment-service';
import { createClient } from '@/lib/supabase/server';
import { mintMembershipNFT } from '@/lib/nft/membership-minting';

const paymentService = new CrossmintPaymentService(
  process.env.CROSSMINT_SERVER_API_KEY!
);

export async function POST(req: NextRequest) {
  try {
    // Get webhook payload and signature
    const payload = await req.text();
    const signature = req.headers.get('x-crossmint-signature');

    if (!signature) {
      return NextResponse.json(
        { error: 'Missing signature' },
        { status: 400 }
      );
    }

    // Verify webhook signature
    const isValid = paymentService.verifyWebhookSignature(
      payload,
      signature,
      process.env.CROSSMINT_WEBHOOK_SECRET!
    );

    if (!isValid) {
      console.error('Invalid webhook signature');
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 401 }
      );
    }

    // Parse event
    const event = JSON.parse(payload);
    console.log('Webhook event received:', event.type);

    // Route to appropriate handler
    switch (event.type) {
      case 'payment.succeeded':
        await handlePaymentSucceeded(event);
        break;

      case 'payment.failed':
        await handlePaymentFailed(event);
        break;

      case 'subscription.created':
        await handleSubscriptionCreated(event);
        break;

      case 'subscription.updated':
        await handleSubscriptionUpdated(event);
        break;

      case 'subscription.cancelled':
        await handleSubscriptionCancelled(event);
        break;

      case 'refund.processed':
        await handleRefundProcessed(event);
        break;

      default:
        console.log('Unhandled event type:', event.type);
    }

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    );
  }
}

async function handlePaymentSucceeded(event: any) {
  const { userId, tier } = event.data.metadata;
  const supabase = createClient();

  try {
    // Update subscription in database
    const { error: updateError } = await supabase
      .from('subscriptions')
      .upsert({
        user_id: userId,
        tier,
        status: 'active',
        current_period_start: new Date(event.data.currentPeriodStart),
        current_period_end: new Date(event.data.currentPeriodEnd),
        crossmint_subscription_id: event.data.subscriptionId,
        crossmint_payment_id: event.data.id,
        updated_at: new Date(),
      });

    if (updateError) throw updateError;

    // Mint NFT membership badge
    if (tier !== 'free') {
      const { data: userData } = await supabase
        .from('users')
        .select('wallet_address')
        .eq('id', userId)
        .single();

      if (userData?.wallet_address) {
        await mintMembershipNFT({
          walletAddress: userData.wallet_address,
          tier,
          userId,
        });
      }
    }

    // Send confirmation email
    await sendSubscriptionConfirmationEmail(userId, tier);

    console.log('Payment succeeded processed:', {
      userId,
      tier,
      paymentId: event.data.id,
    });
  } catch (error) {
    console.error('Failed to handle payment succeeded:', error);
    throw error;
  }
}

async function handlePaymentFailed(event: any) {
  const { userId, tier } = event.data.metadata;
  const supabase = createClient();

  try {
    // Log failed payment
    await supabase.from('payment_failures').insert({
      user_id: userId,
      tier,
      reason: event.data.failureReason,
      crossmint_payment_id: event.data.id,
      retry_count: event.data.retryCount || 0,
      created_at: new Date(),
    });

    // Check retry count
    const retryCount = event.data.retryCount || 0;

    if (retryCount >= 3) {
      // Downgrade subscription after 3 failed attempts
      await supabase
        .from('subscriptions')
        .update({
          tier: 'free',
          status: 'past_due',
          downgraded_at: new Date(),
        })
        .eq('user_id', userId);

      await sendPaymentFailedDowngradeEmail(userId);
    } else {
      // Send retry notification
      await sendPaymentFailedRetryEmail(userId, retryCount + 1);
    }

    console.log('Payment failed processed:', {
      userId,
      tier,
      retryCount,
    });
  } catch (error) {
    console.error('Failed to handle payment failed:', error);
    throw error;
  }
}

async function handleSubscriptionCreated(event: any) {
  const { userId, tier } = event.data.metadata;
  const supabase = createClient();

  try {
    await supabase.from('subscriptions').insert({
      user_id: userId,
      tier,
      status: 'active',
      current_period_start: new Date(event.data.currentPeriodStart),
      current_period_end: new Date(event.data.currentPeriodEnd),
      crossmint_subscription_id: event.data.id,
      created_at: new Date(),
    });

    console.log('Subscription created:', { userId, tier });
  } catch (error) {
    console.error('Failed to handle subscription created:', error);
    throw error;
  }
}

async function handleSubscriptionUpdated(event: any) {
  const { userId, tier } = event.data.metadata;
  const supabase = createClient();

  try {
    // Get old tier
    const { data: oldSubscription } = await supabase
      .from('subscriptions')
      .select('tier')
      .eq('user_id', userId)
      .single();

    // Update subscription
    await supabase
      .from('subscriptions')
      .update({
        tier,
        status: event.data.status,
        current_period_start: new Date(event.data.currentPeriodStart),
        current_period_end: new Date(event.data.currentPeriodEnd),
        updated_at: new Date(),
      })
      .eq('user_id', userId);

    // Handle tier change
    if (oldSubscription && oldSubscription.tier !== tier) {
      await handleTierChange(userId, oldSubscription.tier, tier);
    }

    console.log('Subscription updated:', { userId, oldTier: oldSubscription?.tier, newTier: tier });
  } catch (error) {
    console.error('Failed to handle subscription updated:', error);
    throw error;
  }
}

async function handleSubscriptionCancelled(event: any) {
  const { userId } = event.data.metadata;
  const supabase = createClient();

  try {
    await supabase
      .from('subscriptions')
      .update({
        status: 'cancelled',
        cancel_at_period_end: true,
        cancelled_at: new Date(),
      })
      .eq('user_id', userId);

    await sendCancellationConfirmationEmail(userId);

    console.log('Subscription cancelled:', { userId });
  } catch (error) {
    console.error('Failed to handle subscription cancelled:', error);
    throw error;
  }
}

async function handleRefundProcessed(event: any) {
  const { userId, tier } = event.data.metadata;
  const supabase = createClient();

  try {
    // Update subscription
    await supabase
      .from('subscriptions')
      .update({
        tier: 'free',
        status: 'refunded',
        refunded_at: new Date(),
      })
      .eq('user_id', userId);

    // Burn NFT membership (optional)
    await burnMembershipNFT(userId, tier);

    // Send refund confirmation
    await sendRefundConfirmationEmail(userId, event.data.amount);

    console.log('Refund processed:', {
      userId,
      amount: event.data.amount,
    });
  } catch (error) {
    console.error('Failed to handle refund processed:', error);
    throw error;
  }
}

async function handleTierChange(userId: string, oldTier: string, newTier: string) {
  // Burn old NFT and mint new one
  await burnMembershipNFT(userId, oldTier);

  const supabase = createClient();
  const { data: userData } = await supabase
    .from('users')
    .select('wallet_address')
    .eq('id', userId)
    .single();

  if (userData?.wallet_address) {
    await mintMembershipNFT({
      walletAddress: userData.wallet_address,
      tier: newTier,
      userId,
    });
  }

  await sendTierChangeEmail(userId, oldTier, newTier);
}

// Email helper functions (implement with your email service)
async function sendSubscriptionConfirmationEmail(userId: string, tier: string) {
  console.log('Sending subscription confirmation email:', { userId, tier });
}

async function sendPaymentFailedRetryEmail(userId: string, retryCount: number) {
  console.log('Sending payment failed retry email:', { userId, retryCount });
}

async function sendPaymentFailedDowngradeEmail(userId: string) {
  console.log('Sending payment failed downgrade email:', { userId });
}

async function sendCancellationConfirmationEmail(userId: string) {
  console.log('Sending cancellation confirmation email:', { userId });
}

async function sendRefundConfirmationEmail(userId: string, amount: number) {
  console.log('Sending refund confirmation email:', { userId, amount });
}

async function sendTierChangeEmail(userId: string, oldTier: string, newTier: string) {
  console.log('Sending tier change email:', { userId, oldTier, newTier });
}

async function burnMembershipNFT(userId: string, tier: string) {
  console.log('Burning membership NFT:', { userId, tier });
}

NFT Membership Minting

// lib/nft/membership-minting.ts
import { CrossmintEmbeddedWallet } from '@crossmint/client-sdk-react-ui';
import { Connection, PublicKey } from '@solana/web3.js';
import { SUBSCRIPTION_TIERS, TierName } from '@/lib/payments/crossmint-payment-service';

export interface MintMembershipParams {
  walletAddress: string;
  tier: TierName;
  userId: string;
}

export async function mintMembershipNFT(params: MintMembershipParams) {
  try {
    const tier = SUBSCRIPTION_TIERS[params.tier];

    if (!tier.nftMetadata) {
      console.log('No NFT for tier:', params.tier);
      return null;
    }

    // Use Crossmint NFT minting API
    const response = await fetch('https://api.crossmint.com/v1/nfts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.CROSSMINT_SERVER_API_KEY!,
      },
      body: JSON.stringify({
        recipient: `solana:${params.walletAddress}`,
        metadata: {
          name: tier.nftMetadata.name,
          description: tier.nftMetadata.description,
          image: tier.nftMetadata.image,
          attributes: [
            ...Object.entries(tier.nftMetadata.attributes).map(([trait_type, value]) => ({
              trait_type,
              value,
            })),
            {
              trait_type: 'User ID',
              value: params.userId,
            },
            {
              trait_type: 'Minted At',
              value: new Date().toISOString(),
            },
          ],
        },
      }),
    });

    if (!response.ok) {
      throw new Error(`NFT minting failed: ${response.statusText}`);
    }

    const data = await response.json();

    console.log('Membership NFT minted:', {
      userId: params.userId,
      tier: params.tier,
      mintAddress: data.onChain.mintAddress,
    });

    return {
      mintAddress: data.onChain.mintAddress,
      transactionId: data.onChain.transactionId,
    };
  } catch (error) {
    console.error('Failed to mint membership NFT:', error);
    throw error;
  }
}

React Hook for Subscriptions

// hooks/useSubscription.ts
import { useState, useEffect, useCallback } from 'react';
import { useUser } from '@clerk/nextjs';
import { TierName } from '@/lib/payments/crossmint-payment-service';
import { createClient } from '@/lib/supabase/client';

export interface Subscription {
  id: string;
  userId: string;
  tier: TierName;
  status: 'active' | 'cancelled' | 'past_due' | 'refunded';
  currentPeriodStart: Date;
  currentPeriodEnd: Date;
  cancelAtPeriodEnd: boolean;
}

export function useSubscription() {
  const { user } = useUser();
  const [subscription, setSubscription] = useState<Subscription | null>(null);
  const [loading, setLoading] = useState(true);
  const supabase = createClient();

  useEffect(() => {
    if (user) {
      loadSubscription();
    }
  }, [user]);

  const loadSubscription = useCallback(async () => {
    if (!user) return;

    try {
      const { data, error } = await supabase
        .from('subscriptions')
        .select('*')
        .eq('user_id', user.id)
        .single();

      if (error) {
        if (error.code === 'PGRST116') {
          // No subscription found, user is on free tier
          setSubscription({
            id: 'free',
            userId: user.id,
            tier: 'free',
            status: 'active',
            currentPeriodStart: new Date(),
            currentPeriodEnd: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
            cancelAtPeriodEnd: false,
          });
        } else {
          throw error;
        }
      } else {
        setSubscription({
          id: data.id,
          userId: data.user_id,
          tier: data.tier,
          status: data.status,
          currentPeriodStart: new Date(data.current_period_start),
          currentPeriodEnd: new Date(data.current_period_end),
          cancelAtPeriodEnd: data.cancel_at_period_end || false,
        });
      }
    } catch (error) {
      console.error('Failed to load subscription:', error);
    } finally {
      setLoading(false);
    }
  }, [user, supabase]);

  const startCheckout = useCallback(async (tier: TierName) => {
    if (!user) throw new Error('User not authenticated');

    try {
      const response = await fetch('/api/subscriptions/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ tier }),
      });

      if (!response.ok) {
        throw new Error('Failed to create checkout session');
      }

      const { url } = await response.json();
      window.location.href = url;
    } catch (error) {
      console.error('Failed to start checkout:', error);
      throw error;
    }
  }, [user]);

  const cancelSubscription = useCallback(async (immediate: boolean = false) => {
    if (!user || !subscription) return;

    try {
      const response = await fetch('/api/subscriptions/cancel', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ immediate }),
      });

      if (!response.ok) {
        throw new Error('Failed to cancel subscription');
      }

      await loadSubscription();
    } catch (error) {
      console.error('Failed to cancel subscription:', error);
      throw error;
    }
  }, [user, subscription, loadSubscription]);

  const reactivateSubscription = useCallback(async () => {
    if (!user || !subscription) return;

    try {
      const response = await fetch('/api/subscriptions/reactivate', {
        method: 'POST',
      });

      if (!response.ok) {
        throw new Error('Failed to reactivate subscription');
      }

      await loadSubscription();
    } catch (error) {
      console.error('Failed to reactivate subscription:', error);
      throw error;
    }
  }, [user, subscription, loadSubscription]);

  return {
    subscription,
    loading,
    startCheckout,
    cancelSubscription,
    reactivateSubscription,
    refresh: loadSubscription,
  };
}

Subscription Management UI

// components/subscription/SubscriptionManager.tsx
'use client';

import { useSubscription } from '@/hooks/useSubscription';
import { SUBSCRIPTION_TIERS } from '@/lib/payments/crossmint-payment-service';

export function SubscriptionManager() {
  const { subscription, loading, startCheckout, cancelSubscription } = useSubscription();

  if (loading) {
    return <div>Loading subscription...</div>;
  }

  if (!subscription) {
    return <div>No subscription found</div>;
  }

  const currentTier = SUBSCRIPTION_TIERS[subscription.tier];

  return (
    <div className="max-w-4xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">Subscription Management</h1>

      {/* Current Plan */}
      <div className="bg-white rounded-lg shadow-lg p-6 mb-6">
        <div className="flex items-center justify-between mb-4">
          <div>
            <h2 className="text-2xl font-bold">{currentTier.displayName} Plan</h2>
            <p className="text-gray-600">
              {subscription.tier === 'free'
                ? 'Free forever'
                : `$${currentTier.priceMonthly}/month`}
            </p>
          </div>
          <div className="text-right">
            <p className="text-sm text-gray-600">Status</p>
            <p className="font-semibold capitalize">{subscription.status}</p>
          </div>
        </div>

        {/* Features */}
        <div className="mb-4">
          <h3 className="font-semibold mb-2">Features:</h3>
          <ul className="space-y-1">
            {currentTier.features.map((feature, idx) => (
              <li key={idx} className="flex items-center">
                <span className="text-green-600 mr-2">✓</span>
                {feature}
              </li>
            ))}
          </ul>
        </div>

        {/* Billing Info */}
        {subscription.tier !== 'free' && (
          <div className="border-t pt-4">
            <p className="text-sm text-gray-600">
              Current period: {subscription.currentPeriodStart.toLocaleDateString()} - {subscription.currentPeriodEnd.toLocaleDateString()}
            </p>
            {subscription.cancelAtPeriodEnd && (
              <p className="text-sm text-orange-600 mt-2">
                Your subscription will end on {subscription.currentPeriodEnd.toLocaleDateString()}
              </p>
            )}
          </div>
        )}
      </div>

      {/* Available Tiers */}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {(['free', 'pro', 'enterprise'] as const).map(tierName => {
          const tier = SUBSCRIPTION_TIERS[tierName];
          const isCurrent = subscription.tier === tierName;
          const isUpgrade = getTierLevel(tierName) > getTierLevel(subscription.tier);

          return (
            <div
              key={tierName}
              className={`bg-white rounded-lg shadow p-6 ${
                isCurrent ? 'ring-2 ring-blue-600' : ''
              }`}
            >
              <h3 className="text-xl font-bold mb-2">{tier.displayName}</h3>
              <p className="text-3xl font-bold mb-4">
                {tier.priceMonthly === 0 ? 'Free' : `$${tier.priceMonthly}`}
                {tier.priceMonthly > 0 && <span className="text-sm">/month</span>}
              </p>

              <ul className="space-y-2 mb-6">
                {tier.features.map((feature, idx) => (
                  <li key={idx} className="text-sm flex items-start">
                    <span className="text-green-600 mr-2">✓</span>
                    {feature}
                  </li>
                ))}
              </ul>

              {isCurrent ? (
                <div>
                  <button
                    disabled
                    className="w-full px-4 py-2 bg-gray-300 text-gray-600 rounded cursor-not-allowed"
                  >
                    Current Plan
                  </button>
                  {tierName !== 'free' && !subscription.cancelAtPeriodEnd && (
                    <button
                      onClick={() => cancelSubscription(false)}
                      className="w-full mt-2 px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700"
                    >
                      Cancel Subscription
                    </button>
                  )}
                </div>
              ) : (
                <button
                  onClick={() => startCheckout(tierName)}
                  disabled={tierName === 'free'}
                  className={`w-full px-4 py-2 rounded ${
                    isUpgrade
                      ? 'bg-blue-600 text-white hover:bg-blue-700'
                      : 'bg-gray-200 text-gray-700 hover:bg-gray-300'
                  } ${tierName === 'free' ? 'opacity-50 cursor-not-allowed' : ''}`}
                >
                  {isUpgrade ? 'Upgrade' : 'Downgrade'}
                </button>
              )}
            </div>
          );
        })}
      </div>
    </div>
  );
}

function getTierLevel(tier: string): number {
  const levels = { free: 0, pro: 1, enterprise: 2 };
  return levels[tier as keyof typeof levels] || 0;
}

Database Schema

-- subscriptions table
CREATE TABLE subscriptions (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  tier TEXT NOT NULL CHECK (tier IN ('free', 'pro', 'enterprise')),
  status TEXT NOT NULL CHECK (status IN ('active', 'cancelled', 'past_due', 'refunded')),
  current_period_start TIMESTAMP WITH TIME ZONE NOT NULL,
  current_period_end TIMESTAMP WITH TIME ZONE NOT NULL,
  cancel_at_period_end BOOLEAN DEFAULT FALSE,
  crossmint_subscription_id TEXT,
  crossmint_payment_id TEXT,
  cancelled_at TIMESTAMP WITH TIME ZONE,
  refunded_at TIMESTAMP WITH TIME ZONE,
  downgraded_at TIMESTAMP WITH TIME ZONE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX subscriptions_user_id_idx ON subscriptions(user_id);
CREATE INDEX subscriptions_status_idx ON subscriptions(status);
CREATE INDEX subscriptions_crossmint_subscription_id_idx ON subscriptions(crossmint_subscription_id);

-- payment_failures table
CREATE TABLE payment_failures (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  tier TEXT NOT NULL,
  reason TEXT,
  crossmint_payment_id TEXT,
  retry_count INTEGER DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX payment_failures_user_id_idx ON payment_failures(user_id);

-- membership_nfts table
CREATE TABLE membership_nfts (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  tier TEXT NOT NULL,
  mint_address TEXT NOT NULL,
  transaction_id TEXT NOT NULL,
  burned BOOLEAN DEFAULT FALSE,
  burned_at TIMESTAMP WITH TIME ZONE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX membership_nfts_user_id_idx ON membership_nfts(user_id);
CREATE INDEX membership_nfts_mint_address_idx ON membership_nfts(mint_address);

Best Practices

Payment Security

1. Webhook Verification

   • Always verify webhook signatures
   • Use timing-safe comparison for signatures
   • Log all webhook events for audit trail
   • Implement idempotency to prevent duplicate processing

2. Subscription Management

   • Allow users to cancel at period end (not immediately)
   • Prorate refunds based on usage
   • Implement grace periods for failed payments
   • Send notifications before billing

3. Error Handling

   • Retry failed payments automatically (with limits)
   • Provide clear error messages to users
   • Log all payment failures for analysis
   • Implement fallback payment methods

User Experience

1. Transparent Pricing

   • Show all costs upfront
   • Display currency conversions clearly
   • Explain recurring billing
   • Provide usage tracking

2. Flexible Billing

   • Support monthly and annual billing
   • Allow mid-cycle upgrades/downgrades
   • Prorate charges fairly
   • Offer trial periods

3. Communication

   • Send payment receipts immediately
   • Notify before billing date
   • Alert on failed payments
   • Confirm subscription changes

Testing

// tests/payments/subscription.test.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { CrossmintPaymentService } from '@/lib/payments/crossmint-payment-service';

describe('CrossmintPaymentService', () => {
  let service: CrossmintPaymentService;

  beforeAll(() => {
    service = new CrossmintPaymentService(process.env.CROSSMINT_SERVER_API_KEY!);
  });

  it('should create checkout session for Pro tier', async () => {
    const session = await service.createCheckoutSession({
      userId: 'test-user-123',
      tier: 'pro',
      email: '[email protected]',
      walletAddress: 'WALLET_ADDRESS',
    });

    expect(session.id).toBeDefined();
    expect(session.url).toContain('https://');
    expect(session.expiresAt).toBeInstanceOf(Date);
  });

  it('should process refund', async () => {
    const result = await service.processRefund('payment_123', 9.99, 'Customer request');

    expect(result.refundId).toBeDefined();
    expect(result.status).toBe('pending');
  });

  it('should verify webhook signature', () => {
    const payload = JSON.stringify({ type: 'payment.succeeded' });
    const secret = 'webhook_secret';

    const crypto = require('crypto');
    const signature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');

    const isValid = service.verifyWebhookSignature(payload, signature, secret);
    expect(isValid).toBe(true);
  });
});

Additional Resources

• Crossmint Payment API Documentation
• Webhook Security Best Practices
• Subscription Billing Patterns
• NFT Membership Systems

Conclusion

The Crossmint payment and subscription system provides BlockDrive with a complete solution for stablecoin billing, recurring subscriptions, and NFT membership management. By leveraging USDC/USDT across multiple chains, we can offer users familiar payment methods while maintaining decentralization.

The webhook-driven architecture ensures that subscription state stays synchronized between Crossmint, Supabase, and on-chain NFT memberships. Failed payment handling with automatic retries and grace periods provides a professional billing experience, while NFT membership badges create verifiable proof of tier access that can be used across the entire BlockDrive ecosystem.