nekuda 0.2.9

Python SDK for Nekuda payment processing

Quickstart

Welcome to the rapid-fire tour of the Nekuda Python SDK. In less than five minutes you will:

1. install the package,
2. authenticate with your API key, and
3. run your first card-reveal workflow with type-safe responses.

TL;DR – copy the snippets below into a file called hello.py, export your API key, run it, done.

💡 Don't forget! This Python SDK handles the backend payment processing. You'll also need to integrate our wallet collection SDK on your frontend to securely collect credit card details from users.

---

1. Installation

We recommend using UV (fast Rust-based pip replacement), but plain pip works just as well:

uv pip install nekuda
#-or-
pip install nekuda

The SDK ships as a single, pure-python wheel with minimal dependencies – install is ~1 s.

---

2. Authenticate

Grab your secret key from the Nekuda dashboard and export it as an environment variable:

export NEKUDA_API_KEY="sk_live_…"  # required
# Optional – point the SDK to staging / localmock
export NEKUDA_BASE_URL="https://api.nekuda.ai"

That's all the configuration you need for the quickstart.

---

3. Hello World

from nekuda import NekudaClient

client = NekudaClient.from_env()
print("🚀 Authenticated! Your account ID is:", client.api_key[:8] + "…")

python hello.py

If everything is set-up correctly you should see:

🚀 Authenticated! Your account ID is: sk_live_12…

---

4. End-to-end flow with Type Safety 🎯

The snippet below walks through the full payment flow with type-safe responses:

from nekuda import MandateData, NekudaClient, NekudaError

client = NekudaClient.from_env()
user = client.user("test_user_123")

try:
    # 1) Describe what the user is about to purchase
    mandate = MandateData(
        product="Premium Subscription",
        price=49.99,
        currency="USD",
        merchant="Nekuda Corp"
    )

    # Create mandate - returns MandateCreateResponse
    mandate_response = user.create_mandate(mandate)
    print(f"✅ Created mandate: {mandate_response.mandate_id}")

    # 2) Request a reveal token - returns CardRevealTokenResponse
    reveal_response = user.request_card_reveal_token(mandate_response.mandate_id)
    print(f"🔑 Token: {reveal_response.reveal_token}")

    # IDE knows these fields exist! No more KeyErrors!
    if reveal_response.expires_at:
        print(f"⏰ Expires at: {reveal_response.expires_at}")

    # 3) Exchange token for card details - returns CardDetailsResponse
    card = user.reveal_card_details(reveal_response.reveal_token)
    print(f"💳 **** **** **** {card.card_number[-4:]}")
    print(f"📅 Expiry: {card.card_expiry_date}")  # Always MM/YY format
    print(f"👤 Name: {card.cardholder_name}")

except NekudaError as e:
    print(f"❌ Error: {e}")

Run it and you'll see the card details with full type safety and IDE autocomplete support!

🔗 Complete Integration: Remember that in a real application, steps 1-2 happen on your backend (using this Python SDK), while the actual card collection happens on your frontend using our React wallet SDK.

---

5. Why Type Safety Matters 🛡️

With our new typed response models:

• No more KeyError - IDE knows exactly what fields are available
• Autocomplete everywhere - Your editor suggests available fields
• Validation built-in - Card numbers and expiry dates are validated
• Better error messages - Know exactly what went wrong

# Before (raw dicts) 😟
result = client.request_card_reveal_token(...)
token = result["reveal_token"]  # Hope the key exists!

# After (typed models) 😊
result = client.request_card_reveal_token(...)
token = result.reveal_token  # IDE autocomplete! Type checked!

---

What's next?

• 📚 Full Documentation – comprehensive guides, API reference, and integration examples
• Core Concepts – understand NekudaClient, UserContext, and response models
• Usage Guide – deep dive into the payment flow
• Configuration – production-ready settings
• Error Handling – build resilient applications

Happy hacking! 🎉