Headless SDK

Build your own store with any framework (React, Vue, Svelte, plain HTML) or AI tools (Lovable, Claude, v0) and use TagadaPay as the headless backend for checkout, payments, pixel tracking, and CRM.

When to use this SDK:

You’re building a custom store on your own hosting (Vercel, Netlify, etc.)
You want full control over the UI while TagadaPay handles payments, PSP routing, pixel tracking, and subscriptions
An AI tool is generating your store code and needs a simple, self-documenting API

When NOT to use this SDK:

You want to deploy pages on TagadaPay — use the Plugin SDK instead
You only need a checkout link — use Web Integration
You need server-side automation — use the Node SDK
You’re building a payment platform that charges for many merchants (Suby-style PSPs, marketplaces) — use the Partners section instead. Partner S2S deliberately avoids checkout sessions, which this SDK is built around.

Not sure? Compare all five SDKs side-by-side on SDKs at a glance.

How It Works

Your Store (Vercel, Netlify, etc.)
├── Frontend (any framework)
│   ├── @tagadapay/headless-sdk    ← checkout, pixel tracking, offers, CRM
│   └── @tagadapay/core-js         ← card tokenization, 3DS (optional)
└── Backend (API routes)
    └── @tagadapay/node-sdk         ← server automation, webhooks

The headless SDK talks to TagadaPay’s REST API from the browser. It’s a single import that gives you these modules:

Module	What it does
`tagada.checkout`	Load sessions, update cart, apply promos, handle shipping
`tagada.payment`	Discover APMs, tokenize cards, process payments, handle 3DS
`tagada.offers`	Load upsells/downsells, accept/decline, order bumps
`tagada.catalog`	Browse products, variants, and prices
`tagada.customer`	Profile, orders, subscriptions
`tagada.funnel`	Send shoppers into a TagadaPay funnel from your own cart

Pixel tracking (Meta, TikTok, Snap, GTM, GA4) is configured in the TagadaPay dashboard and automatically injected into your checkout sessions. See the Pixels page for details.

Install

npm install @tagadapay/headless-sdk

# Optional: for client-side card tokenization
npm install @tagadapay/core-js

Quick Start

Vanilla JavaScript
React
CDN / Script Tag

import { createHeadlessClient } from '@tagadapay/headless-sdk';

const tagada = createHeadlessClient({
  storeId: 'store_abc123',
  environment: 'production',
});

// 1. Load checkout session (token from URL)
const session = await tagada.checkout.loadSession(checkoutToken, sessionToken);

// 2. Set customer info + address
await tagada.checkout.updateCustomer(session.id, {
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
});
await tagada.checkout.updateAddress(session.id, {
  shippingAddress: {
    line1: '123 Main St',
    city: 'San Francisco',
    postalCode: '94102',
    country: 'US',
  },
});

// 3. Tokenize card + pay (3DS handled automatically)
const { tagadaToken } = await tagada.payment.tokenizeCard({
  cardNumber: '4242424242424242',
  expiryDate: '12/28',
  cvc: '123',
});

const result = await tagada.payment.processPayment({
  checkoutSessionId: session.id,
  tagadaToken,
});

// 4. Handle result
if (result.status === 'succeeded') {
  console.log('Paid!', result.order);
} else if (result.status === 'requires_redirect') {
  window.location.href = result.redirectUrl;
} else if (result.status === 'failed') {
  console.error(result.error);
}

import {
  TagadaHeadlessProvider,
  useCheckout,
  usePayment,
} from '@tagadapay/headless-sdk/react';

function App() {
  return (
    <TagadaHeadlessProvider storeId="store_abc123" environment="production">
      <CheckoutPage />
    </TagadaHeadlessProvider>
  );
}

function CheckoutPage() {
  const { session, updateCustomer, updateAddress } = useCheckout(checkoutToken, sessionToken);
  const { processPayment, isProcessing, tokenizeCard } = usePayment({
    onPaymentSuccess: (result) => router.push('/thank-you'),
    onPaymentFailed: (result) => alert(result.error),
  });

  const handlePay = async () => {
    await updateCustomer({ email, firstName, lastName });
    await updateAddress({
      shippingAddress: { line1, city, postalCode, country },
    });

    const { tagadaToken } = await tokenizeCard({ cardNumber, expiryDate, cvc });
    await processPayment({ checkoutSessionId: session.id, tagadaToken });
    // 3DS redirects + polling handled automatically
    // onPaymentSuccess / onPaymentFailed callbacks fire when done
  };

  return (
    <button onClick={handlePay} disabled={isProcessing}>
      {isProcessing ? 'Processing...' : 'Pay Now'}
    </button>
  );
}

