Advanced Usage

Custom Element Configurations

Define a custom set and order of payment elements if <NekudaPaymentForm> doesn’t fit your needs. This feature relies on you providing an elementId to your element instances that matches the elementId specified in the configuration here.

Show Custom Element Configuration Example

const customElementsConfig = [
{ elementId: 'custom-card-number', type: 'cardNumber', options: { placeholder: 'Enter card number here' } },
{ elementId: 'custom-expiry-date', type: 'cardExpiry' },
// Add other element types like 'cardCvc', 'name', 'email' as needed
];

<NekudaWalletProvider elements={customElementsConfig} publicKey="YOUR_NEKUDA_PUBLIC_KEY">
{/* Manually render each element defined in customElementsConfig, ensuring to pass the matching elementId */}
<CardNumberElement elementId="custom-card-number" />
<CardExpiryElement elementId="custom-expiry-date" />
{/* ... other elements ... */}
</NekudaWalletProvider>

Custom Placeholders

Provide custom placeholder text for elements. You can set these globally on <NekudaWalletProvider> using the placeholders prop (targeting by element type or by a specific elementId), or directly on an individual element instance via its placeholder prop or options.placeholder.

Show Custom Placeholders Example (Provider-level)

const customPlaceholders = {
'cardNumber': 'Default Card Number Placeholder', // Applies to all CardNumberElements without a specific ID or direct prop
'paymentform-name': 'Your Full Name (via Provider)', // For an element with elementId="paymentform-name"
'custom-card-placeholder-id': 'Credit Card Number (via Provider)', // For an element with elementId="custom-card-placeholder-id"
};

<NekudaWalletProvider placeholders={customPlaceholders} publicKey="YOUR_NEKUDA_PUBLIC_KEY">
<NekudaPaymentForm />
<CardNumberElement />
<NameElement elementId="paymentform-name" />
<CardNumberElement elementId="custom-card-placeholder-id" />
<EmailElement placeholder="Directly on element" />
</NekudaWalletProvider>

Beyond visual styles, you can also customize the placeholder text for form inputs. This can be done globally using the placeholders prop on the <NekudaWalletProvider> (see the Custom Placeholders subsection under Advanced Usage for details), or for individual elements using their options prop. For example, to set a placeholder for a specific CardNumberElement:

<CardNumberElement options={{ placeholder: "Enter your card number" }} />

Refer to the documentation for each element to see available styling selectors and properties.

Advanced Card Management Patterns

Integrating Card Management with Checkout Flows

Create a seamless checkout experience by combining saved cards with new payment options:

Show Complete Checkout Flow Example

import { useState, useEffect } from 'react';
import {
NekudaWalletProvider,
NekudaPaymentForm,
NekudaCardManagement,
createWalletApiService,
useNekudaWallet
} from '@nekuda/react-nekuda-js';

// Create API service
const apiService = createWalletApiService({
customerId: 'your-customer-id',
publicKey: 'YOUR_PUBLIC_KEY'
});

