Getting Started

Overview

The @nekuda/react-nekuda-js SDK securely collects payment information and manages saved payment methods, enabling your AI agents to handle both guest and returning customer checkouts.

Requirements:
• React 17+ or React 18
• Valid nekuda public key

Key Features:

PCI-compliant secure collection via isolated iframes
Card Management - Save, update, and manage multiple payment methods
Customizable React components with theming support
Simple integration with automatic API configuration
Saved Cards - Enable one-click checkout for returning customers

Installation

npm install @nekuda/react-nekuda-js

Quick Integration

Step 1: Obtain your nekuda public key from the nekuda Portal. Step 2: Import the SDK

Show Import Statements

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

Step 3: Create the Payment Form Component

Show PaymentForm Component Code

function PaymentForm() {
const [processing, setProcessing] = useState(false);
const [succeeded, setSucceeded] = useState(false);
const [error, setError] = useState(null);

const handlePaymentSave = async (formData) => {
  console.log('Payment saved via coordinator:', formData);

  // Extract token ID from coordinator response
  const tokenId = formData.id || formData.cardTokenId;

  if (tokenId) {
    setProcessing(false);
    setSucceeded(true);
    setError(null);
  } catch (err) {
    setError(err.message || 'Payment submission failed');
    setSucceeded(false);
  }
};

return (
  <NekudaPaymentForm>
    {error && <div className="error" style={{ color: 'red', marginBottom: '10px' }}>{error}</div>}
    <button onClick={handleSubmit} disabled={processing || succeeded} style={{ marginTop: '10px' }}>
      {processing ? 'Processing...' : 'Save Payment Details'}
    </button>
    {succeeded && <div style={{ color: 'green', marginTop: '10px' }}>Payment details saved successfully!</div>}
  </NekudaPaymentForm>
);
}

Step 4: Wrap Your App with the Provider

Show App Provider Setup Code

// Wrap your app with the provider
function App() {
// Generate or retrieve your user's ID
const userId = getUserId(); // e.g., from your auth system

return (
  <NekudaWalletProvider
    publicKey="YOUR_NEKUDA_PUBLIC_KEY" // Publishable key from nekuda Portal
    userId={userId} // Your user's unique identifier
  >
    <PaymentForm />
  </NekudaWalletProvider>
);
}

That’s it! This setup will render a complete payment form.

SDK Components & Usage

`<NekudaWalletProvider>`

Initializes the SDK and must wrap any components that use nekuda.

Show Props

publicKey

string

required

Your nekuda publishable key from the nekuda Portal (e.g., pk_test_...). This is safe to use in frontend code.

userId

string

required

User identifier from your system. You generate and manage these IDs to link saved cards with your users. Examples: database user IDs, customer IDs, or any unique identifier.

onSuccess

function

Callback when payment information is successfully collected. Receives collection result with id, status, and message.

onError

function

Callback for handling errors during payment collection. Receives error details.

onValidationError

function

Callback for handling field validation errors. Receives field-specific error details.

elementsConfig

object

Configure styles for form elements. Maps element types to style states (base, focus, error). See Customization.

Example:

Show Provider Example Code

// Example with user ID management
const userId = getCurrentUserId(); // Your user ID logic

<NekudaWalletProvider
publicKey="YOUR_NEKUDA_PUBLIC_KEY"
userId={userId}
>
{/* Your components that use nekuda elements */}
</NekudaWalletProvider>

`<NekudaPaymentForm>`

A pre-built payment form component that securely collects all payment information.

Show Props

onSave

function

Callback when form data is successfully saved. Receives the collected form data.

style

object

Inline styles for the form container.

elementsConfig

object

Style configurations for form elements. Overrides provider-level elementsConfig.

className

string

CSS class name for custom styling.

Show PaymentForm Example Code

<NekudaPaymentForm
style={{ width: '500px' }}
onSave={(formData) => console.log('Form saved:', formData)}
>
{/* Optional: Add a custom submit button */}
<button type="submit">Submit Payment</button>
</NekudaPaymentForm>

`onSave` Callback Pattern

Accesses SDK functionality from within components wrapped by <NekudaWalletProvider>.

