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
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.
Your nekuda publishable key from the nekuda Portal (e.g., pk_test_...
). This is safe to use in frontend code.
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.
Callback when payment information is successfully collected. Receives collection result with id
, status
, and message
.
Callback for handling errors during payment collection. Receives error details.
Callback for handling field validation errors. Receives field-specific error details.
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 >
A pre-built payment form component that securely collects all payment information.
Callback when form data is successfully saved. Receives the collected form data.
Inline styles for the form container.
Style configurations for form elements. Overrides provider-level elementsConfig
.
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
Object containing the submit()
method to process payment collection.
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.
Callback when a new card is successfully saved. Receives the saved card details.
Callback when a card is deleted. Receives the deleted card ID.
Callback when a default card is set. Receives the card ID.
Controls the visibility of the card management interface. Defaults to true
.
Callback to control modal open/close state when using as a modal.
Inline styles for the component container.
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:
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.