function CheckoutFlow({ userId, orderTotal }) {
const [savedCards, setSavedCards] = useState([]);
const [selectedCard, setSelectedCard] = useState(null);
const [useNewCard, setUseNewCard] = useState(false);
const [showCardManager, setShowCardManager] = useState(false);
const { elements } = useNekudaWallet();

// Fetch saved cards on mount
useEffect(() => {
async function loadCards() {
try {
const cards = await apiService.getCardsForSdk(userId);
setSavedCards(cards);
// Auto-select default card if available
const defaultCard = cards.find(card => card.isDefault);
if (defaultCard) {
setSelectedCard(defaultCard);
}
} catch (error) {
console.error('Failed to load saved cards:', error);
}
}
loadCards();
}, [userId]);

const handlePayment = async () => {
if (selectedCard && !useNewCard) {
// Handle information with saved card
try {
const result = await processPaymentWithSavedCard(selectedCard.id, orderTotal);
console.log('Information handled successfully:', result);
} catch (error) {
console.error('Payment failed:', error);
}
} else {
// Process payment with new card
try {
const result = await elements.submit();
console.log('New card information handled successfully:', result);
} catch (error) {
console.error('Payment failed:', error);
}
}
};

return (

<div className="checkout-container">
<h2>Payment Method</h2>

    {/* Saved Cards Section */}
    {savedCards.length > 0 && (
      <div className="saved-cards-section">
        <h3>Saved Cards</h3>
        {savedCards.map(card => (
          <label key={card.id} className="card-option">
            <input
              type="radio"
              name="payment-method"
              checked={selectedCard?.id === card.id && !useNewCard}
              onChange={() => {
                setSelectedCard(card);
                setUseNewCard(false);
              }}
            />
            <div className="card-details">
              <span>{card.brand} •••• {card.last4}</span>
              <span>Expires {card.expiry}</span>
              {card.isDefault && <span className="default-badge">Default</span>}
            </div>
          </label>
        ))}

        <button
          type="button"
          onClick={() => setShowCardManager(true)}
          className="manage-cards-btn"
        >
          Manage Cards
        </button>
      </div>
    )}

    {/* New Card Option */}
    <label className="card-option">
      <input
        type="radio"
        name="payment-method"
        checked={useNewCard}
        onChange={() => setUseNewCard(true)}
      />
      <span>Use a new card</span>
    </label>

    {/* Payment Form for New Card */}
    {useNewCard && (
      <div className="new-card-form">
        <NekudaPaymentForm />
      </div>
    )}

    {/* Order Summary */}
    <div className="order-summary">
      <h3>Order Total: ${orderTotal}</h3>
      <button
        onClick={handlePayment}
        disabled={!selectedCard && !useNewCard}
        className="pay-button"
      >
        Complete Information Handling
      </button>
    </div>

    {/* Card Management Modal */}
    <NekudaCardManagement
      open={showCardManager}
      onOpenChange={setShowCardManager}
      apiService={apiService}
      userId={userId}
      onCardSave={(card) => {
        // Refresh saved cards list
        setSavedCards(prev => [...prev, card]);
        setSelectedCard(card);
        setUseNewCard(false);
        setShowCardManager(false);
      }}
      onCardDelete={(cardId) => {
        setSavedCards(prev => prev.filter(c => c.id !== cardId));
        if (selectedCard?.id === cardId) {
          setSelectedCard(null);
        }
      }}
      onDefaultCardSet={(cardId) => {
        setSavedCards(prev => prev.map(c => ({
          ...c,
          isDefault: c.id === cardId
        })));
      }}
    />
  </div>

);
}

// Wrap with provider
function CheckoutPage() {
return (

<NekudaWalletProvider
publicKey="YOUR_PUBLIC_KEY"
userId="user_123"
onSuccess={(info) => {
  console.log("Information handled successfully:", info);
  // Redirect to success page
}}
onError={(error) => {
  console.error("Information handling error:", error);
  // Show error to user
}}
>
<CheckoutFlow userId="user_123" orderTotal={99.99} />
</NekudaWalletProvider>
); }

Programmatic Card Management

Use the API service directly for custom card management implementations:

Show Programmatic API Usage

import { createWalletApiService } from '@nekuda/react-nekuda-js';

// Initialize the service
const walletApi = createWalletApiService({
customerId: 'your-customer-id',
publicKey: 'YOUR_PUBLIC_KEY'
});

// Card Management Functions
async function cardManagementExamples(userId) {
try {
  // 1. Fetch all saved cards
  const cards = await walletApi.getCardsForSdk(userId);
  console.log('User cards:', cards);

  // 2. Set a default card
  if (cards.length > 0) {
    const cardId = cards[0].id;
    await walletApi.setDefaultCard(cardId, userId);
    console.log('Default card set:', cardId);
  }

  // 3. Delete a card
  const cardToDelete = cards.find(c => !c.isDefault);
  if (cardToDelete) {
    await walletApi.deleteCard(cardToDelete.id, userId);
    console.log('Card deleted:', cardToDelete.id);
  }

  // 4. Collect and save new payment data
  const paymentData = {
    card_number: '4242424242424242',
    card_exp: '12/25',
    card_cvv: '123',
    card_holder: 'John Doe',
    email: 'john@example.com',
    billing_address: '123 Main St',
    zip_code: '12345'
  };

  const result = await walletApi.collectPaymentData(userId, paymentData);
  console.log('Payment data collected:', result);

} catch (error) {
  console.error('Card management error:', error);

  // Handle specific error types
  if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
  }
}
}

// React Hook for Card Management
function useCardManagement(userId) {
const [cards, setCards] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

const fetchCards = useCallback(async () => {
  setLoading(true);
  setError(null);
  try {
    const userCards = await walletApi.getCardsForSdk(userId);
    setCards(userCards);
  } catch (err) {
    setError(err);
  } finally {
    setLoading(false);
  }
}, [userId]);

const deleteCard = useCallback(async (cardId) => {
  try {
    await walletApi.deleteCard(cardId, userId);
    setCards(prev => prev.filter(c => c.id !== cardId));
  } catch (err) {
    setError(err);
    throw err;
  }
}, [userId]);

const setDefaultCard = useCallback(async (cardId) => {
  try {
    await walletApi.setDefaultCard(cardId, userId);
    setCards(prev => prev.map(c => ({
      ...c,
      isDefault: c.id === cardId
    })));
  } catch (err) {
    setError(err);
    throw err;
  }
}, [userId]);

useEffect(() => {
  fetchCards();
}, [fetchCards]);

return {
  cards,
  loading,
  error,
  refetch: fetchCards,
  deleteCard,
  setDefaultCard
};
}