Next Steps

Card Management

Enable users to save and manage multiple payment methods

Customization

Style components with themes and design systems

Advanced Usage

Learn about prefilling data and complex workflows

Error Handling

Handle errors and edge cases gracefully

Show Hook Returns

elements

object

Object containing the submit() method to process payment collection.

userId

string

The current user ID from the provider context.

Show useNekudaWallet Example Code

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

const handleFormSubmit = async () => {
  if (!elements) return;

  try {
    const result = await elements.submit();
    console.log('Collection Success:', result);
    // result contains: { id, status, message, request_id }
  } catch (error) {
    console.error('Collection Error:', error);
  }
};

return (
  <div>
    <NekudaPaymentForm />
    <button onClick={handleFormSubmit}>
      Submit Payment
    </button>
    {succeeded && <div>Information details saved successfully!</div>}
  </NekudaPaymentForm>
);
}

`<NekudaCardManagement>`

A complete card management interface for users to view, add, and manage their saved payment methods.

Show Props

onCardSave

function

Callback when a new card is successfully saved. Receives the saved card details.

onCardDelete

function

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

onDefaultCardSet

function

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

open

boolean

Controls the visibility of the card management interface. Defaults to true.

onOpenChange

function

Callback to control modal open/close state when using as a modal.

style

object

Inline styles for the component container.

className

string

CSS class name for custom styling.

Show CardManagement Example Code

// Basic usage
<NekudaCardManagement
onCardSave={(card) => console.log('Card saved:', card)}
onCardDelete={(cardId) => console.log('Card deleted:', cardId)}
onDefaultCardSet={(cardId) => console.log('Default set:', cardId)}
/>

// As a modal
function PaymentSettings() {
const [isOpen, setIsOpen] = useState(false);

return (
  <>
    <button onClick={() => setIsOpen(true)}>
      Manage Payment Methods
    </button>

    <NekudaCardManagement
      open={isOpen}
      onOpenChange={setIsOpen}
      onCardSave={(card) => {
        console.log('Card saved:', card);
        setIsOpen(false);
      }}
    />
  </>
);
}

Understanding the Flow

User ID Management

You generate and manage user IDs in your system. These IDs link saved cards to your users.

Frontend Collection

The React SDK securely collects and tokenizes information in the browser.

Backend Processing

Your backend uses the secret API key (never exposed in frontend) to process information using the stored cards.

Next Steps

After integrating the payment collection:

Learn how to manage saved payment methods for returning customers
Explore customization options to match your brand
Review error handling best practices

Security and PCI Compliance

Secure Data Collection: Sensitive information (card number, CVC, expiry) is collected within secure iframes hosted by nekuda. This data never touches your servers directly.
Tokenization: Upon successful submission, the SDK returns a secure, single-use token representing the information details. This token can be safely passed to your backend.
No PCI Scope: By using the iframed elements, your PCI DSS compliance scope is reduced, as you don’t handle or store raw cardholder data.

Get Started

Frontend SDK

Backend SDK

Security

Testing

Overview

Key Features:

Installation

Quick Integration

SDK Components & Usage

`<NekudaWalletProvider>`

`<NekudaPaymentForm>`

`onSave` Callback Pattern

Next Steps

Card Management

Customization

Advanced Usage

Error Handling

`<NekudaCardManagement>`

Understanding the Flow

Next Steps

Security and PCI Compliance

Get Started

Frontend SDK

Backend SDK

Security

Testing

​Overview

​Key Features:

​Installation

​Quick Integration

​SDK Components & Usage

​<NekudaWalletProvider>

​<NekudaPaymentForm>

​onSave Callback Pattern

​Next Steps

Card Management

Customization

Advanced Usage

Error Handling

​<NekudaCardManagement>

​Understanding the Flow

​Next Steps

​Security and PCI Compliance

Overview

Key Features:

Installation

Quick Integration

SDK Components & Usage

`<NekudaWalletProvider>`

`<NekudaPaymentForm>`

`onSave` Callback Pattern

Next Steps

`<NekudaCardManagement>`

Understanding the Flow

Next Steps

Security and PCI Compliance