Payment Icons

v1.1.2

Documentation Under Review

Installation

Install the Payment Icons component from the Catalyst component library:

npm install '@pmi/catalyst-payment-icons'

Overview

The Payment Icons package provides a collection of payment method icons for e-commerce and checkout flows. Each icon component is built on top of the BaseIcon component from @pmi/catalyst-icons, ensuring consistent sizing, coloring, and rendering across all applications.

Available Payment Methods

The package includes 15 payment method icon components representing major payment systems:

• Credit Cards: Visa, Maestro (Maestro), American Express (AMEX), Discover, Diners Club, JCB
• Digital Wallets: PayPal, AliPay, WeChat Pay, Cash App
• Buy Now, Pay Later: Klarna
• Regional Payment Systems: RuPay (India), UPI (Unified Payments Interface), NET Banking
• Default: Generic payment card icon for unknown or unsupported methods

Each payment method is exported as a named component (e.g., Visa, PayPal, Klarna, CashApp).

Gallery

Examples

Basic Usage

Display a payment icon with default settings:

All Payment Icons Gallery

Display all available payment method icons:

API Reference

All payment icon components accept the same props as BaseIcon from @pmi/catalyst-icons:

Size Scale Reference

Payment icon sizes use CSS variable-based scaling:

• xs: 16px × 16px
• sm: 20px × 20px
• md: 24px × 24px
• lg: 32px × 32px (default, recommended for payment icons)
• xl: 40px × 40px
• full: 100% of parent width and height

Available Payment Icon Components

Import payment icons using their payment method name:

import {
  // Credit Cards
  Visa,
  Maestro,
  AMEX,
  Discover,
  DinersClub,
  JCB,

  // Digital Wallets
  PayPal,
  AliPay,
  WeChatPay,
  CashApp,

  // Buy Now, Pay Later
  Klarna,

  // Regional Payment Systems
  RuPay,
  UPI,
  NETBanking,

  // Default
  Default,
} from '@pmi/catalyst-payment-icons';

Payment Method Categories

Credit Cards

Major international credit card brands:

• Visa: Global payment network, most widely accepted
• Maestro: Global payment network, includes Maestro debit cards
• AMEX: American Express, premium card network
• Discover: US-based credit card network
• Diners Club: International charge card network
• JCB: Japan Credit Bureau, popular in Asia

Digital Wallets

Online payment services and digital wallets:

• PayPal: Global digital wallet and payment service
• AliPay: Chinese digital wallet by Alibaba, widely used in Asia
• WeChat Pay: Chinese payment service integrated with WeChat
• Cash App: US-based peer-to-peer payment service by Block (formerly Square)

Buy Now, Pay Later

Installment and deferred payment services:

• Klarna: Global buy-now-pay-later service offering flexible payment options

Regional Payment Systems

Region-specific payment methods:

• RuPay: Indian domestic card payment network
• UPI: Unified Payments Interface, India's instant payment system
• NET Banking: Online banking payment method, popular in India

Default Icon

• Default: Generic payment card icon for unknown or unsupported payment methods

Usage Guidelines

Payment Icon Selection

Choose payment icons based on your target market and supported methods:

• Global E-commerce: Visa, Maestro, AMEX, PayPal, Klarna
• US Market: Visa, Maestro, AMEX, Discover, CashApp
• European Market: Visa, Maestro, Klarna
• Asian Markets: Visa, Maestro, AliPay, WeChat Pay
• Indian Market: Visa, Maestro, RuPay, UPI, NET Banking
• Unknown Methods: Use Default icon as fallback

Color Usage

• Original Colors: Always use color="original" to preserve payment brand colors for recognition
• Accessibility: Ensure sufficient contrast between icon and background
• Consistency: Display all payment icons with the same size and styling

Size and Spacing

• Minimum Size: Use at least size="md" (24px) for clear recognition
• Recommended Size: Use size="lg" (32px) for optimal visibility
• Consistent Sizing: Display all payment icons at the same size
• Spacing: Maintain adequate spacing between icons (at least 12-16px)
• Grid Layout: Use consistent grid for multiple icons

Context-Specific Recommendations

• Checkout Forms: size="lg", display accepted methods prominently
• Payment Method Selection: size="lg" to size="xl", interactive buttons
• Footer "We Accept": size="md", grouped display
• Mobile Checkout: Ensure touch targets are at least 44px × 44px
• Invoices/Receipts: size="sm" to size="md", subtle display

Accessibility

All payment icon components are built with accessibility in mind:

WCAG 2.1 AA Compliance

• Hidden from Screen Readers: Icons have aria-hidden="true" by default (payment method names provided separately)
• Semantic Context: When icons represent selectable options, provide descriptive labels
• Color Recognition: Icons maintain brand colors for recognition, but don't rely solely on color
• Touch Targets: Ensure interactive payment icons meet minimum 44px × 44px target size
• Alternative Text: Provide text alternatives for payment method names