<script src="https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk/dist/tagada-headless.min.js"></script>
<script>
  const tagada = TagadaHeadless.create({
    storeId: 'store_abc123',
    environment: 'production',
  });

  // Use tagada.checkout, tagada.payment, etc.
</script>

SDK Layers — Which Package Does What?

TagadaPay has three npm packages. Most developers only need the Headless SDK:

Package	Runs in	Purpose
`@tagadapay/headless-sdk`	Browser	Checkout sessions, payments (tokenize + charge + 3DS), offers, CRM, catalog. This is the main package.
`@tagadapay/core-js`	Browser	Low-level card tokenization, 3DS modal, Apple/Google Pay. Optional peer dep of headless-sdk — install it if you use `tagada.payment.tokenizeCard()`.
`@tagadapay/node-sdk`	Server (Node.js)	Server automation: create stores, products, payment flows, webhooks, deploy to CDN, manage subscriptions.

┌───────────────────────────────────────────────────────────┐
│  Your Frontend (React, Vue, Svelte, HTML)                 │
│                                                           │
│  @tagadapay/headless-sdk                                  │
│    ├── checkout   — sessions, cart, promos, shipping      │
│    ├── payment    — processPayment(), 3DS, APMs, express  │
│    │   └── uses @tagadapay/core-js internally             │
│    ├── offers     — upsells, downsells, order bumps       │
│    ├── customer   — profile, orders, subscriptions        │
│    └── catalog    — products, variants, prices            │
│                                                           │
│  @tagadapay/core-js  (optional)                           │
│    └── tokenizeCard(), useThreeds(), Apple/Google Pay     │
└───────────────────────────────────────────────────────────┘
                        │ HTTPS
                        ▼
┌───────────────────────────────────────────────────────────┐
│  Your Backend (optional)                                  │
│  @tagadapay/node-sdk — stores, webhooks, deploy, etc.    │
└───────────────────────────────────────────────────────────┘

When do you need @tagadapay/core-js separately? Only if you’re building a low-level payment integration (mobile apps, embedded forms, MIT charges) without the Headless SDK’s session management. If you use @tagadapay/headless-sdk, just npm install @tagadapay/core-js as a peer dep — the Headless SDK calls it internally.

Design Principles

Zero dependencies — core uses native fetch. No axios, no lodash.
AI-first — single import, minimal config, self-contained methods. LLMs generate working code on the first try.
Full payment coverage — same APMs, express checkout, 3DS, and PSP routing as the Plugin SDK.
Automatic 3DS — processPayment() handles redirects, iframe challenges, and polling out of the box.
Tree-shakeable — unused modules are eliminated by bundlers.
TypeScript-first — full type coverage, JSDoc on every method.

Next Steps

Build a Store with AI

Use Claude or Lovable to generate a storefront — TagadaPay handles the rest

Payment Setup

Discover APMs, express checkout, and payment flows

Checkout Flow

Sessions, cart, promo codes, and shipping

Funnel Navigation

Send shoppers into a TagadaPay funnel from your own cart

Emails

Transactional emails — order confirmations, subscription receipts, cart recovery

Pixels

Client-side pixel tracking for Meta, TikTok, GA4, GTM, and more

Upsells & Offers

Post-purchase offers and order bumps

Catalog

Browse products, variants, and prices

Customer

Profiles, order history, and subscriptions

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

Headless SDK

Headless SDK

How It Works

Install

Quick Start

SDK Layers — Which Package Does What?

Design Principles

Next Steps

Build a Store with AI

Payment Setup

Checkout Flow

Funnel Navigation

Emails

Pixels

Upsells & Offers

Catalog

Customer

​Headless SDK

​How It Works

​Install

​Quick Start

​SDK Layers — Which Package Does What?

​Design Principles

​Next Steps

Build a Store with AI

Payment Setup

Checkout Flow

Funnel Navigation

Emails

Pixels

Upsells & Offers

Catalog

Customer

Headless SDK

How It Works

Install

Quick Start

SDK Layers — Which Package Does What?

Design Principles

Next Steps