Documentation Index
Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
Use this file to discover all available pages before exploring further.
SDKs at a glance
TagadaPay ships five SDKs plus several CLI / MCP tools. Each one targets a specific job. Use this page to pick the right one in 30 seconds.
Rule of thumb: the further “down” you go in this list, the more control you get and the more code you write. Start at the top — if it covers your use case, stop there.
Decision flowchart
What are you building?
│
├─ Just a "Buy Now" button on a static site
│ → Web Integration (no SDK, just a snippet)
│
├─ A custom checkout for ONE store you own
│ ├─ I want it hosted on TagadaPay → Plugin SDK
│ └─ I want it on my own domain → Headless SDK
│
├─ A platform that charges cards for MANY merchants
│ → Partners (Node SDK + core-js) ◄── this is the new section
│
├─ A backend automation (CI / agent / batch job)
│ → Node SDK
│
├─ A native mobile app or embedded form
│ → core-js + REST (low-level)
│
└─ AI agents that edit my Studio templates
→ Studio MCP
The five SDKs
1. @tagadapay/core-js — Browser primitives
| |
|---|
| Layer | Browser, low-level |
| Use it for | Card / Apple Pay / Google Pay tokenization, 3DS challenges, wallet availability checks, Stripe Express |
| Don’t use it for | Anything stateful (cart, session, customer) — that’s the headless-sdk |
| Carries a session? | No |
| Best companion | @tagadapay/node-sdk (server) |
| Doc | Low-level payments · Partners |
tagadaToken. Use it whenever sensitive payment data needs to leave the browser without touching your server.
2. @tagadapay/headless-sdk — Custom checkouts
| |
|---|
| Layer | Browser, session-based orchestration |
| Use it for | Building a custom checkout on your own domain with React / Vue / vanilla JS |
| Don’t use it for | Server automation, batch jobs, cross-merchant platforms |
| Carries a session? | Yes — built around checkoutSession |
| Best companion | @tagadapay/node-sdk (for everything not session-related) |
| Doc | Headless SDK introduction |
useCheckout() hook, point it at a TagadaPay store. Cart, promotions, shipping, payment, upsells — all session-based. Internally uses core-js for tokenization.
| |
|---|
| Layer | Browser, React framework for in-platform plugins |
| Use it for | Checkout pages, landing pages, customer portals deployed on TagadaPay’s runtime (e.g. via the Plugin CLI) |
| Don’t use it for | Pages hosted on your own domain (use headless-sdk) |
| Carries a session? | Yes — reads window.__TGD_STEP_CONFIG__ injected by the runtime |
| Best companion | @tagadapay/plugin-cli (deployment) |
| Doc | Plugin SDK introduction |
core-js for tokenization.
4. @tagadapay/node-sdk — Server-side, the big one
| |
|---|
| Layer | Server, Stripe-style resource client |
| Use it for | All server operations: payments, refunds, customers, stores, products, subscriptions, checkout sessions, webhooks, and partner provisioning (partners.*) |
| Don’t use it for | Anything that needs to run in a browser |
| Carries a session? | No (you choose the storeId per call) |
| Best companion | Any of the browser SDKs |
| Doc | Node SDK quick start · Partners |
stripe-node of TagadaPay. Resource-keyed (tagada.payments.process(), tagada.customers.create(), etc.). The tagada.partners.* namespace covers partner provisioning end-to-end (sub-merchants, API keys, requirements, documents).
When two SDKs are involved
Most real integrations need exactly two SDKs working together:
| Scenario | Browser | Server |
|---|
| Custom checkout on your domain | headless-sdk | node-sdk |
| Plugin deployed on TagadaPay | plugin-sdk | (none — runtime handles the server side) |
| Partner platform (Suby-style) | core-js | node-sdk (with partners.*) |
| Mobile app / native checkout | core-js | node-sdk |
| Backend automation only | (none) | node-sdk |
Side-by-side comparison
| core-js | headless-sdk | plugin-sdk | node-sdk |
|---|
| Runs in | Browser | Browser | Browser | Server (Node 18+) |
| Card tokenization | ✅ Direct | ✅ via core-js | ✅ via core-js | ❌ |
| Apple/Google Pay tokenization | ✅ | ✅ via core-js | ✅ via core-js | ❌ |
| 3DS challenges | ✅ | ✅ | ✅ | ❌ |
| Checkout sessions | ❌ | ✅ Built-in | ✅ via runtime | ✅ Create/manage |
| Cart / promotions / shipping | ❌ | ✅ | ✅ | ✅ Server-side |
| Stores / products / customers | ❌ | Read-only | Read-only | ✅ Full CRUD |
| Payments S2S | ❌ | ❌ | ❌ | ✅ |
| Subscriptions | ❌ | ❌ | ❌ | ✅ |
| Partner provisioning | ❌ | ❌ | ❌ | ✅ (partners.*) |
| Webhooks | ❌ | ❌ | ❌ | ✅ Verify + manage |
These aren’t SDKs — they’re separate tools:
| Tool | Purpose | Doc |
|---|
@tagadapay/plugin-cli (tgd) | Package and deploy plugins from the command line | Plugin CLI |
@tagadapay/studio-mcp | Let AI agents edit Tagada Studio templates | Studio MCP |
@tagadapay/crm-mcp | Let AI agents read your account configuration | CRM MCP |
Common pitfalls
Don’t mix headless-sdk and plugin-sdk in the same app. They have different runtime assumptions. If you’re hosting on your own domain, pick headless-sdk. If you’re deploying to TagadaPay, pick plugin-sdk. Never both.
Don’t use the partner key in your charging path. Mint a sub-key per merchant and use the sub-key for payments.process. The partner key has too much power for hot-path credentials. See API keys. Don’t call core-js from your server. It’s a browser library — the bundled BasisTheory client expects browser APIs. Server-side, all tokenization is done implicitly via the public API endpoints exposed by node-sdk.
Migration map
| Coming from… | Go to… |
|---|
@tagadapay/plugin-sdk/v2/standalone (Apple/Google Pay primitives) | @tagadapay/core-js (same primitives, same signatures) |
| Direct REST API calls | One of the SDKs above — pick from the decision flowchart |
