Node SDK Quick Start
Create stores, deploy pages, and process payments from your server in 5 minutes
Time: \~5 minutes | Difficulty: Beginner
- Server automation: AI agents, CI/CD pipelines, batch jobs
- Programmatically managing stores, products, payments, customers, subscriptions
- Verifying webhook signatures
- Provisioning sub-merchants and minting per-merchant API keys (
tagada.partners.*— see the Partners section)
When NOT to use this SDK:
- Anything that runs in a browser — tokenization, 3DS challenges, wallet sheets → use
@tagadapay/core-jsor the Headless SDK - Custom checkout UI on your own domain → pair this SDK with the Headless SDK on the browser side
processing.applications.create() with your CRM key.
What Is the Node SDK?
The Node SDK lets you control AsherPay from your server. Think of it as the backend counterpart to the Plugin SDK — while the Plugin SDK builds the checkout UI, the Node SDK manages everything behind it.
┌──────────────────────────────────────────────┐
│ Your server / script / CI pipeline │
│ ↓ │
│ @tagadapay/node-sdk │
│ ↓ │
│ TagadaPay REST API │
│ • Create stores & products │
│ • Deploy checkout pages │
│ • Set up multi-step funnels │
│ • Process & route payments across PSPs │
│ • Manage subscriptions & customers │
└──────────────────────────────────────────────┘
Prerequisites
- Node.js 18+ (nodejs.org — run
node --versionto check) - A AsherPay API key — get one in 30 seconds (next section)
Get an API key in 30 seconds
You have three options. The first one is what AI coding tools / installers should use; the last one is what you'd do if you already have an account.
.env:
```bash theme={null}
npx -p @tagadapay/node-sdk@latest tagada-init you@example.com
```
Paste the 6-digit code from your inbox when prompted. Done — `TAGADA_API_KEY`, `TAGADA_STORE_ID`, and `TAGADA_ACCOUNT_ID` are now in `.env`.
```ts theme={null}
import Tagada from '@tagadapay/node-sdk';
const onboarding = Tagada.public();
await onboarding.start({ email: 'you@example.com' });
// ...prompt the user / read from a query string...
const { apiKey, storeId } = await onboarding.verify({
email: 'you@example.com',
code: '123456',
});
const tagada = new Tagada(apiKey); // ready to call any resource
```
<Frame>
<img src="https://mintcdn.com/tagadapay/TKkbuy8GaudqLW4Y/assets/images/api-key-menu.png?fit=max&auto=format&n=TKkbuy8GaudqLW4Y&q=85&s=5610f731f341dd04cbf426269c14398d" alt="Navigate to Settings from the user menu" width="1024" height="993" data-path="assets/images/api-key-menu.png" />
</Frame>
2. **Access Tokens** → **+ Create Access Token** → copy the UUID.
<Frame>
<img src="https://mintcdn.com/tagadapay/TKkbuy8GaudqLW4Y/assets/images/api-key-settings.png?fit=max&auto=format&n=TKkbuy8GaudqLW4Y&q=85&s=c6473adc09ba63dde29d03d9b7751d6a" alt="Access Tokens page in Settings" width="1024" height="397" data-path="assets/images/api-key-settings.png" />
</Frame>
tagada-init writes (Vite / Next / Astro): Get an API key from code.
Install
```bash theme={null} npm install @tagadapay/node-sdk
***
## Initialize
```ts theme={null}
import Tagada from '@tagadapay/node-sdk';
const tagada = new Tagada('your-api-key');
That's it. Every resource is now available via tagada.<resource>.
Example: Full Checkout Setup in 7 Steps
This script creates a processor, payment flow, store, product, and funnel — activates the checkout — then generates a checkout session link. No plugin deployment needed; AsherPay's native checkout is auto-injected.
```ts theme={null} import Tagada from '@tagadapay/node-sdk'; const tagada = new Tagada('your-api-key');
// 1. Create a sandbox processor (or use 'stripe', 'nmi', etc.) const { processor } = await tagada.processors.create({ processor: { name: 'Sandbox', type: 'sandbox', enabled: true, supportedCurrencies: ['USD'], baseCurrency: 'USD', options: { testMode: true }, }, });
// 2. Create a payment flow const flow = await tagada.paymentFlows.create({ data: { name: 'Default', strategy: 'simple', fallbackMode: false, maxFallbackRetries: 0, threeDsEnabled: false, stickyProcessorEnabled: false, pickProcessorStrategy: 'weighted', processorConfigs: [{ processorId: processor.id, weight: 100, disabled: false, nonStickable: false }], fallbackProcessorConfigs: [], abuseDetectionConfig: null, }, });
// 3. Create a store with the payment flow const store = await tagada.stores.create({ name: 'My Store', baseCurrency: 'USD', presentmentCurrencies: ['USD', 'EUR'], chargeCurrencies: ['USD'], selectedPaymentFlowId: flow.id, });
// 4. Create a product const product = await tagada.products.create({ storeId: store.id, name: 'Premium Plan', active: true, variants: [{ name: 'Monthly', sku: 'premium-monthly', grams: 0, price: 2999, compareAtPrice: 0, active: true, default: true, prices: [{ currencyOptions: { USD: { amount: 2999 } }, recurring: false, billingTiming: 'in_advance', default: true }], }], }); const variantId = product.variants[0].id;
// 5. Create a funnel (native checkout auto-injected) const funnel = await tagada.funnels.create({ storeId: store.id, config: { id: 'my-checkout', name: 'My Checkout', version: '1.0.0', nodes: [ { id: 'step_checkout', name: 'Checkout', type: 'checkout', kind: 'step', isEntry: true, position: { x: 0, y: 0 }, config: { path: '/checkout' } }, { id: 'step_thankyou', name: 'Thank You', type: 'thankyou', kind: 'step', position: { x: 300, y: 0 }, config: { path: '/thankyou' } }, ], edges: [{ id: 'e1', source: 'step_checkout', target: 'step_thankyou' }], }, isDefault: true, });
// 6. Activate (mounts routes, checkout goes live) const result = await tagada.funnels.update(funnel.id, { storeId: store.id, config: funnel.config, });
const funnelCheckoutUrl = result.funnel.config.nodes .find(n => n.id === 'step_checkout').config.url; console.log('Funnel live at:', funnelCheckoutUrl);
// 7. Create a checkout session — shareable link with pre-loaded cart const session = await tagada.checkout.createSession({ storeId: store.id, items: [{ variantId, quantity: 1 }], currency: 'USD', checkoutUrl: funnelCheckoutUrl, }); console.log('Checkout link:', session.redirectUrl);
<Tip>
For a detailed walkthrough of each step, see the [Merchant Quick Start](/guides/merchant-quickstart.html). For deploying your own pages (checkout, landing, offers) instead of the native checkout, see Funnel Pages.
</Tip>
***
## Available Resources
Every resource follows the same patterns: `list`, `retrieve`, `create`, `update`, `del`.
| Resource | Examples |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`tagada.stores`** | `.list()`, `.create(...)`, `.retrieve(id)` |
| **`tagada.products`** | `.list(...)`, `.create(...)`, `.update(...)` |
| **`tagada.payments`** | `.list(...)`, `.process(...)`, `.refund(...)`, `.void(...)` |
| **`tagada.paymentFlows`** | `.create(...)`, `.listWithProcessors()` — define how payments cascade across PSPs |
| **`tagada.funnels`** | `.create(...)`, `.update(id, ...)`, `.promote(id, ...)` — multi-step flows with auto-routing |
| **`tagada.shopify`** | `.checkScript(storeId)`, `.updateScript(storeId, ...)`, `.removeScript(storeId)`, `.audit(storeId)` — Shopify checkout script |
| **`tagada.plugins`** | `.deployDirectory(...)` (recommended), `.deploy(...)`, `.instantiate(...)`, `.mount(...)`, `.configureSplit(...)` — host pages on AsherPay's CDN with A/B testing |
| **`tagada.subscriptions`** | `.create(...)`, `.cancel(...)`, `.rebill(id)`, `.changeProcessor(...)` |
| **`tagada.customers`** | `.list(...)`, `.retrieve(id)` |
| **`tagada.orders`** | `.list(...)`, `.retrieve(id)` |
| **`tagada.webhooks`** | `.create(...)`, `.list(...)`, `.del(id)` |
| **`tagada.events`** | `.recent(...)`, `.list(...)`, `.statistics(...)` — event log and audit trail |
| **`tagada.emailTemplates`** | `.create(...)`, `.list(...)`, `.update(...)`, `.test(...)`, `.del(...)` — Emails guide |
| **`tagada.promotions`** | `.create(...)`, `.list(...)`, `.update(...)` — discounts |
| **`tagada.promotionCodes`** | `.create(...)`, `.list(...)` — discount codes |
| **`tagada.offers`** | `.list(...)`, `.create(...)` — upsells, downsells, order bumps |
| **`tagada.blockRules`** | `.create(...)`, `.list(...)`, `.del(...)` — fraud prevention |
| **`tagada.paymentInstruments`** | `.createFromToken(...)`, `.list(...)`, `.retrieve(id)`, `.del(id)` — stored payment methods |
| **`tagada.checkoutOffers`** | `.list(...)`, `.create(...)`, `.update(...)`, `.del(...)` — checkout-scoped offers |
| **`tagada.checkout`** | `.createSession(...)`, `.pay(...)` — create checkout links and process payments server-side |
| **`tagada.processors`** | `.list()`, `.create(...)`, `.retrieve(id)`, `.update(...)`, `.del([ids])` — manage PSP connections |
| **`tagada.domains`** | `.add(...)`, `.list(...)`, `.verify(...)`, `.remove(...)`, `.getConfig(...)`, `.getDnsLookup(...)` — Custom Domains guide |
***
## Payment Flows: The Core of AsherPay
AsherPay is **PSP-agnostic**. You connect multiple processors (Stripe, Adyen, NMI, etc.) and define **payment flows** that route transactions intelligently.
```ts theme={null}
const flow = await tagada.paymentFlows.create({
data: {
name: 'US Primary',
strategy: 'cascade', // 'simple' = single processor, 'cascade' = fallback chain
fallbackMode: true,
maxFallbackRetries: 3,
threeDsEnabled: false,
stickyProcessorEnabled: true,
pickProcessorStrategy: 'weighted', // 'weighted' | 'lowestCapacity' | 'automatic'
processorConfigs: [
{ processorId: 'proc_stripe', weight: 60, disabled: false, nonStickable: false },
{ processorId: 'proc_adyen', weight: 40, disabled: false, nonStickable: false },
],
fallbackProcessorConfigs: [
{ processorId: 'proc_nmi', orderIndex: 0 },
],
},
});
60% of traffic goes to Stripe, 40% to Adyen. If both fail, NMI picks up the payment. All automatic.
Error Handling
The SDK throws typed errors you can catch individually:
```ts theme={null} import Tagada, { TagadaNotFoundError, TagadaValidationError, TagadaAuthenticationError, TagadaRateLimitError, } from '@tagadapay/node-sdk';
try {
await tagada.payments.retrieve('pay_nonexistent');
} catch (err) {
if (err instanceof TagadaNotFoundError) {
// 404 — resource doesn't exist
} else if (err instanceof TagadaValidationError) {
console.log(err.errors); // [{ field: 'amount', message: 'Required' }]
} else if (err instanceof TagadaRateLimitError) {
console.log(Retry after ${err.retryAfter}s);
}
}
Retries on `429`, `5xx`, and network errors are automatic (configurable via `maxRetries`).
***
## Configuration
```ts theme={null}
const tagada = new Tagada({
apiKey: 'your-api-key',
baseUrl: 'https://app.tagadapay.com/api/public/v1', // default
timeout: 30_000, // request timeout
maxRetries: 2, // auto-retry on failure
apiVersion: '2025-01-01',
});
idempotencyKey to safely retry mutations:
ts theme={null}
await tagada.payments.process(params, { idempotencyKey: 'unique-key-123' });
TypeScript
Fully typed. Import any type you need:
ts theme={null}
import type { Payment, Customer, Subscription, TagadaList } from '@tagadapay/node-sdk';