Multi-step Forms with Card Selection

Implement complex checkout flows with card selection as a step:

Show Multi-step Checkout Example

function MultiStepCheckout() {
const [step, setStep] = useState(1); // 1: Cart, 2: Shipping, 3: Payment, 4: Review
const [selectedCard, setSelectedCard] = useState(null);
const [paymentMethod, setPaymentMethod] = useState('saved'); // 'saved' or 'new'

const PaymentStep = () => {
const [cards, setCards] = useState([]);

  return (
    <div className="payment-step">
      <h3>Step 3: Payment Information</h3>

      {/* Payment Method Toggle */}
      <div className="payment-method-toggle">
        <button
          className={paymentMethod === 'saved' ? 'active' : ''}
          onClick={() => setPaymentMethod('saved')}
        >
          Saved Cards
        </button>
        <button
          className={paymentMethod === 'new' ? 'active' : ''}
          onClick={() => setPaymentMethod('new')}
        >
          New Card
        </button>
      </div>

      {paymentMethod === 'saved' ? (
        <NekudaCardManagement
          apiService={apiService}
          userId="user_123"
          savedCards={cards}
          onCardSave={(card) => {
            setCards([...cards, card]);
            setSelectedCard(card);
          }}
        />
      ) : (
        <NekudaPaymentForm />
      )}

      <div className="step-navigation">
        <button onClick={() => setStep(2)}>Previous</button>
        <button
          onClick={() => setStep(4)}
          disabled={paymentMethod === 'saved' && !selectedCard}
        >
          Review Order
        </button>
      </div>
    </div>
  );

};

// Render current step
switch(step) {
case 1: return <CartStep onNext={() => setStep(2)} />;
case 2: return <ShippingStep onNext={() => setStep(3)} onBack={() => setStep(1)} />;
case 3: return <PaymentStep />;
case 4: return <ReviewStep selectedCard={selectedCard} paymentMethod={paymentMethod} />;
default: return null;
}
}

Subscription Management with Saved Cards

Handle recurring payments and subscription updates:

Show Subscription Management Example

function SubscriptionManager({ subscription, userId }) {
const [defaultCard, setDefaultCard] = useState(null);
const [showCardManager, setShowCardManager] = useState(false);

useEffect(() => {
  // Load the current payment method for subscription
  async function loadPaymentMethod() {
    const cards = await apiService.getCardsForSdk(userId);
    const defaultCard = cards.find(c => c.isDefault);
    setDefaultCard(defaultCard);
  }
  loadPaymentMethod();
}, [userId]);

const handleUpdatePaymentMethod = async (newCardId) => {
  try {
    // Update subscription payment method
    await updateSubscriptionPaymentMethod(subscription.id, newCardId);

    // Update local state
    const cards = await apiService.getCardsForSdk(userId);
    const newDefault = cards.find(c => c.id === newCardId);
    setDefaultCard(newDefault);

    toast.success('Payment method updated successfully');
  } catch (error) {
    toast.error('Failed to update payment method');
  }
};

return (
  <div className="subscription-manager">
    <h2>Subscription: {subscription.planName}</h2>
    <p>Next billing date: {subscription.nextBillingDate}</p>
    <p>Amount: ${subscription.amount}/month</p>

    <div className="payment-method-section">
      <h3>Payment Method</h3>
      {defaultCard ? (
        <div className="current-card">
          <span>{defaultCard.brand} •••• {defaultCard.last4}</span>
          <span>Expires {defaultCard.expiry}</span>
          <button onClick={() => setShowCardManager(true)}>
            Update Payment Method
          </button>
        </div>
      ) : (
        <button onClick={() => setShowCardManager(true)}>
          Add Payment Method
        </button>
      )}
    </div>

    <NekudaCardManagement
      open={showCardManager}
      onOpenChange={setShowCardManager}
      apiService={apiService}
      userId={userId}
      onDefaultCardSet={(cardId) => {
        handleUpdatePaymentMethod(cardId);
        setShowCardManager(false);
      }}
    />
  </div>
);
}

Prefilling Form Data

The Nekuda SDK provides a clean, programmatic API for prefilling form fields with customer data. This eliminates the need for manual DOM queries or understanding internal iframe communication. The prefill API is exposed through the elements object from the useNekudaWallet hook:

const { elements } = useNekudaWallet();

API Methods

prefill(data: Partial<CardFormData>)

function

Prefills multiple fields at once with a data object.

elements.prefill({
  email: "john@example.com",
  billingAddress: "123 Main St",
  city: "New York",
  state: "NY",
  zipCode: "10001",
  phoneNumber: "+1234567890",
});

