Skip to main content

​
Overview

This guide covers advanced usage patterns for the nekuda React SDK, including prefilling form data, using multiple components together, and handling complex payment workflows.

​
Using Components Together

You can use both NekudaPaymentForm and NekudaCardManagement components within the same application to provide a complete payment experience: 
import { useState } from 'react';
import { 
  NekudaWalletProvider, 
  NekudaPaymentForm, 
  NekudaCardManagement,
  useNekudaWallet 
} from '@nekuda/react-nekuda-js';

function PaymentPage() {
  const [showCardManager, setShowCardManager] = useState(false);
  
  return (
    <NekudaWalletProvider publicKey="pk_test_..." userId={userId}>
      <div>
        {/* Payment form for new cards */}
        <NekudaPaymentForm 
          onSave={(data) => console.log('Payment saved:', data)}
        />
        
        {/* Button to manage saved cards */}
        <button onClick={() => setShowCardManager(true)}>
          Manage Saved Cards
        </button>
        
        {/* Card management modal */}
        <NekudaCardManagement
          open={showCardManager}
          onOpenChange={setShowCardManager}
          onCardSave={(card) => console.log('Card saved:', card)}
          onCardDelete={(cardId) => console.log('Card deleted:', cardId)}
        />
      </div>
    </NekudaWalletProvider>
  );
}

​
Handling Errors

Implement comprehensive error handling for both payment collection and card management: 
import { useState } from 'react';
import {
  NekudaWalletProvider,
  NekudaPaymentForm,
  NekudaCardManagement
} from '@nekuda/react-nekuda-js';

function PaymentWithErrorHandling() {
  const [errors, setErrors] = useState({});
  
  const handleValidationError = (fieldErrors) => {
    console.log('Validation errors:', fieldErrors);
    // fieldErrors is an array of { fieldName, message, fieldType }
    const errorMap = {};
    fieldErrors.forEach(err => {
      errorMap[err.fieldName] = err.message;
    });
    setErrors(errorMap);
  };
  
  const handleGeneralError = (error) => {
    console.error('Error occurred:', error);
    // error contains { code, message, severity, recoverable, suggestedAction }
    
    if (error.code === 'NETWORK_TIMEOUT' && error.recoverable) {
      // Retry the operation
      setTimeout(() => window.location.reload(), 3000);
    }
  };
  
  return (
    <NekudaWalletProvider
      publicKey="pk_test_..."
      userId={userId}
      onValidationError={handleValidationError}
      onError={handleGeneralError}
    >
      <NekudaPaymentForm />
      {errors.cardNumber && <span className="error">{errors.cardNumber}</span>}
    </NekudaWalletProvider>
  );
}

​
Prefilling Form Data

The nekuda SDK provides a prefill API for populating form fields with customer data. The prefill methods are exposed through the elements object from the useNekudaWallet hook: 
const { elements } = useNekudaWallet();
The prefill API is currently experimental and may not work reliably in all scenarios. Test thoroughly before using in production.

​
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

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

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

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

    // Prefill the form
    if (elements) {
      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>
  );
}

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

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

  const prefillTestData = () => {
    if (elements) {
      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>
  );
}

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

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

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

  return <NekudaPaymentForm />;
}

​
Important Notes

  1. Elements Availability: Always check if elements exists before calling prefill methods
  2. Field Limitations: Only non-sensitive billing information can be prefilled (email, address, city, state, zip, phone)
  3. Card Data: Card numbers, expiry dates, and CVV cannot be prefilled for security reasons
  4. Timing: The prefill methods may not work immediately after component mount - allow time for iframes to initialize
⌘I