# 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](https://docs.nekuda.ai/essentials/react-nekuda-js) on your frontend to securely collect credit card details from users.
---
## 1. Installation
We recommend using **[UV](https://github.com/astral-sh/uv)** (fast Rust-based `pip` replacement), but plain `pip` works just as well:
```bash
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:
```bash
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
```python title="hello.py"
from nekuda import NekudaClient
client = NekudaClient.from_env()
print("🚀 Authenticated! Your account ID is:", client.api_key[:8] + "…")
```
```bash
python hello.py
```
If everything is set-up correctly you should see:
```text
🚀 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:
```python title="quick_demo.py"
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](https://docs.nekuda.ai/essentials/react-nekuda-js).
---
## 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
```python
# 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](https://docs.nekuda.ai)** – comprehensive guides, API reference, and integration examples
- **[Core Concepts](Core_Concepts.md)** – understand `NekudaClient`, `UserContext`, and response models
- **[Usage Guide](Usage_Guide.md)** – deep dive into the payment flow
- **[Configuration](Configuration.md)** – production-ready settings
- **[Error Handling](Errors.md)** – build resilient applications
Happy hacking! 🎉
Raw data
{
"_id": null,
"home_page": null,
"name": "nekuda",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai-agents, credit-card, fintech, nekuda, payments, sdk",
"author": null,
"author_email": "Nekuda AI <support@nekuda.ai>",
"download_url": null,
"platform": null,
"description": "# Quickstart\n\nWelcome to the rapid-fire tour of the Nekuda **Python SDK**. In less than five minutes you will:\n\n1. install the package,\n2. authenticate with your **API key**, and\n3. run your first _card-reveal_ workflow with **type-safe responses**.\n\n> **TL;DR** \u2013 copy the snippets below into a file called `hello.py`, export your API key, run it, done.\n\n> **\ud83d\udca1 Don't forget!** This Python SDK handles the backend payment processing. You'll also need to integrate our [wallet collection SDK](https://docs.nekuda.ai/essentials/react-nekuda-js) on your frontend to securely collect credit card details from users.\n\n---\n\n## 1. Installation\n\nWe recommend using **[UV](https://github.com/astral-sh/uv)** (fast Rust-based `pip` replacement), but plain `pip` works just as well:\n\n```bash\nuv pip install nekuda\n#-or-\npip install nekuda\n```\n\n> The SDK ships as a single, pure-python wheel with minimal dependencies \u2013 install is ~1 s.\n\n---\n\n## 2. Authenticate\n\nGrab your secret key from the Nekuda dashboard and export it as an environment variable:\n\n```bash\nexport NEKUDA_API_KEY=\"sk_live_\u2026\" # required\n# Optional \u2013 point the SDK to staging / localmock\nexport NEKUDA_BASE_URL=\"https://api.nekuda.ai\"\n```\n\nThat's _all_ the configuration you need for the quickstart.\n\n---\n\n## 3. Hello World\n\n```python title=\"hello.py\"\nfrom nekuda import NekudaClient\n\nclient = NekudaClient.from_env()\nprint(\"\ud83d\ude80 Authenticated! Your account ID is:\", client.api_key[:8] + \"\u2026\")\n```\n\n```bash\npython hello.py\n```\n\nIf everything is set-up correctly you should see:\n\n```text\n\ud83d\ude80 Authenticated! Your account ID is: sk_live_12\u2026\n```\n\n---\n\n## 4. End-to-end flow with Type Safety \ud83c\udfaf\n\nThe snippet below walks through the **full payment flow** with type-safe responses:\n\n```python title=\"quick_demo.py\"\nfrom nekuda import MandateData, NekudaClient, NekudaError\n\nclient = NekudaClient.from_env()\nuser = client.user(\"test_user_123\")\n\ntry:\n # 1) Describe what the user is about to purchase\n mandate = MandateData(\n product=\"Premium Subscription\",\n price=49.99,\n currency=\"USD\",\n merchant=\"Nekuda Corp\"\n )\n\n # Create mandate - returns MandateCreateResponse\n mandate_response = user.create_mandate(mandate)\n print(f\"\u2705 Created mandate: {mandate_response.mandate_id}\")\n\n # 2) Request a reveal token - returns CardRevealTokenResponse\n reveal_response = user.request_card_reveal_token(mandate_response.mandate_id)\n print(f\"\ud83d\udd11 Token: {reveal_response.reveal_token}\")\n\n # IDE knows these fields exist! No more KeyErrors!\n if reveal_response.expires_at:\n print(f\"\u23f0 Expires at: {reveal_response.expires_at}\")\n\n # 3) Exchange token for card details - returns CardDetailsResponse\n card = user.reveal_card_details(reveal_response.reveal_token)\n print(f\"\ud83d\udcb3 **** **** **** {card.card_number[-4:]}\")\n print(f\"\ud83d\udcc5 Expiry: {card.card_expiry_date}\") # Always MM/YY format\n print(f\"\ud83d\udc64 Name: {card.cardholder_name}\")\n\nexcept NekudaError as e:\n print(f\"\u274c Error: {e}\")\n```\n\nRun it and you'll see the card details with full type safety and IDE autocomplete support!\n\n> **\ud83d\udd17 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](https://docs.nekuda.ai/essentials/react-nekuda-js).\n\n---\n\n## 5. Why Type Safety Matters \ud83d\udee1\ufe0f\n\nWith our new typed response models:\n\n- **No more `KeyError`** - IDE knows exactly what fields are available\n- **Autocomplete everywhere** - Your editor suggests available fields\n- **Validation built-in** - Card numbers and expiry dates are validated\n- **Better error messages** - Know exactly what went wrong\n\n```python\n# Before (raw dicts) \ud83d\ude1f\nresult = client.request_card_reveal_token(...)\ntoken = result[\"reveal_token\"] # Hope the key exists!\n\n# After (typed models) \ud83d\ude0a\nresult = client.request_card_reveal_token(...)\ntoken = result.reveal_token # IDE autocomplete! Type checked!\n```\n\n---\n\n## What's next?\n\n- **[\ud83d\udcda Full Documentation](https://docs.nekuda.ai)** \u2013 comprehensive guides, API reference, and integration examples\n- **[Core Concepts](Core_Concepts.md)** \u2013 understand `NekudaClient`, `UserContext`, and response models\n- **[Usage Guide](Usage_Guide.md)** \u2013 deep dive into the payment flow\n- **[Configuration](Configuration.md)** \u2013 production-ready settings\n- **[Error Handling](Errors.md)** \u2013 build resilient applications\n\nHappy hacking! \ud83c\udf89\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for Nekuda payment processing",
"version": "0.2.8",
"project_urls": {
"Documentation": "https://docs.nekuda.ai",
"Homepage": "https://nekuda.ai"
},
"split_keywords": [
"ai-agents",
" credit-card",
" fintech",
" nekuda",
" payments",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e72e49ac50afc61edbf861287c93431887a217f2cf3f083cebc297c1eb5421b3",
"md5": "83e2ebe128d64c95ca7ac054ef479298",
"sha256": "b8ec1a1cadf45d85e1ebbb996cf88f634bdf5232b0ebc3660b8d7f880efe971c"
},
"downloads": -1,
"filename": "nekuda-0.2.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83e2ebe128d64c95ca7ac054ef479298",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 23715,
"upload_time": "2025-07-16T21:27:10",
"upload_time_iso_8601": "2025-07-16T21:27:10.220984Z",
"url": "https://files.pythonhosted.org/packages/e7/2e/49ac50afc61edbf861287c93431887a217f2cf3f083cebc297c1eb5421b3/nekuda-0.2.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 21:27:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "nekuda"
}
JSON