prefillField(fieldType: NekudaElementType, value: string)

function

Prefills a specific field by its type.

elements.prefillField("email", "john@example.com");

clearField(fieldType: NekudaElementType)

function

Clears a specific field.

elements.clearField("email");

clearAll()

function

Clears all form fields.

elements.clearAll();

Field Types

The following field types are supported for prefilling. The key in the prefill method corresponds to the CardFormData type, which maps to a NekudaElementType.

email - Email address
billingAddress - Billing address
city - City
state - State/Province
zipCode - ZIP/Postal code
phoneNumber - Phone number

Example Usage

Show Payment Form Prefill

import { useNekudaWallet, NekudaPaymentForm } from '@nekuda/react-sdk';

function PaymentPage() {
const { elements } = useNekudaWallet();

  const prefillWithSavedData = () => {
    // Fetch customer data from your backend
    const customerData = fetchCustomerData();

    // Prefill the form
    elements.prefill({
      email: customerData.email,
      billingAddress: customerData.address,
      city: customerData.city,
      state: customerData.state,
      zipCode: customerData.zip,
      phoneNumber: customerData.phone
    });
  };

  return (
    <div>
      <button onClick={prefillWithSavedData}>
        Use Saved Information
      </button>
      <NekudaPaymentForm />
    </div>
  );

}

Show Card Management Prefill

import { useNekudaWallet, NekudaCardManagement } from '@nekuda/react-sdk';

function CardManagementPage() {
  const { elements } = useNekudaWallet();

  const prefillTestData = () => {
    elements.prefill({
      email: 'test@example.com',
      billingAddress: '123 Test Street',
      city: 'Test City',
      state: 'TS',
      zipCode: '12345',
      phoneNumber: '+1234567890'
    });
  };

  return (
    <div>
      <button onClick={prefillTestData}>
        Fill Test Data
      </button>
      <NekudaCardManagement />
    </div>
  );
}

Show Progressive Field Filling

function CheckoutForm() {
  const { elements } = useNekudaWallet();
  const [userEmail, setUserEmail] = useState('');

  // Prefill email when user logs in
  useEffect(() => {
    if (userEmail) {
      elements.prefillField('email', userEmail);
    }
  }, [userEmail, elements]);


  return <NekudaPaymentForm />;

}

Best Practices

Wait for SDK Readiness: Ensure the SDK is loaded and iframes are ready before calling prefill methods. You may need to add a small delay.
Security: When handling sensitive data like card numbers, ensure it is transmitted securely to the frontend and cleared from memory as soon as it’s passed to the SDK.
User Experience: Consider prefilling non-sensitive fields (email, address) automatically, while letting users enter sensitive card details manually for security peace of mind.
Validation: The SDK will validate prefilled data. Invalid data will be rejected by the secure iframes, and the fields will show an error state.

Migration from Direct DOM Access

If you were previously using document.querySelectorAll to find iframes and send messages directly:

Show Migration Example

// ❌ Old approach - Don't do this
const iframes = document.querySelectorAll('iframe[src*="collect"]');
iframes.forEach(iframe => {
iframe.contentWindow.postMessage({
  type: 'nekuda_set_prefill',
  payload: { value: 'test@example.com' }
}, '*');
});

// ✅ New approach - Use the SDK API
elements.prefillField('email', 'test@example.com');

The new API provides several advantages:

Handles iframe communication internally
Manages secure origins properly
Provides type safety for field names
Works consistently across different environments
Simplifies error handling and validation feedback

Get Started

Frontend SDK

Backend SDK

Security

Advanced Usage

Advanced Usage

Custom Element Configurations

Custom Placeholders

Advanced Card Management Patterns

Integrating Card Management with Checkout Flows

Programmatic Card Management

Multi-step Forms with Card Selection

Subscription Management with Saved Cards

Prefilling Form Data

API Methods

Field Types

Example Usage

Best Practices

Migration from Direct DOM Access

Get Started

Frontend SDK

Backend SDK

Security

​Advanced Usage

​Custom Element Configurations

​Custom Placeholders

​Advanced Card Management Patterns

​Integrating Card Management with Checkout Flows

​Programmatic Card Management

​Multi-step Forms with Card Selection

​Subscription Management with Saved Cards

​Prefilling Form Data

​API Methods

​Field Types

​Example Usage

​Best Practices

​Migration from Direct DOM Access

Advanced Usage

Custom Element Configurations

Custom Placeholders

Advanced Card Management Patterns

Integrating Card Management with Checkout Flows

Programmatic Card Management

Multi-step Forms with Card Selection

Subscription Management with Saved Cards

Prefilling Form Data

API Methods

Field Types

Example Usage

Best Practices

Migration from Direct DOM Access