Card Management

Save, manage, and organize multiple payment cards for seamless checkout experiences

Overview

The nekuda Card Management system enables your users to securely save and manage multiple payment methods. The frontend SDK collects and tokenizes card information, while your backend uses the stored cards with your secret key to handle information through your AI agents or automated workflows.

Key Benefits:
• Secure Storage: Cards are tokenized and linked to user IDs you manage
• Multiple Cards: Users can save and manage multiple payment methods
• PCI Compliant: Card details are tokenized and never touch your servers
• Backend Processing: Use stored cards in your agentic workflows with secret key

Important: The frontend SDK only collects and stores payment information. Actual information handling happens on your backend using the nekuda backend SDK with your secret API key. Never expose your secret key in frontend code.

Understanding User IDs

User IDs are the key to linking saved cards with your users. You must generate and manage these IDs in your system:

// Example: Generate user ID when user signs up or logs in
function App() {
  // You generate and manage user IDs - they can be:
  // - Your database user IDs
  // - Session IDs
  // - Any unique identifier for your users
  const userId = getCurrentUserId(); // e.g., "user_abc123", "12345", etc.

  return (
    <NekudaWalletProvider
      publicKey="pk_test_..." // Your publishable key (safe for frontend)
      userId={userId}         // Your user's unique ID
    >
      {/* Your app */}
    </NekudaWalletProvider>
  );
}

Best Practices for User IDs:

• Use stable, persistent IDs (not session tokens that change)
• Store the mapping between your user records and nekuda user IDs
• Use the same user ID across sessions for returning users
• Consider using your existing user database IDs

Installation

The card management component is included in the main SDK package:

npm

npm install @nekuda/react-nekuda-js

Quick Integration

Step 1: Import Required Components

import {
  NekudaWalletProvider,
  NekudaCardManagement
} from '@nekuda/react-nekuda-js';

Step 2: Implement Card Management

Basic Implementation

function PaymentSettings() {
  const userId = getCurrentUserId(); // Your user ID management
  
  const handleCardSave = (card) => {
    console.log('Card saved:', card);
    // Handle successful card save
  };

  const handleCardDelete = (cardId) => {
    console.log('Card deleted:', cardId);
    // Handle card deletion
  };

  const handleDefaultCardSet = (cardId) => {
    console.log('Default card set:', cardId);
    // Handle default card selection
  };

  return (
    <NekudaWalletProvider
      publicKey="pk_test_..."
      userId={userId}
    >
      <NekudaCardManagement
        open={true}
        onCardSave={handleCardSave}
        onCardDelete={handleCardDelete}
        onDefaultCardSet={handleDefaultCardSet}
      />
    </NekudaWalletProvider>
  );
}

Component API Reference

<NekudaCardManagement>

The main card management component that provides a complete UI for managing payment methods.

open · boolean

Controls the visibility of the card management modal. When used without onOpenChange, the component renders inline.

onOpenChange · function

Callback function to control modal open/close state. Signature: (open: boolean) => void

onAddCardClick · function

Called when the “Add Card” button is clicked. Useful for updating prefill data or tracking user interactions.

onCardsUpdated · function

Called whenever the cards list changes (add, update, delete, or set default). Receives the updated array of saved cards.

onCardSave · function

Called when a new card is successfully saved. Receives the saved card object.

onCardUpdate · function

Called when an existing card is updated. Receives the updated card object.

onCardDelete · function

Called when a card is deleted. Receives the deleted card ID.

onDefaultCardSet · function

Called when a default card is set. Receives the card ID.

defaultCardDetails · object

Pre-fill data for the add card form. When provided, these values will populate the form fields when adding a new card. The data is consumed after being used once. Supports fields like email, billing_address, city, state, zip_code, and phone_number.

onDefaultCardDetailsConsumed · function

Called when the default card details have been consumed and applied to the form. Useful for clearing or updating the prefill data.

className · string

Optional CSS class name for custom styling.

style · object

Optional inline styles for the component.

styles · object

Base typography and font styling for the component. Includes fontFamily and fontSize.

elementsConfig · object

