Quick Start: Your First Plugin

Build a complete checkout plugin from scratch in 15 minutes. Choose between React for rich UIs or vanilla JavaScript for lightweight implementations.

What You’ll Build

A simple checkout page that:

Initializes automatically with funnel session
Displays product information
Processes payment
Auto-redirects to thank you page
Passes order data between steps

Prerequisites

Node.js 18+

node --version
# Should be v18 or higher

Package Manager

# npm (comes with Node.js)
npm --version

# OR pnpm (recommended for monorepos)
npm install -g pnpm

TagadaPay Account

Choose Your Framework

React (Recommended)
Vanilla JavaScript

Perfect for building rich, interactive checkout experiences with modern UI components.

Step 1: Create Project

# Create new Vite + React project
npm create vite@latest my-checkout -- --template react-ts
cd my-checkout

# Install TagadaPay SDK
npm install @tagadapay/plugin-sdk

# Install dependencies
npm install

Step 2: Create Plugin Manifest

Create plugin.manifest.json in your project root:

{
  "name": "My Checkout",
  "pluginId": "my-checkout",
  "version": "1.0.0",
  "description": "A simple checkout plugin",
  "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
    }
  ]
}

Step 3: Wrap App with Provider

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { TagadaProvider } from '@tagadapay/plugin-sdk/v2';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <TagadaProvider>
      <App />
    </TagadaProvider>
  </React.StrictMode>
);

What TagadaProvider does:

✅ Initializes authentication and session
✅ Auto-initializes funnel (no manual initializeSession() needed)
✅ Handles automatic redirects
✅ Provides all hooks (useFunnel, useCheckout, etc.)

Step 4: Build Checkout Page

// src/pages/CheckoutPage.tsx
import { useState } from 'react';
import {
  useFunnel,
  useCheckout,
  useCurrency
} from '@tagadapay/plugin-sdk/v2';

export default function CheckoutPage() {
  const funnel = useFunnel();
  const { data: checkout, isLoading } = useCheckout();
  const { formatMoney } = useCurrency();
  
  const [formData, setFormData] = useState({
    email: '',
    name: '',
    cardNumber: '4242424242424242'
  });
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    // Simulate payment processing
    const mockOrder = {
      id: `ord_${Date.now()}`,
      amount: checkout?.total || 4900,
      currency: checkout?.currency || 'USD',
      items: checkout?.lineItems || []
    };

    // Navigate to next step - auto-redirects!
    await funnel.next({
      type: 'payment_success',
      data: {
        resources: {
          order: mockOrder,
          customer: {
            id: `cus_${Date.now()}`,
            email: formData.email,
            name: formData.name
          },
          payment: {
            id: `pay_${Date.now()}`,
            status: 'succeeded'
          }
        }
      }
    });
  };
  
  if (isLoading || !funnel.context) {
    return <div>Loading checkout...</div>;
  }
  
  return (
    <div style={{ maxWidth: 600, margin: '0 auto', padding: '2rem' }}>
      <h1>Checkout</h1>
      
      {checkout && (
        <div style={{ background: '#f5f5f5', padding: '1rem', marginBottom: '2rem' }}>
          <h2>Order Summary</h2>
          <p><strong>Total:</strong> {formatMoney(checkout.total, checkout.currency)}</p>
        </div>
      )}
      
      <form onSubmit={handleSubmit}>
        <div style={{ marginBottom: '1rem' }}>
          <label>Email</label>
          <input
            type="email"
            value={formData.email}
            onChange={(e) => setFormData({ ...formData, email: e.target.value })}
            style={{ width: '100%', padding: '0.75rem', marginTop: '0.5rem' }}
            required
          />
        </div>
        
        <div style={{ marginBottom: '1rem' }}>
          <label>Name</label>
          <input
            type="text"
            value={formData.name}
            onChange={(e) => setFormData({ ...formData, name: e.target.value })}
            style={{ width: '100%', padding: '0.75rem', marginTop: '0.5rem' }}
            required
          />
        </div>
        
        <div style={{ marginBottom: '1rem' }}>
          <label>Card Number (Test: 4242...)</label>
          <input
            type="text"
            value={formData.cardNumber}
            onChange={(e) => setFormData({ ...formData, cardNumber: e.target.value })}
            style={{ width: '100%', padding: '0.75rem', marginTop: '0.5rem' }}
            required
          />
        </div>
        
        <button
          type="submit"
          style={{
            width: '100%',
            padding: '1rem',
            background: '#0070f3',
            color: 'white',
            border: 'none',
            borderRadius: '4px',
            cursor: 'pointer'
          }}
        >
          Pay {formatMoney(checkout?.total || 4900, checkout?.currency || 'USD')}
        </button>
      </form>
    </div>
  );
}