Best Practices

// ✅ Good: Icon with descriptive label in button
<button aria-label="Pay with Visa">
  <Visa size="lg" color="original" />
  <span>Visa</span>
</button>

// ✅ Good: Icon in selection interface with label
<div role="radiogroup" aria-label="Select payment method">
  <button role="radio" aria-checked={selected === 'visa'}>
    <Visa size="lg" color="original" />
    <span className="sr-only">Visa</span>
  </button>
</div>

// ✅ Good: Non-interactive display with context
<div aria-label="Accepted payment methods">
  <Visa size="md" color="original" />
  <Maestro size="md" color="original" />
  <span className="sr-only">We accept Visa and Maestro</span>
</div>

// ❌ Avoid: Icon without context
<div>
  <Visa size="lg" />
</div>

Testing Considerations

Payment icon components include data-testid support for integration testing:

<Visa data-testid="payment-icon-visa" size="lg" color="original" />

Design Tokens

Payment icons use the following design tokens from the Catalyst theme:

Size Tokens

• --scale-16: Extra small (xs)
• --scale-20: Small (sm)
• --scale-24: Medium (md)
• --scale-32: Large (lg) - recommended for payment icons
• --scale-40: Extra large (xl)
• Custom sizing via parent container for full size

Color Preservation

Payment icons should always use color="original" to maintain brand recognition. The following applies for container backgrounds:

• --colors-white: White background (standard)
• --colors-neutral-50: Light neutral background
• Border colors for card-like containers: --colors-neutral-200

Technical Details

Component Generation

Payment icon components are auto-generated from SVG assets. Do not modify icon component files directly. Any changes should be made in the build script at ~/process-packages-assets.cjs.

Bundle Optimization

Each payment icon component is exported individually, enabling tree-shaking. Import only the icons you need to minimize bundle size:

// ✅ Optimal: Tree-shakeable imports
import { Visa, Maestro, PayPal } from '@pmi/catalyst-payment-icons';

// ⚠️ Avoid: Wildcard imports prevent tree-shaking
import * as PaymentIcons from '@pmi/catalyst-payment-icons';

SVG Rendering

Payment icons use react-inlinesvg for SVG rendering, which:

• Preserves embedded payment brand colors
• Ensures unique IDs for multiple instances
• Maintains crisp rendering at all sizes
• Supports CSS custom properties for theming

Brand Compliance

• Color Accuracy: All colors match official payment brand guidelines
• Proportions: Aspect ratios are precisely maintained (credit cards typically 3:2)
• Recognition: Icons designed for instant brand recognition
• Updates: Icons are version-controlled and updated centrally

Usage Examples

In Checkout Form

import { Visa, Maestro, AMEX } from '@pmi/catalyst-payment-icons';

function CheckoutForm() {
  return (
    <div className="space-y-4">
      <label className="block">
        <span className="text-sm font-medium">Card Number</span>
        <div className="mt-1 relative">
          <input
            type="text"
            placeholder="1234 5678 9012 3456"
            className="w-full px-3 py-2 border border-neutral-300 rounded"
          />
          <div className="absolute right-2 top-2 flex gap-1">
            <Visa size="sm" color="original" />
            <Maestro size="sm" color="original" />
            <AMEX size="sm" color="original" />
          </div>
        </div>
      </label>
    </div>
  );
}

In Payment Method List

import { Visa, Maestro, PayPal } from '@pmi/catalyst-payment-icons';

function SavedPaymentMethods() {
  return (
    <div className="space-y-2">
      <button className="w-full p-3 flex items-center justify-between border rounded hover:bg-neutral-50">
        <div className="flex items-center gap-3">
          <Visa size="lg" color="original" />
          <div className="text-left">
            <p className="text-sm font-medium">Visa ending in 4242</p>
            <p className="text-xs text-neutral-600">Expires 12/25</p>
          </div>
        </div>
        <span className="text-xs text-neutral-600">Default</span>
      </button>
    </div>
  );
}

In Footer

import { Visa, Maestro, AMEX, PayPal } from '@pmi/catalyst-payment-icons';

function Footer() {
  return (
    <footer className="bg-neutral-900 text-white p-8">
      <div className="container mx-auto">
        <div className="flex items-center gap-2 text-xs">
          <span>We accept:</span>
          <div className="flex gap-2">
            <Visa size="sm" color="original" />
            <Maestro size="sm" color="original" />
            <AMEX size="sm" color="original" />
            <PayPal size="sm" color="original" />
          </div>
        </div>
      </div>
    </footer>
  );
}

Related Components

• Icons - Base icon component system that payment icons extend
• Social Icons - Social media platform icons
• Flags - Country and territory flag assets
• Button - Button component for payment actions
• Select - Select component for payment method dropdowns

See Also

• BaseIcon Component Documentation
• Accessibility Best Practices
• Design Tokens Documentation
• PCI DSS Compliance (external)