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

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

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

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 · Partners

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
`@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

Overview

Web Integration

Tracking & Attribution

Node SDK

Funnels

Shopify

SaaS Billing

Headless SDK

Plugin SDK

Plugin CLI

Studio MCP (AI Agents)

CRM MCP (AI Agents)

Hosting & A/B Testing

Internal

SDKs at a glance

SDKs at a glance

Decision flowchart

The five SDKs

1. `@tagadapay/core-js` — Browser primitives

2. `@tagadapay/headless-sdk` — Custom checkouts

3. `@tagadapay/plugin-sdk` — Plugins on the TagadaPay platform

4. `@tagadapay/node-sdk` — Server-side, the big one

When two SDKs are involved

Side-by-side comparison

What about the CLI / MCP tools?

Common pitfalls

Migration map

​SDKs at a glance

​Decision flowchart

​The five SDKs

​1. @tagadapay/core-js — Browser primitives

​2. @tagadapay/headless-sdk — Custom checkouts

​3. @tagadapay/plugin-sdk — Plugins on the TagadaPay platform

​4. @tagadapay/node-sdk — Server-side, the big one

​When two SDKs are involved

​Side-by-side comparison

​What about the CLI / MCP tools?

​Common pitfalls

​Migration map

SDKs at a glance

Decision flowchart

The five SDKs

1. `@tagadapay/core-js` — Browser primitives

2. `@tagadapay/headless-sdk` — Custom checkouts

3. `@tagadapay/plugin-sdk` — Plugins on the TagadaPay platform

4. `@tagadapay/node-sdk` — Server-side, the big one

When two SDKs are involved

Side-by-side comparison

What about the CLI / MCP tools?

Common pitfalls

Migration map