Step 5: Build Thank You Page

// src/pages/ThankYouPage.tsx
import { useFunnel, useCurrency } from '@tagadapay/plugin-sdk/v2';
import { useParams } from 'wouter';

export default function ThankYouPage() {
  const { orderId } = useParams<{ orderId: string }>();
  const funnel = useFunnel();
  const { formatMoney } = useCurrency();
  
  // Access order data from previous step
  const order = funnel.context?.resources?.order;
  const customer = funnel.context?.resources?.customer;
  
  if (!funnel.context || !order) {
    return <div>Loading...</div>;
  }
  
  return (
    <div style={{ maxWidth: 600, margin: '0 auto', padding: '2rem', textAlign: 'center' }}>
      <div style={{ fontSize: '4rem' }}>✅</div>
      <h1>Thank You for Your Purchase!</h1>
      
      <div style={{ background: '#f5f5f5', padding: '1.5rem', marginTop: '2rem', textAlign: 'left' }}>
        <p><strong>Order #:</strong> {order.id}</p>
        <p><strong>Amount:</strong> {formatMoney(order.amount, order.currency)}</p>
        <p><strong>Email:</strong> {customer?.email}</p>
      </div>
      
      <p style={{ marginTop: '2rem' }}>
        A confirmation email has been sent to {customer?.email}
      </p>
    </div>
  );
}

Step 6: Setup Routing

# Install wouter (lightweight router)
npm install wouter

// src/App.tsx
import { Route, Switch } from 'wouter';
import CheckoutPage from './pages/CheckoutPage';
import ThankYouPage from './pages/ThankYouPage';

export default function App() {
  return (
    <Switch>
      <Route path="/checkout" component={CheckoutPage} />
      <Route path="/thankyou/:orderId" component={ThankYouPage} />
      <Route path="/" component={CheckoutPage} />
    </Switch>
  );
}

Step 7: Test Locally

# Start development server
npm run dev

# Visit http://localhost:5173/checkout

The SDK will automatically:

Create a session
Initialize the funnel
Enable debug mode (local environment)
Handle redirects after payment

Perfect for lightweight implementations or integrating with existing non-React apps.

Step 1: Create Project

# Create new Vite project
npm create vite@latest my-checkout -- --template vanilla-ts
cd my-checkout

# Install TagadaPay SDK
npm install @tagadapay/plugin-sdk

# Install dependencies
npm install

Step 2: Create Plugin Manifest

Create plugin.manifest.json in your project root:

{
  "name": "Vanilla Checkout",
  "pluginId": "vanilla-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
    }
  ]
}

Step 3: Update HTML

<!-- index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Checkout</title>
  </head>
  <body>
    <div id="app">
      <div id="loading">Loading checkout...</div>
      
      <div id="checkout-content" style="display: none;">
        <h1>Checkout</h1>
        
        <div id="order-summary">
          <h2>Order Summary</h2>
          <div id="order-items"></div>
          <p>Total: <span id="total-amount">--</span></p>
        </div>
        
        <form id="checkout-form">
          <label>Email:
            <input type="email" id="email" required />
          </label>
          
          <label>Name:
            <input type="text" id="name" required />
          </label>
          
          <button type="submit" id="pay-button">Pay Now</button>
        </form>
        
        <div id="error-message"></div>
      </div>
    </div>
    
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Step 4: Initialize SDK

// src/main.ts
import './style.css';
import {
  createTagadaClient,
  FunnelActionType,
  type TagadaState
} from '@tagadapay/plugin-sdk/v2/standalone';

// DOM elements
const loadingEl = document.getElementById('loading')!;
const contentEl = document.getElementById('checkout-content')!;
const formEl = document.getElementById('checkout-form')! as HTMLFormElement;
const emailInput = document.getElementById('email')! as HTMLInputElement;
const nameInput = document.getElementById('name')! as HTMLInputElement;
const payBtn = document.getElementById('pay-button')! as HTMLButtonElement;
const errorEl = document.getElementById('error-message')!;
const totalEl = document.getElementById('total-amount')!;

let globalClient: ReturnType<typeof createTagadaClient> | null = null;

