Skip to main content

​
TagadaPay Plugin SDK v2

Build custom checkout experiences, funnels, and interactive e-commerce components with the TagadaPay Plugin SDK. Choose between React for rich UIs or vanilla JavaScript for lightweight implementations.

React + TypeScript

Modern React hooks with full TypeScript support

Vanilla JavaScript

Framework-agnostic standalone SDK

Funnel System

Pass data seamlessly between funnel steps

Auto-redirect

Automatic navigation and URL routing

​
Quick Start

npm install @tagadapay/plugin-sdk

import { TagadaProvider, useFunnel } from '@tagadapay/plugin-sdk/v2';

export default function App() {
  return (
    <TagadaProvider>
      <CheckoutPage />
    </TagadaProvider>
  );
}

function CheckoutPage() {
  const funnel = useFunnel();

  const handlePayment = async () => {
    await funnel.next({
      type: 'payment_success',
      data: {
        resources: {
          order: { id: 'ord_123', amount: 99.99 }
        }
      }
    });
  };

  return <button onClick={handlePayment}>Pay Now</button>;
}

​
Core Concepts

​
1. Provider-Based Architecture (React)

The SDK uses React Context to provide global state and functionality: 
import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';

export default function App() {
  return (
    <TagadaProvider>
      {/* Your plugin components */}
    </TagadaProvider>
  );
}
What TagadaProvider does:
  • Initializes authentication and session
  • Auto-initializes funnel if enabled
  • Provides hooks like useFunnel(), useCheckout(), etc.
  • Handles automatic redirects
  • Manages debug mode based on environment

​
2. Funnel System

Build multi-step funnels where data flows automatically between steps: 
// Step 1: Checkout
await funnel.next({
  type: 'payment_success',
  data: {
    resources: {
      order: { id: 'ord_123', amount: 100 },
      customer: { id: 'cus_456', email: '[email protected]' }
    }
  }
});

// Step 2: Thank You Page - order data is automatically available
const order = funnel.context?.resources?.order;
Learn more: Funnel Resources Guide

​
3. Automatic Features

The SDK handles common tasks automatically: Auto-initialization
  • Funnel session initializes automatically when TagadaProvider mounts
  • No manual initializeSession() calls needed
  • Controlled via autoInitializeFunnel prop (default: true)
Auto-redirect
  • Navigating with funnel.next() automatically redirects to the next step URL
  • No need for custom onNavigate handlers
  • Browser is redirected immediately after successful navigation
Debug Mode
  • Automatically enabled in local development
  • Loads local config from config/resources.static.json
  • Disabled in production automatically
// All of this happens automatically:
<TagadaProvider>
  {/* ✅ Funnel initializes
       ✅ Session created
       ✅ Debug mode enabled (if local)
       ✅ Redirects handled */}
  <YourPlugin />
</TagadaProvider>

​
4. Plugin Manifest

Define your plugin’s pages, features, and requirements: 
{
  "name": "My Checkout",
  "pluginId": "my-checkout",
  "version": "1.0.0",
  "mode": "direct-mode",
  "category": "checkout",
  "pages": [
    {
      "path": "/checkout",
      "features": [
        {
          "type": "checkout",
          "requirements": [
            {
              "resource": "checkoutSession",
              "from": [{ "name": "checkoutToken", "type": "query" }]
            }
          ]
        }
      ],
      "remappable": true
    },
    {
      "path": "/thankyou/:orderId",
      "features": [
        {
          "type": "thankyou",
          "requirements": [
            {
              "resource": "order",
              "from": [{ "name": "id", "type": "path" }]
            }
          ]
        }
      ],
      "remappable": true
    }
  ]
}
Learn more: Manifest Documentation

​
Available Hooks (React)

​
Funnel Navigation

HookDescription
useFunnel()Navigate between steps and access session context

​
Data Fetching

HookDescription
useCheckout()Fetch and manage checkout session
useProducts()Fetch products with caching
useOffer()Fetch offers for upsells
useStoreConfig()Fetch store settings
useCustomer()Fetch customer data

​
Utilities

HookDescription
useCurrency()Format money with formatMoney()
useTranslation()Multi-language translation helper
usePluginConfig()Access plugin configuration

​
Standalone SDK (Vanilla JS)

For non-React applications, use the standalone SDK: 
import { createTagadaClient } from '@tagadapay/plugin-sdk/v2/standalone';

const client = createTagadaClient({
  features: { funnel: true }
});

// Subscribe to state changes
client.subscribe((state) => {
  console.log('SDK state:', state);
});

// Use funnel features
await client.funnel.navigate({ type: 'payment_success' });

​
Environment Detection

The SDK automatically detects your environment:
EnvironmentWhenBehavior
locallocalhost, *.localhost, ngrokDebug mode ON, local config loaded
developmentdev., staging.Debug mode ON
productionapp.*, other domainsDebug mode OFF
Override with the debugMode prop: 
<TagadaProvider debugMode={false}>
  {/* Force debug mode off */}
</TagadaProvider>

​
Configuration Presets

Define multiple configuration variants with metadata: 
{
  "meta": {
    "id": "premium",
    "name": "Premium Theme",
    "description": "High-end checkout design"
  },
  "branding": {
    "primaryColor": "#000000",
    "companyName": "Premium Store"
  }
}
The meta.name is displayed in the CRM marketplace when merchants select presets.

​
Next Steps

Quick Start

Build your first plugin in 15 minutes

Initialize Checkout

Create checkout sessions programmatically

Tutorial

Step-by-step plugin development

API Reference

Complete API documentation

Funnel Resources

Learn how to pass data between steps

Examples

See real plugin examples

Best Practices

Production-ready tips