Headless SDK

Use TagadaPay as a headless checkout and CRM backend from any website

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

---

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.customer	Profile, orders, subscriptions

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

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);

// 2. See what payment methods are available
const setup = await tagada.payment.getPaymentSetup(session.id);
console.log(setup); // { card: { enabled: true }, apple_pay: { ... }, ... }

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

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

// 4. Handle result
if (result.payment.status === 'succeeded') {
  // Pixel events (Purchase, Conversion) are fired automatically
  // by TagadaPay when configured in the dashboard.
  console.log('Paid!', result.payment.id);
}

React

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

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

function CheckoutPage() {
  const { session, isLoading } = useCheckout(checkoutToken);
  const { pay, isProcessing, tokenizeCard, loadPaymentSetup } = usePayment();

  useEffect(() => {
    if (session?.id) loadPaymentSetup(session.id);
  }, [session?.id]);

  const handlePay = async () => {
    const { tagadaToken } = await tokenizeCard({
      cardNumber: '4242424242424242',
      expiryDate: '12/28',
      cvc: '123',
    });
    const result = await pay({
      checkoutSessionId: session.id,
      tagadaToken,
    });
    if (result.payment.status === 'succeeded') {
      console.log('Paid!', result.payment.id);
    }
  };

  if (isLoading) return <p>Loading...</p>;

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

CDN / Script Tag

<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    — pay(), APMs, 3DS, express checkout    │
│    │   └── 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

1. Zero dependencies — core uses native fetch. No axios, no lodash.
2. AI-first — single import, minimal config, self-contained methods. LLMs generate working code on the first try.
3. Full payment coverage — same APMs, express checkout, 3DS, and PSP routing as the Plugin SDK.
4. Tree-shakeable — unused modules are eliminated by bundlers.
5. 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

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