async function init() {
  try {
    // Create Tagada Client
    const client = createTagadaClient({
      features: { funnel: true }
    });

    globalClient = client;

    // Wait for SDK to be ready
    const unsubscribe = client.subscribe(async (state: TagadaState) => {
      if (state.isInitialized && state.auth.session && state.store) {
        unsubscribe();

        try {
          if (!client.funnel) {
            throw new Error('Funnel feature not enabled');
          }

          // Auto-initialize funnel
          const context = await client.funnel.autoInitialize(
            {
              customerId: state.auth.session.customerId,
              sessionId: state.auth.session.sessionId
            },
            {
              id: state.store.id,
              accountId: state.store.accountId!
            }
          );

          if (context) {
            renderCheckout(state);
          }
        } catch (err) {
          showError(err instanceof Error ? err.message : 'Init failed');
        }
      }
    });
  } catch (err) {
    showError(err instanceof Error ? err.message : 'SDK failed');
  }
}

function renderCheckout(state: TagadaState) {
  loadingEl.style.display = 'none';
  contentEl.style.display = 'block';

  // Display order total (mock data)
  const total = 4900; // $49.00
  totalEl.textContent = `$${(total / 100).toFixed(2)}`;

  // Handle form submission
  formEl.onsubmit = async (e) => {
    e.preventDefault();
    
    payBtn.disabled = true;
    payBtn.textContent = 'Processing...';
    errorEl.textContent = '';

    try {
      if (!globalClient?.funnel) {
        throw new Error('Funnel not available');
      }

      // Process payment and navigate
      await globalClient.funnel.navigate({
        type: FunnelActionType.PAYMENT_SUCCESS,
        data: {
          resources: {
            order: {
              id: `ord_${Date.now()}`,
              amount: total,
              currency: 'USD'
            },
            customer: {
              id: `cus_${Date.now()}`,
              email: emailInput.value,
              name: nameInput.value
            },
            payment: {
              id: `pay_${Date.now()}`,
              status: 'succeeded'
            }
          }
        }
      } as any);

      // SDK auto-redirects - if we reach here, redirect failed
      alert('Payment successful!');
    } catch (err) {
      payBtn.disabled = false;
      payBtn.textContent = 'Pay Now';
      showError('Payment failed');
    }
  };
}

function showError(msg: string) {
  loadingEl.style.display = 'none';
  errorEl.textContent = `Error: ${msg}`;
}

// Start initialization
init();

Step 5: Add Basic Styles

/* src/style.css */
body {
  font-family: system-ui, sans-serif;
  max-width: 600px;
  margin: 0 auto;
  padding: 2rem;
}

form {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  margin-top: 2rem;
}

label {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

input {
  padding: 0.75rem;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 1rem;
}

button {
  padding: 1rem;
  background: #0070f3;
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 1rem;
  cursor: pointer;
}

button:hover {
  background: #0051cc;
}

button:disabled {
  background: #ccc;
  cursor: not-allowed;
}

#order-summary {
  background: #f5f5f5;
  padding: 1rem;
  border-radius: 4px;
  margin: 2rem 0;
}

#error-message {
  color: #d32f2f;
  margin-top: 1rem;
}

Step 6: Test Locally

# Start development server
npm run dev

# Visit http://localhost:5173

The SDK will automatically:

Create a session
Initialize the funnel
Enable debug mode (local environment)
Handle redirects after payment

Build for Production

# Build your plugin
npm run build

# Output will be in dist/ folder

Deploy to TagadaPay

Using CLI (Recommended)

# Install TagadaPay CLI globally
npm install -g @tagadapay/cli

# Login to your account
tgdcli login

# Deploy your plugin (interactive mode)
tgdcli deploy

# Follow prompts to:
# 1. Select store
# 2. Confirm build path (dist/)
# 3. Confirm deployment

Manual Upload

Go to TagadaPay Dashboard → Plugins
Click “Upload Plugin”
Upload your dist/ folder as a ZIP file
Fill in plugin details from manifest
Click “Deploy”

Use Your Plugin in a Funnel

Go to Funnels in your dashboard
Create a new funnel or edit existing
Add a “Checkout” step
Select your plugin from the dropdown
Select the /checkout page
Add a “Thank You” step
Select your plugin → /thankyou/:orderId page
Save and test your funnel!

What Happens Automatically?

The SDK handles these tasks for you:

Session Management

✅ Creates anonymous session automatically
✅ Manages authentication tokens
✅ Persists session across page loads

Funnel Initialization

✅ Auto-initializes when TagadaProvider mounts
✅ Loads funnel context from URL or cookie
✅ Creates new funnel session if needed

