Get Started
System Overview
Understand how nekuda’s wallet works for AI agents and applications.
nekuda SDK provides a wallet designed specifically for AI agents and applications. It provides a secure way to collect, store, and reveal payment information when needed, enabling AI agents to complete transactions on behalf of users.
It also supports specific nuances of agentic payments required by card networks, such as recording user-specific authorization (mandate) and utilizing network tokens for payments.
The wallet has two main components: a frontend to create a beautiful wallet experience and securely collect payment credentials (removing PCI friction from the agent developer), and a backend to retrieve card details just-in-time and handle specific requirements of agentic payments, such as mandates.
As agentic payments evolve quickly, some underlying details may change, but we always stay aligned with the latest requirements.
Agent wallet examples
Main Workflows
The wallet is built around three main workflows:1. Collect Payment Information
The Frontend SDK renders a wallet within the agent GUI, enabling you to securely collect credit card and shipping information from users. It uses customizable iframes to keep you out of PCI scope while matching the wallet’s appearance to your design preferences. Users can store multiple cards in the wallet and update their information at any time.2. Capture Payment Mandate
Becuase users give permission to an agent to make purchasees on their behalf, it is important to record to user mandate for that action. A mandate can take many forms (e.g. click a “buy” button, voice, text etc.) and the Backend SDK supports capturing it and storing it for future use. Once you record the mandate in our system, you’ll receive ‘reveal token’ that can be used to reveal the payment credentials when needed.3. Retrieve Card
Using the reveal token and then retrieve the actual card details just-in-time for payment. This ensures card information is only accessed when explicitly authorized and needed. The card details can appear in two forms: either as a network token (a 16-digit number that looks and behaves like a credit card) when supported by the card network (for example Visa), or as a PAN when not. You can read about our security best practices to handle this stage properly.Architecture Overview
The nekuda system consists of two main components that work together:Frontend SDK
The Frontend SDK (@nekuda/react-nekuda-js) runs in the user’s browser and handles:
- Secure collection of credit card and shipping details
- User interface components for the wallet
- Client-side validation and error handling
Backend SDKs
The Backend SDKs (nekuda for Python and @nekuda/nekuda-js for TypeScript) run on your server and handle:
- Recording the user mandate
- Card details / network token retrieve
- Policy engine for security (coming soon)
Core Concepts
Users
Each user in the nekuda system is identified by a uniqueuser_id that you provide and manage. This identifier connects frontend payment data collection with backend information handling. The ‘user_id’ is needed whenever the backend wants to retrieve the payment credentials for payments.
Mandates
A mandate represents a user’s intent to make a purchase. It contains:- Product information
- Price and currency
- Merchant details
- Associated user context (such as prompts or other proof of delegated payment permission)
Reveal Tokens
Reveal tokens are short-lived, single-use tokens that authorize the revelation of card details. They are:- Generated for specific mandates
- Time-limited for security
- Required to access actual payment information
Credit Cards
Each user can store multiple credit cards in their nekuda wallet, identified by uniquecard_id values. This allows users to manage multiple payment methods:
- Multiple Cards: Users can store several credit cards under the same
user_id - Card Identification: Each card is assigned a unique
card_idfor reference - Default Card: Users can set one card as their default payment method
- Automatic Selection: When revealing card details, the default card is automatically retrieved unless a specific
card_idis requested - Card Management: Users can add, update, or remove cards through the frontend SDK
Network tokens
- Different card networks, like Visa and Mastercard, are developing agentic payment solutions that include network tokens. Network tokens have 16 digits like regular PANs and can be passed through GUI or human checkout interfaces. They look and feel like PANs but offer stronger security because they are scoped per transaction (hence the exposure of the network token is less risky than a PAN). They also come with a dynamic CVV (DTVV) generated by the card network for each transaction, and can be injected into guest checkouts.
Information Flow
1
Frontend Collection
User provides payment and shipping details through the nekuda frontend SDK, which securely stores the information associated with their
user_id.2
Mandate Creation
Your backend captures a mandate using the backend SDK, specifying the purchase details and user context.
3
Token Request
Using the mandate ID, your backend requests a reveal token that authorizes access to the user’s payment information.
4
Information Revelation
The reveal token is used to securely retrieve the actual card details, which can then be used with the payment.
Integration Points
Checkout Agents / APIs
A commerce agent can build its own stack to complete purchases or use a third-party checkout agent, which usually receives SKUs or an order intent and executes purchases across different merchants. nekuda can be easily integrated into these agents by delegating the retrieval functionality to them. You can pass theuser_id to them, and if they have access to your account, they can call the payment credentials just-in-time. Contact us for help with integration.