Styling configuration for individual form elements (cardNumber, cardExpiry, cardCvv, etc.). Each element accepts base and focus style states.

walletStyles · object

Theming styles for wallet components including modal, cardItem, and button (with primary, secondary, ghost variants).

Saved Card Object Structure

When cards are saved or retrieved, they follow this structure:

interface SavedCard {
  id: string;           // Unique card identifier
  last4: string;        // Last 4 digits of card number
  expiry: string;       // Card expiry date (MM/YY)
  brand: string;        // Card brand (visa, mastercard, etc.)
  holderName: string;   // Cardholder name
  isDefault: boolean;   // Whether this is the default card
}

Frontend Collection vs Backend Processing

The nekuda system separates payment collection (frontend) from information handling (backend):

1. Frontend: Collect & Store Cards

   Use the React SDK to securely collect and tokenize payment information. Cards are stored and linked to user IDs.

2. Backend: Retrieve Payment Methods

   Your backend uses the secret API key to retrieve stored cards and handle payments through your AI agents or automated workflows.

Usage Patterns

Card Management (Wallet)

// Let users manage their saved payment methods
function PaymentSettings() {
  const userId = getCurrentUserId(); // Your user ID

  return (
    <NekudaWalletProvider
      publicKey="pk_test_..."
      userId={userId}
    >
      <NekudaCardManagement
        onCardSave={(card) => {
          console.log('Card saved for user:', userId);
          // Card is now available for backend to retrieve
        }}
      />
    </NekudaWalletProvider>
  );
}

Security Considerations

Important Security Notes:
• Card numbers are tokenized immediately upon entry
• Only the last 4 digits are stored for display purposes
• CVV is never stored and must be re-entered for each transaction
• All card data transmission occurs over secure, encrypted channels

PCI Compliance

The card management system maintains PCI compliance by:

1. Tokenization: Sensitive card data is converted to secure tokens
2. Iframe Isolation: Card inputs are rendered in secure iframes
3. No Raw Card Storage: Your servers never receive or store actual card numbers
4. Secure Communication: All data transmission uses TLS encryption

Styling

The NekudaCardManagement component supports comprehensive styling through the nekuda three-prop styling system:

• styles - Base typography configuration
• elementsConfig - Form element styling (for add/edit card forms)
• walletStyles - Component theming for modal, card items, and buttons

For complete styling examples including dark themes and design system integration, see the Customization Guide.

Quick Example

<NekudaCardManagement
  styles={{ fontFamily: '"Inter", sans-serif', fontSize: '14px' }}
  walletStyles={{
    modal: { backgroundColor: '#fff', color: '#111827' },
    cardItem: { backgroundColor: '#fff', border: '1px solid #e5e7eb' },
    button: {
      primary: { backgroundColor: '#3b82f6', color: '#fff' }
    }
  }}
/>

Error Handling

The card management component handles errors gracefully with user-friendly messages:

function PaymentSettingsWithErrorHandling() {
  const [error, setError] = useState(null);

  return (
    <NekudaWalletProvider
      publicKey="YOUR_KEY"
      userId="user_123"
      onError={(errorInfo) => {
        if (errorInfo.apiError) {
          // Handle API errors (network, auth, etc.)
          setError(errorInfo.apiError.userMessage);
        }
      }}
    >
      {error && <Alert type="error">{error}</Alert>}

      <NekudaCardManagement
        onCardSave={(card) => {
          setError(null); // Clear any previous errors
          // Handle successful save
        }}
      />
    </NekudaWalletProvider>
  );
}

Best Practices

1. Provide Clear Feedback

   Always show loading states and success/error messages for card operations.

2. Confirm Destructive Actions

   The component includes built-in confirmation dialogs for card deletion.

3. Handle Edge Cases

   Consider scenarios like expired cards, declined cards, and network failures.

4. Secure Your Implementation

   Always use HTTPS in production and validate user permissions server-side.

Next Steps

Customization Guide

Learn how to style components with themes, dark mode, and design system integration

Error Handling

Handle validation errors, API failures, and edge cases gracefully

Advanced Usage

Explore prefilling data, complex workflows, and multiple components

Support

Get help from the nekuda support team