PaymentMethodCard

The PaymentMethodCard component displays the user's payment method with quick access to the Stripe billing portal for updates.

v0.3.0 Update: Component now auto-opens billing portal with Better Auth Stripe plugin. No authClient prop required.

Installation

npm install @bettercone/ui

Features

✅ Auto-Portal Access - Opens Stripe billing portal automatically
✅ Presentational Mode - Display payment method details manually
✅ Card Brand Icons - Visual card brand indicators (Visa, Mastercard, Amex, etc.)
✅ Expiry Warnings - Highlights expired or expiring cards
✅ Localization - Full i18n support

Usage

import { AuthUIProvider, PaymentMethodCard } from '@bettercone/ui';
import { authClient } from '@/lib/auth-client';

export default function BillingPage() {
  return (
    <AuthUIProvider authClient={authClient}>
      {/* Shows generic "Managed via Stripe" message */}
      <PaymentMethodCard />
    </AuthUIProvider>
  );
}

import { PaymentMethodCard, type PaymentMethod } from '@bettercone/ui';

export default function BillingPage() {
  const paymentMethod: PaymentMethod = {
    id: "pm_123",
    type: "card",
    last4: "4242",
    brand: "visa",
    expiryMonth: 12,
    expiryYear: 2025,
  };

  return <PaymentMethodCard data={paymentMethod} />;
}

import { AuthUIProvider, PaymentMethodCard } from '@bettercone/ui';
import { authClient } from '@/lib/auth-client';

export default function BillingPage() {
  // Optional: provide payment method for better UX
  const paymentMethod = {
    id: "pm_123",
    type: "card" as const,
    last4: "4242",
    brand: "visa" as const,
    expiryMonth: 12,
    expiryYear: 2025,
  };

  return (
    <AuthUIProvider authClient={authClient}>
      <PaymentMethodCard data={paymentMethod} />
    </AuthUIProvider>
  );
}

Props

Prop

Type

Payment Method Types

interface PaymentMethod {
  id: string;
  type: PaymentMethodType;
  last4?: string;                  // Last 4 digits
  brand?: CardBrand;               // Card brand
  expiryMonth?: number;            // 1-12
  expiryYear?: number;             // 2025, etc.
  isDefault?: boolean;
}

type PaymentMethodType = "card" | "paypal" | "bank_account" | "other";

type CardBrand = 
  | "visa"
  | "mastercard"
  | "amex"
  | "discover"
  | "diners"
  | "jcb"
  | "unionpay"
  | "unknown";

Billing Portal Integration

The "Update Payment Method" button opens Stripe's billing portal using authClient.subscription.billingPortal().

// Internal implementation
const handleUpdate = async () => {
  const result = await authClient.subscription.billingPortal({
    referenceId: referenceId || session.user.id,
    returnUrl: window.location.href,
  });
  
  if (result.data?.url) {
    window.location.href = result.data.url;
  }
};

Stripe billing portal must be enabled in your Stripe Dashboard.

Examples

Example 1: With Expiry Warning

import { PaymentMethodCard } from '@bettercone/ui';

const expiringCard = {
  id: "pm_123",
  type: "card" as const,
  last4: "4242",
  brand: "visa" as const,
  expiryMonth: 12,
  expiryYear: 2024, // Expired!
};

<PaymentMethodCard data={expiringCard} />
// Shows warning: "Card expired"

Example 2: Custom Styling

<PaymentMethodCard 
  data={paymentMethod}
  className="shadow-lg"
  classNames={{
    base: "border-2",
    header: "bg-gradient-to-r from-blue-500 to-purple-500 text-white",
    content: "p-6",
  }}
/>

Example 3: Localized

<PaymentMethodCard
  data={paymentMethod}
  localization={{
    paymentMethod: "Método de Pagamento",
    updatePaymentMethod: "Atualizar Método",
    cardEnding: "Cartão terminado em",
    expires: "Expira",
    expired: "Expirado",
    noPaymentMethod: "Nenhum método de pagamento",
  }}
/>

Migration from v0.2.x

Breaking Change: The authClient prop has been removed. Use AuthUIProvider instead.

// Before (v0.2.x)
<PaymentMethodCard authClient={authClient} />

// After (v0.3.0) - Auto-portal
<AuthUIProvider authClient={authClient}>
  <PaymentMethodCard />
</AuthUIProvider>

// After (v0.3.0) - Presentational
<PaymentMethodCard data={paymentMethodData} />

SubscriptionCard - Display subscription
InvoiceHistoryCard - View invoices
BillingDashboard - Complete billing view

PaymentMethodCard

PaymentMethodCard

Installation

Features

Usage

Props

Payment Method Types

Billing Portal Integration

Examples

Example 1: With Expiry Warning

Example 2: Custom Styling

Example 3: Localized

Migration from v0.2.x

See Also

On this page