Nekuda Wallet

The official React SDK for integrating nekuda's wallet component into your AI agent application. Let your users save and manage payment credentials that your AI agent can use for automated purchases.

Full documentation is available at nekuda Docs.

Overview

The React nekuda-js SDK provides a complete wallet component for managing payment methods, contact information, and shipping addresses. Card data is tokenized and stored securely via PCI-compliant iframes, keeping you out of PCI scope.

Requirements

• Node.js 20.0.0 or higher
• React 18+ or React 19
• Valid nekuda public key from app.nekuda.ai

Key Features

• Complete Wallet UI - Payment methods, contact info, and shipping address management
• PCI-compliant Security - Card data never touches your frontend via isolated iframes
• Customizable Theming - Light, dark, and minimal themes with full style override support
• Mobile Responsive - Automatically adapts to mobile screens
• Type-safe - Full TypeScript support with type definitions included

Installation

# npm
npm install @nekuda/wallet

# yarn
yarn add @nekuda/wallet

Quick Start

import { WalletProvider, NekudaWallet } from '@nekuda/wallet';

function UserSettings() {
  const userId = currentUser.id; // Your user's ID

  return (
    <WalletProvider publicKey="pk_test_..." userId={userId}>
      <NekudaWallet />
    </WalletProvider>
  );
}

Get your public key from app.nekuda.ai. Users can now save and manage payment methods. Your backend can retrieve them via the nekuda backend SDK.

What You Get

The NekudaWallet component provides:

1. Payment Methods Tab - Add, edit, delete, and set default cards
2. Settings Tab - Manage contact information and shipping address
3. Secure Collection - All card data collected via PCI-compliant iframes
4. Tokenization - Cards are tokenized and stored server-side

Frontend to Backend Flow

// Frontend: User adds card via wallet
<WalletProvider publicKey="pk_test_..." userId="user_123">
  <NekudaWallet />
</WalletProvider>

# Backend: Retrieve card when AI agent needs to make purchase
from nekuda import NekudaClient, MandateData

client = NekudaClient.from_env()
user = client.user("user_123")  # Same userId

# 3-step mandate flow
mandate_resp = user.create_mandate(MandateData(...))
reveal_resp = user.request_card_reveal_token(mandate_resp.mandate_id)
card = user.reveal_card_details(reveal_resp.reveal_token)

# AI agent now has: card.card_number, card.cvv, card.card_expiry_date

Frontend stores cards (tokenized). Backend retrieves cards (full details) for your AI agent to complete purchases.

Key Concepts

userId

Your user's unique identifier from your system (e.g., database ID). Must be consistent across frontend and backend. nekuda doesn't generate this - you provide it.

publicKey

Your public API key (pk_test_... or pk_live_...) from app.nekuda.ai. Safe to use in frontend code. Only allows card collection, not retrieval.

Never use your secret key (sk_*) in frontend code - it's for backend only.

Accessing Payment Method Metadata

Use useWallet() to access non-sensitive card metadata in your React components:

import { useWallet } from '@nekuda/wallet';

function Dashboard() {
  const wallet = useWallet();
  const defaultCard = wallet.payments.list.find(pm => pm.isDefault);

  return (
    <div>
      <p>{wallet.payments.list.length} cards saved</p>
      {defaultCard && (
        <p>Default: •••• {defaultCard.lastFourDigits}</p>
      )}
    </div>
  );
}

Available fields: id, lastFourDigits, expiryDate, cardType, cardHolderName, isDefault, billingAddress, timestamps.

Full card numbers and CVVs are never exposed. Backend SDK only.

Customization

Choose from three styling modes:

// Pre-built themes (light, dark, minimal)
<NekudaWallet mode="themed" theme="dark" />

// Custom style overrides
<NekudaWallet mode="custom" styles={yourCustomStyles} />

// Headless mode - full control over appearance
<NekudaWallet mode="headless" />

See Styling & Theming for complete customization options.

Component Props

<WalletProvider> (Required)

| Prop | Type | Required | Description | |------|------|----------|-------------| | publicKey | string | ✅ | Your nekuda public API key (pk_test_... or pk_live_...) | | userId | string | ✅ | Your user's unique identifier from your system | | debug | boolean | | Enable debug logging (default: false) |

<NekudaWallet> (All props optional)

| Prop | Type | Default | Description | |------|------|---------|-------------| | mode | 'themed' \| 'headless' \| 'custom' | 'themed' | Styling mode | | theme | 'light' \| 'dark' \| 'minimal' | 'light' | Pre-built theme when mode="themed" | | className | string | | CSS class name for container | | styles | Partial<WalletStyles> | | Custom style overrides | | showSettings | boolean | true | Show Settings tab (contact/shipping) | | defaultContact | Partial<IdentityData> | | Pre-fill contact information | | defaultShipping | Partial<AddressData> | | Pre-fill shipping address | | defaultBilling | Partial<AddressData> | | Pre-fill billing address for new cards | | onError | (error: Error) => void | | Callback when any operation fails | | onContactChange | (data: IdentityData) => void | | Callback when contact info updated | | onShippingChange | (data: AddressData) => void | | Callback when shipping updated | | renderEmptyState | () => ReactNode | | Custom component when no saved cards |

Security & PCI Compliance

Card inputs render in secure iframes at collect.nekuda.ai - your frontend cannot access them. The wallet only shows tokenized data (last 4 digits, expiry, name). Full card numbers and CVVs are never transmitted to your frontend.

Key separation:

• Public key (pk_*): Frontend collection only
• Secret key (sk_*): Backend retrieval only

HTTPS required in production. This design keeps you out of PCI scope.

Documentation

• Wallet Overview - Complete guide and setup
• Integration Patterns - Real-world examples
• Payment Methods Tab - Card management features
• Settings Tab - Contact and shipping management
• Styling & Theming - Customize appearance
• Backend SDK - Retrieve card details for AI agent

Support

• 📧 Email: [email protected]
• 📖 Docs: docs.nekuda.ai
• 🌐 Portal: app.nekuda.ai

License

MIT License - see LICENSE file for details.