Navigation & Redirects

Debug Mode

✅ Enabled automatically in local development
✅ Loads config/resources.static.json for testing
✅ Disabled automatically in production

Common Issues

useFunnel() returns undefined

Solution: Make sure your app is wrapped with <TagadaProvider>

// main.tsx - MUST wrap your app
<TagadaProvider>
  <App />
</TagadaProvider>

Resources are empty on next page

Solution: Check that you’re passing resources correctly:

await funnel.next({
  data: {
    resources: {  // ← Must be inside "resources" key!
      order: { id: 'ord_123', amount: 100 },
      customer: { id: 'cus_456', email: '[email protected]' }
    }
  }
});

Redirect not working

Solution: The SDK auto-redirects by default. If it’s not working:

Check that funnel.next() returns successfully
Ensure the navigation response includes a url field
Verify you’re not preventing navigation with custom handlers

To debug:

const result = await funnel.next({ ... });
console.log('Navigation result:', result);
// Should have result.url property

TypeScript errors

Solution: Make sure you’re importing from the correct path:

// ✅ Correct - React hooks
import { useFunnel } from '@tagadapay/plugin-sdk/v2';

// ✅ Correct - Standalone SDK
import { createTagadaClient } from '@tagadapay/plugin-sdk/v2/standalone';

// ❌ Wrong - old path
import { useFunnel } from '@tagadapay/plugin-sdk';

Next Steps

Initialize Checkout

Create checkout sessions programmatically

Funnel Resources

Learn how to pass complex data between steps

API Reference

Explore all available hooks and methods

Tutorial

Build a complete multi-step funnel

Examples

See complete plugin examples

Manifest Guide

Master plugin configuration

Best Practices

Production-ready plugin development

Need Help?

Discord Community

Get help from the community

Documentation

Read the full docs

Support

Contact our team

Plugin SDK

Plugin CLI

Integration Guides

Quick Start Guide

Quick Start: Your First Plugin

What You’ll Build

Prerequisites

Choose Your Framework

Step 1: Create Project

Step 2: Create Plugin Manifest

Step 3: Wrap App with Provider

Step 4: Build Checkout Page

Step 5: Build Thank You Page

Step 6: Setup Routing

Step 7: Test Locally

Step 1: Create Project

Step 2: Create Plugin Manifest

Step 3: Update HTML

Step 4: Initialize SDK

Step 5: Add Basic Styles

Step 6: Test Locally

Build for Production

Deploy to TagadaPay

Using CLI (Recommended)

Manual Upload

Use Your Plugin in a Funnel

What Happens Automatically?

Common Issues

Next Steps

Initialize Checkout

Funnel Resources

API Reference

Tutorial

Examples

Manifest Guide

Best Practices

Need Help?

Discord Community

Documentation

Support

Plugin SDK

Plugin CLI

Integration Guides

​Quick Start: Your First Plugin

​What You’ll Build

​Prerequisites

​Choose Your Framework

​Step 1: Create Project

​Step 2: Create Plugin Manifest

​Step 3: Wrap App with Provider

​Step 4: Build Checkout Page

​Step 5: Build Thank You Page

​Step 6: Setup Routing

​Step 7: Test Locally

​Step 1: Create Project

​Step 2: Create Plugin Manifest

​Step 3: Update HTML

​Step 4: Initialize SDK

​Step 5: Add Basic Styles

​Step 6: Test Locally

​Build for Production

​Deploy to TagadaPay

​Using CLI (Recommended)

​Manual Upload

​Use Your Plugin in a Funnel

​What Happens Automatically?

​Common Issues

​Next Steps

Initialize Checkout

Funnel Resources

API Reference

Tutorial

Examples

Manifest Guide

Best Practices

​Need Help?

Discord Community

Documentation

Support

Quick Start: Your First Plugin

What You’ll Build

Prerequisites

Choose Your Framework

Step 1: Create Project

Step 2: Create Plugin Manifest

Step 3: Wrap App with Provider

Step 4: Build Checkout Page

Step 5: Build Thank You Page

Step 6: Setup Routing

Step 7: Test Locally

Step 1: Create Project

Step 2: Create Plugin Manifest

Step 3: Update HTML

Step 4: Initialize SDK

Step 5: Add Basic Styles

Step 6: Test Locally

Build for Production

Deploy to TagadaPay

Using CLI (Recommended)

Manual Upload

Use Your Plugin in a Funnel

What Happens Automatically?

Common Issues

Next Steps

Need Help?