> ## 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
> Every TagadaPay SDK explained in one page: who it’s for, what it does, and what to use instead if it’s not the right fit.
# 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](/developer-tools/payments/headless-payments) · [Partners](/developer-tools/partners/introduction) |
**Mental model**: a thin, framework-agnostic wrapper around BasisTheory + Apple Pay + Google Pay APIs that returns a `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](/developer-tools/headless-sdk/introduction) |
**Mental model**: take your existing storefront, wire a `useCheckout()` hook, point it at a TagadaPay store. Cart, promotions, shipping, payment, upsells — all session-based. Internally uses `core-js` for tokenization.
***
### 3. `@tagadapay/plugin-sdk` — Plugins on the TagadaPay platform
| | |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| **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](/developer-tools/sdk/introduction) |
**Mental model**: write a React app that runs INSIDE TagadaPay’s funnel runtime. The runtime hands you the session, the step config, the customer state — you only write the UI. Internally uses `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](/developer-tools/node-sdk/quick-start) · [Partners](/developer-tools/partners/introduction) |
**Mental model**: think of it as the `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 |
***
## What about the CLI / MCP tools?
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](/developer-tools/cli/introduction) |
| `@tagadapay/studio-mcp` | Let AI agents edit Tagada Studio templates | [Studio MCP](/developer-tools/studio-mcp/introduction) |
| `@tagadapay/crm-mcp` | Let AI agents read your account configuration | [CRM MCP](/developer-tools/crm-mcp/introduction) |
***
## 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](/developer-tools/partners/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 |