TagadaPay Developer Documentation

https://docs.tagada.io
Admin
Complete developer documentation for TagadaPay, covering REST APIs, SDKs, CLIs, and integration...
Tokens:528,718
Snippets:3,913
Trust Score:5.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Run Development Server

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Commands to install dependencies and start the local development server.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Start Development Server

Source: https://docs.tagada.io/developer-tools/examples/apple-google-pay

Commands to clone and run the example project locally.

```bash
git clone https://github.com/TagadaPay/examples.git
cd examples/apple-google-tokenization
pnpm install && pnpm dev        # http://localhost:5173
```

--------------------------------

### Payment Flow Configuration Examples

Source: https://docs.tagada.io/api-reference/payment-flows/create-payment-flow

Examples demonstrating simple single-processor setups and complex cascade flows with fallback mechanisms.

```yaml
simple:
  summary: Simple single-processor flow
  value:
    data:
      name: Simple Stripe
      strategy: simple
      fallbackMode: false
      maxFallbackRetries: 0
      threeDsEnabled: false
      stickyProcessorEnabled: false
      pickProcessorStrategy: weighted
      processorConfigs:
        - processorId: proc_stripe
          weight: 100
          disabled: false
          nonStickable: false
      fallbackProcessorConfigs: []
      abuseDetectionConfig: null
```

```yaml
cascade:
  summary: Cascade flow with fallback
  value:
    data:
      name: Cascade Stripe → Checkout
      strategy: cascade
      fallbackMode: true
      maxFallbackRetries: 2
      threeDsEnabled: true
      stickyProcessorEnabled: true
```

--------------------------------

### Initialize checkout session examples

Source: https://docs.tagada.io/api-reference/checkout/initialize-checkout-session

Examples of GET requests to the checkout initialization endpoint, demonstrating parameter forwarding and customer prefilling.

```http
GET /api/public/v1/checkout/init?storeId=store_123&items=[{"variantId":"var_123","quantity":1}]&currency=USD
→ Redirects to: https://checkout.example.com/checkout/ch_abc123/op?token=cms_token_xyz
```

```http
GET /api/public/v1/checkout/init?storeId=store_123&items=[...]&currency=USD&utm_source=email&custom_param=value
→ Redirects to: https://checkout.example.com/checkout/ch_abc123/op?token=cms_token_xyz&utm_source=email&custom_param=value
```

```http
GET /api/public/v1/checkout/init?storeId=store_123&items=[...]&currency=USD&customerEmail=john@example.com&customerFirstName=John&customerLastName=Doe
→ Redirects to checkout with customer information prefilled
```

--------------------------------

### Programmatic SDK Initialization

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Use the SDK methods directly for programmatic setup, suitable for AI agents or automated installers.

```javascript
Tagada.public().start(...) then verify(...)
```

--------------------------------

### Execute setup script

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Use tsx to run the TypeScript setup file.

```bash
npx tsx setup.ts
```

--------------------------------

### Install Plugin Instance

Source: https://docs.tagada.io/developer-tools/cli/introduction

Install a deployed plugin to create an instance. You can optionally configure it during this step.

```bash
tgd install --store store_abc123
```

--------------------------------

### Programmatic Onboarding with SDK

Source: https://docs.tagada.io/developer-tools/node-sdk/quick-start

Use the SDK to start an onboarding flow and verify credentials programmatically, suitable for AI agents or custom installers.

```ts
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
```

--------------------------------

### Subscription Creation Examples

Source: https://docs.tagada.io/api-reference/subscriptions/create-subscription

Various JSON payloads for creating subscriptions, covering basic setups, trial periods, and pre-configured payment methods.

```json
{
  "customerId": "cust_123",
  "priceId": "price_456",
  "storeId": "store_789",
  "quantity": 1,
  "currency": "USD",
  "initiatePayment": false
}
```

```json
{
  "customerId": "cust_123",
  "priceId": "price_456",
  "storeId": "store_789",
  "quantity": 2,
  "currency": "USD",
  "trialSettings": {
    "trialPeriodDuration": 14,
    "trialPeriodDurationType": "day"
  },
  "metadata": {
    "source": "api",
    "campaign": "trial_offer"
  }
}
```

```json
{
  "customerId": "cust_123",
  "priceId": "price_456",
  "storeId": "store_789",
  "quantity": 1,
  "currency": "USD",
  "defaultPaymentInstrumentId": "pi_123",
  "billingCycleAnchor": "2024-04-01T00:00:00Z"
}
```

--------------------------------

### Define Payment Setup Configuration

Source: https://docs.tagada.io/developer-tools/node-sdk/step-config-guide

A comprehensive example showing how to map multiple payment methods with their respective providers and routing identifiers.

```ts
stepConfig: {
  paymentSetupConfig: {
    card: {
      enabled: true,
      method: 'card',
      provider: 'tagada',
      paymentFlowId: 'flow_xxx',
    },
    'apple_pay:stripe': {
      enabled: true,
      method: 'apple_pay',
      provider: 'stripe',
      express: true,
      processorId: 'processor_xxx',
    },
    'google_pay:stripe': {
      enabled: true,
      method: 'google_pay',
      provider: 'stripe',
      express: true,
      processorId: 'processor_xxx',
    },
    'klarna:airwallex': {
      enabled: false,
      method: 'klarna',
      provider: 'airwallex',
      processorId: 'processor_yyy',
    },
  },
}
```

--------------------------------

### Install Tagada SDKs

Source: https://docs.tagada.io/developer-tools/partners/quick-start

Install the required Node.js SDKs for partner server-to-server integration.

```bash
npm install @tagadapay/node-sdk @tagadapay/core-js
```

--------------------------------

### Install TagadaPay Tokenization SDK

Source: https://docs.tagada.io/developer-tools/payments/core-js-payments

Install the required client-side library via npm.

```bash
npm install @tagadapay/core-js
```

--------------------------------

### Create Preview Session Request Example

Source: https://docs.tagada.io/api-reference/funnels/create-a-preview-session

Example payload for initiating a new preview session.

```json
storeId: store_123
funnelId: funnelv2_123
stepId: step_thankyou
accountId: acc_123
contextData:
  orderId: order_abc123
```

--------------------------------

### Successful Deployment Response Example

Source: https://docs.tagada.io/api-reference/plugins/deploy-plugin-from-blob-url

Example response returned upon a successful plugin deployment.

```json
{
  "success": true,
  "deployment": {
    "pluginId": "sample-funnel",
    "version": "1.0.0",
    "url": "https://sample-funnel-abc123.cdn.tagada.dev/",
    "deployedAt": "2024-03-20T10:30:00Z",
    "size": 15000000
  },
  "message": "Plugin Sample Funnel Plugin v1.0.0 deployed successfully from blob"
}
```

--------------------------------

### Deploy Plugin Request Example

Source: https://docs.tagada.io/api-reference/plugins/deploy-plugin-from-blob-url

Example request body for deploying a plugin from a blob URL.

```json
{
  "blobUrl": "https://blob.vercel-storage.com/plugins/plugin.zip",
  "pluginData": "{\"pluginId\":\"sample-funnel\",\"version\":\"1.0.0\",\"name\":\"Sample Funnel Plugin\",\"description\":\"A sample funnel plugin\",\"author\":\"Tagada Pay Team\",\"storeId\":\"store_123\",\"mode\":\"direct-mode\"}"
}
```

--------------------------------

### Promotion Details Response Example

Source: https://docs.tagada.io/api-reference/promotions/get-promotion-by-id

Example of a successful response containing promotion configuration and rules.

```json
id: promo_123
name: Summer Sale 20% Off
enabled: true
automatic: false
usageLimit: 100
usageCount: 42
startDate: '2025-06-01T00:00:00.000Z'
endDate: '2025-08-31T23:59:59.000Z'
ruleOperator: AND
rules: []
actions:
  - type: OrderAdjustment
    adjustmentType: percentage
    adjustmentPercentage: 20
```

--------------------------------

### Get Promotion Details Request Example

Source: https://docs.tagada.io/api-reference/promotions/get-promotion-by-id

Example payload for requesting promotion details by ID.

```json
id: promo_123
storeId: store_123
```

--------------------------------

### Get Domain Configuration Request Example

Source: https://docs.tagada.io/api-reference/domains/get-domain-configuration

Example payload for requesting the configuration of a specific domain.

```yaml
domain: checkout.example.com
```

--------------------------------

### Initialize project and install dependencies

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Run these commands to set up a new directory and install the required Tagada SDK packages.

```bash
mkdir my-store && cd my-store
npm init -y
npm install @tagadapay/node-sdk @tagadapay/headless-sdk
```

--------------------------------

### Install Plugin and Manage Instances

Source: https://docs.tagada.io/developer-tools/cli/introduction

Install a plugin from the store and manage its instances. This includes listing instances, mounting plugins to aliases, and listing mount points.

```bash
tgd install --store store_abc123
# Interactive — select plugin, configure, create instance

tgd list-instances --store store_abc123
# Shows instances grouped by plugin → version → config

tgd mount-alias --store store_abc123
# Interactive — select instance, pick alias

tgd list-mounts --store store_abc123
# Shows all aliases/domains and their mounted routes
```

--------------------------------

### Initialize Checkout Session Examples

Source: https://docs.tagada.io/api-reference/checkout/initialize-checkout-session

Examples showing basic checkout initialization, forwarding custom query parameters, and prefilling customer information.

```http
GET
/api/public/v1/checkout/init?storeId=store_123&items=[{"variantId":"var_123","quantity":1}]&currency=USD

→ Redirects to:
https://checkout.example.com/checkout/ch_abc123/op?token=cms_token_xyz
```

```http
GET
/api/public/v1/checkout/init?storeId=store_123&items=[...]&currency=USD&utm_source=email&custom_param=value

→ Redirects to:
https://checkout.example.com/checkout/ch_abc123/op?token=cms_token_xyz&utm_source=email&custom_param=value
```

```http
GET
/api/public/v1/checkout/init?storeId=store_123&items=[...]&currency=USD&customerEmail=john@example.com&customerFirstName=John&customerLastName=Doe

→ Redirects to checkout with customer information prefilled
```

--------------------------------

### Get deployment details example payload

Source: https://docs.tagada.io/api-reference/plugins-v2/get-deployment-details-v2

Example JSON payload for requesting deployment details using deploymentId and storeId.

```json
{
  "deploymentId": "plugin_deployment_abc123",
  "storeId": "store_abc123"
}
```

--------------------------------

### Clone and run the SaaS billing example

Source: https://docs.tagada.io/developer-tools/saas-billing/introduction

Commands to set up the local development environment for the Tagada SaaS billing example project.

```bash
git clone https://github.com/TagadaPay/examples.git
cd examples/mini-saas-billing   # or examples/mini-saas-billing in the monorepo
cp env.example .env             # add TAGADA_API_KEY + TAGADA_STORE_ID
npm install
npm run seed                    # product + cascade payment flow
npm run verify                  # automated end-to-end test
npm run dev                     # frontend :5173 + backend :3001
```

--------------------------------

### List payment flows request examples

Source: https://docs.tagada.io/api-reference/payment-flows

Examples of how to perform a GET request to retrieve payment flows using various programming languages.

```bash
curl --request GET \
  --url https://api.tagada.io/api/public/v1/payment-flows \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://api.tagada.io/api/public/v1/payment-flows"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tagada.io/api/public/v1/payment-flows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tagada.io/api/public/v1/payment-flows",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tagada.io/api/public/v1/payment-flows"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.tagada.io/api/public/v1/payment-flows")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.tagada.io/api/public/v1/payment-flows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Install and Mount Plugin Instance

Source: https://docs.tagada.io/developer-tools/cli/quick-start

After deployment, install the plugin instance for a specific store and then mount it by choosing an alias path.

```bash
tgd install --store store_abc123
# Select your deployment, configure if needed

tgd mount-alias --store store_abc123
# Select the instance, choose an alias path
```

--------------------------------

### Run the development server

Source: https://docs.tagada.io/developer-tools/saas-billing/quick-start

Starts the local development environment for the billing demo.

```bash
npm run dev
```

--------------------------------

### Install @vercel/blob Client

Source: https://docs.tagada.io/developer-tools/hosting/deploy-and-ab-test

Install the necessary client library to handle blob uploads. This library simplifies the process of getting an upload token and confirming completion.

```bash
npm install @vercel/blob
```

--------------------------------

### Run Development Server

Source: https://docs.tagada.io/developer-tools/sdk/quick-start

Start the local development server to test your integration. Open the provided URL in your browser.

```bash
npm run dev
# Open http://localhost:5173
```

--------------------------------

### Get Processor by ID Request Example

Source: https://docs.tagada.io/api-reference/processors/get-processor-by-id

Use this JSON payload to request details for a specific processor.

```json
{
  "processorId": "processor_abc123"
}
```

--------------------------------

### Get Funnel by ID Success Response

Source: https://docs.tagada.io/api-reference/funnels/get-funnel-by-id

Example of a successful JSON response when retrieving funnel details.

```json
{
  "id": "funnelv2_123",
  "name": "My Funnel",
  "active": true,
  "config": {
    "steps": []
  },
  "store": {
    "id": "store_123",
    "name": "My Store"
  }
}
```

--------------------------------

### Mount Plugin V2 Configuration Examples

Source: https://docs.tagada.io/api-reference/plugins-v2/mount-plugin-v2

Examples demonstrating how to mount a plugin to a hostname, custom domain, or alias.

```yaml
deploymentId: plugin_deployment_abc123
storeId: store_abc123
hostname: cdn.example.com
basePath: /
matcher: .*
```

```yaml
deploymentId: plugin_deployment_abc123
storeId: store_abc123
customDomain: checkout.example.com
basePath: /checkout
matcher: /checkout/.*
```

```yaml
deploymentId: plugin_deployment_abc123
storeId: store_abc123
alias: checkout
basePath: /
```

--------------------------------

### List Funnels Response Example

Source: https://docs.tagada.io/api-reference/funnels/list-funnels-for-a-store

The successful response structure for the GET /api/public/v1/stores/{storeId}/funnels endpoint.

```json
{
  "funnels":
    [
      {
        "id": "funnelv2_123",
        "name": "Default Funnel",
        "status": "active",
        "stepsCount": 3,
        "isDefault": true
      }
    ]
}
```

--------------------------------

### GET /stores/{storeId}/shopify-script

Source: https://docs.tagada.io/developer-tools/shopify/checkout-script

Read the currently installed Tagada checkout script and its configuration for a specific store.

```APIDOC
## GET /stores/{storeId}/shopify-script

### Description
Retrieves the details and configuration of the Tagada checkout script currently installed on the specified Shopify store.

### Method
GET

### Endpoint
/stores/{storeId}/shopify-script

### Parameters
#### Path Parameters
- **storeId** (string) - Required - The unique identifier of the Shopify store.
```

--------------------------------

### Deploy Plugin from URL Examples

Source: https://docs.tagada.io/api-reference/plugins-v2/deploy-plugin-from-url-v2

Examples showing the JSON payload structure for deploying a plugin, including a standard deployment and an overwrite deployment.

```json
{
  "url": "https://example.com/plugin.zip",
  "pluginId": "checkout-plugin",
  "version": "1.0.0",
  "name": "Checkout Plugin",
  "description": "A checkout plugin",
  "storeId": "store_abc123",
  "mode": "direct-mode"
}
```

```json
{
  "url": "https://example.com/plugin.zip",
  "pluginId": "checkout-plugin",
  "version": "1.0.0",
  "name": "Checkout Plugin",
  "description": "A checkout plugin",
  "storeId": "store_abc123",
  "mode": "direct-mode",
  "overwrite": true
}
```

--------------------------------

### Config Preset Example

Source: https://docs.tagada.io/developer-tools/cli/configuration

An example of a configuration preset file. These files are synced to the deployment environment and used to set up instances.

```json
{
  "theme": {
    "primaryColor": "#007bff",
    "fontFamily": "Inter, sans-serif"
  },
  "features": {
    "expressCheckout": true,
    "upsells": true
  }
}
```

--------------------------------

### Get source data for a specific deployment

Source: https://docs.tagada.io/api-reference/plugins-v2/get-deployment-source-data-v2

Request body example including both pluginId and deploymentId to target a specific deployment.

```json
{
  "pluginId": "my-landing-page-abc123",
  "deploymentId": "abc123xyz"
}
```

--------------------------------

### Get source data for a plugin

Source: https://docs.tagada.io/api-reference/plugins-v2/get-deployment-source-data-v2

Basic request body example to retrieve source data for a specific plugin ID.

```json
{
  "pluginId": "my-landing-page-abc123"
}
```

--------------------------------

### Initialize Tagada Store via CLI

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Commands to clone the example repository and initialize a new Tagada account and store.

```bash
git clone https://github.com/TagadaPay/examples.git
cd examples/headless-react-store
npx -p @tagadapay/node-sdk@latest tagada-init you@example.com
```

--------------------------------

### Initialize Project and Install SDK

Source: https://docs.tagada.io/developer-tools/sdk/tutorial

Commands to scaffold a React TypeScript project and install the TagadaPay plugin SDK and router dependencies.

```bash
# Create project
npm create vite@latest my-checkout -- --template react-ts
cd my-checkout

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

# Install dependencies
npm install
```

--------------------------------

### Get Domain Configuration Success Response

Source: https://docs.tagada.io/api-reference/domains/get-domain-configuration

Example of a successful response containing domain configuration details such as CNAME and accepted challenges.

```json
configuredBy: CNAME
misconfigured: false
recommendedCNAME: cname.vercel-dns.com
acceptedChallenges:
  - dns-01
  - http-01
```

--------------------------------

### Initialize Merchant and Processing Setup

Source: https://docs.tagada.io/developer-tools/partners/merchant-automation

Demonstrates the end-to-end flow for creating a merchant, generating keys, and setting up a processing TPA.

```ts
const partner = new Tagada(process.env.PARTNER_KEY!);

// 1. CRM: create the merchant + a CRM Key
const merchant = await partner.partners.crm.merchants.create({
  legalName: 'Acme SAS',
  externalRef: 'merchant_42',
});
const crmKey = await partner.partners.crm.merchants.keys.create(merchant.id);

// 2. Processing — pick the path that matches your contract:
//    • Payfac WL: tpas.create (below)
//    • CRM-only: applications.create({ accountId: merchant.id, … }) then enroll after promote
//      → see /developer-tools/partners/accounts and processing-applications
const tpa = await partner.partners.processing.tpas.create({
  legalName: 'Acme SAS',       // required — the KYB legal entity
  accountId: merchant.id,      // attach to the existing merchant (acc_xxx)
  externalRef: 'merchant_42_eu',
  country: 'FR',
  currency: 'EUR',
});
const processingKey = await partner.partners.processing.tpas.keys.create(tpa.id);

// 3. Discover the auto-created store
const stores = await partner.stores.list({ accountId: merchant.id });
const storeId = stores.data[0].id;

// 4. Persist on your side
await yourVault.put(merchant.externalRef ?? merchant.id, {
  crmKey: crmKey.token,
  processingKey: processingKey.secret,
  storeId,
});
```

--------------------------------

### Checkout Step Configuration

Source: https://docs.tagada.io/developer-tools/node-sdk/custom-checkout

Example of a checkout step configuration, including payment setup, order bumps, and pixels. Use for payment pages.

```typescript
{
  id: 'step_checkout',
  type: 'checkout',
  config: {
    stepConfig: {
      paymentSetupConfig: { card: { enabled: true, paymentFlowId: 'flow_xxx' } },
      orderBumps: { mode: 'custom', enabledOfferIds: ['offer_1'] },
      pixels: { facebook: [...] },
    },
  },
}
```

--------------------------------

### Create a Product

Source: https://docs.tagada.io/developer-tools/node-sdk/merchant-quickstart

Define what you are selling, including multi-currency pricing and variant details. This example sets up a monthly premium plan.

```typescript
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 },
        EUR: { amount: 2599 },
      },
      recurring: false,
      billingTiming: 'in_advance',
      default: true,
    }],
  }],
});

const variantId = product.variants[0].id;
console.log('Product:', product.id, '| Variant:', variantId);
```

--------------------------------

### GET /api/public/v1/stores/{storeId}/shopify-script

Source: https://docs.tagada.io/developer-tools/shopify/checkout-script

Retrieves the current installation status of the Shopify script, including the bound funnel configuration and conflict detection.

```APIDOC
## GET /api/public/v1/stores/{storeId}/shopify-script

### Description
Find out whether the script is installed and which funnel/step it currently points at. Pass funnelId and stepId to also get conflict detection against a target funnel.

### Method
GET

### Endpoint
/api/public/v1/stores/{storeId}/shopify-script

### Parameters
#### Path Parameters
- **storeId** (string) - Required - The unique identifier of the Shopify store.

#### Query Parameters
- **funnelId** (string) - Optional - The target funnel ID for conflict detection.
- **stepId** (string) - Optional - The target step ID for conflict detection.

### Response
#### Success Response (200)
- **isInjected** (boolean) - Whether the script is currently injected.
- **themeName** (string) - The name of the active Shopify theme.
- **shopUrl** (string) - The URL of the Shopify shop.
- **config** (object) - The current configuration object.
- **isConflict** (boolean) - Whether the current configuration conflicts with the provided target.
- **conflictDetails** (object) - Details regarding the detected conflict.
```

--------------------------------

### Install Headless SDK

Source: https://docs.tagada.io/developer-tools/headless-sdk/introduction

Commands to install the primary headless SDK and the optional core library for client-side card tokenization.

```bash
npm install @tagadapay/headless-sdk

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

--------------------------------

### Verify Plugin Installation and Mounts

Source: https://docs.tagada.io/developer-tools/cli/quick-start

List installed plugins, instances, and their mount points for a given store to verify the deployment and mounting process.

```bash
tgd list --store store_abc123
tgd list-instances --store store_abc123
tgd list-mounts --store store_abc123
```

--------------------------------

### Get Payment Setup Configuration

Source: https://docs.tagada.io/developer-tools/partners/payment-setup

Retrieve the runtime payment configuration for a specific store. This is the primary method for obtaining the data needed to render payment options.

```typescript
const setup = await tagada.paymentSetup.get('store_xxx');
```

--------------------------------

### Payment Setup Configuration JSON Structure

Source: https://docs.tagada.io/developer-tools/partners/payment-setup

An example of the `paymentSetupConfig` object, showing enabled payment methods and their associated providers and configurations. Keys are typically in the format "{method}" or "{method}:{provider}".

```json
{
  "card": {
    "enabled": true,
    "method": "card",
    "provider": "tagada",
    "paymentFlowId": "pf_eu_cascade"
  },
  "apple_pay": {
    "enabled": true,
    "method": "apple_pay",
    "provider": "apple_pay",
    "type": "apple_pay",
    "express": true,
    "processorId": "proc_native_apple",
    "metadata": { "country": "FR" }
  },
  "klarna:stripe": {
    "enabled": true,
    "method": "klarna",
    "provider": "stripe",
    "type": "apm",
    "processorId": "proc_stripe_eu"
  },
  "express_checkout:proc_stripe_eu": {
    "enabled": true,
    "method": "express_checkout",
    "provider": "stripe",
    "publishableKey": "pk_live_xxx",
    "methods": {
      "apple_pay":  { "enabled": true },
      "google_pay": { "enabled": true },
      "link":       { "enabled": true }
    }
  }
}
```

--------------------------------

### List Plugin Deployments Response Example

Source: https://docs.tagada.io/api-reference/plugins/list-plugin-deployments

Example of a successful response containing a list of deployment objects with plugin metadata.

```json
{
  "deployments": [
    {
      "id": "dep_123",
      "pluginId": "jointboost-variant-a",
      "version": "1.0.2",
      "url": "https://jointboost-variant-a-abc123.cdn.tagada.dev/",
      "active": true,
      "mode": "direct-mode",
      "size": 264697,
      "deployedAt": "2024-03-20T10:30:00Z",
      "plugin": {
        "id": "jointboost-variant-a",
        "name": "JointBoost Variant A",
        "description": "Green theme variant for A/B testing"
      }
    }
  ]
}
```

--------------------------------

### TagadaPay CLI - Start Only

Source: https://docs.tagada.io/developer-tools/node-sdk/get-api-key

Initiates the TagadaPay onboarding process by mailing an OTP and then exits. This is useful for CI/CD or scripted environments where user interaction is handled separately.

```bash
npx -p @tagadapay/node-sdk@latest tagada-init you@example.com --start-only
```

--------------------------------

### Implement Browser Checkout with Apple Pay and Card Payments

Source: https://docs.tagada.io/developer-tools/partners/examples

This example shows how to initialize the TagadaPay Tokenizer, conditionally render Apple Pay buttons, and handle card form submissions. Ensure the merchant setup is fetched securely from your own backend before initializing client-side components.

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <title>Acme — Checkout</title>
</head>
<body>
  <h1>Pay €49.99</h1>

  <!-- Express buttons (rendered conditionally based on paymentSetup) -->
  <div id="express-buttons"></div>

  <!-- Card form -->
  <form id="card-form">
    <input id="card-number" placeholder="Card number" />
    <input id="card-expiry" placeholder="MM/YY" />
    <input id="card-cvc" placeholder="CVC" />
    <button type="submit">Pay with card</button>
  </form>

  <script type="module">
    import {
      Tokenizer,
      isApplePayAvailable,
      startApplePaySession,
      isGooglePayAvailable,
      startGooglePaySession,
    } from 'https://esm.sh/@tagadapay/core-js@3';

    // 1. Discover what this merchant has enabled
    //    (your server fetches this with the merchant's Processing Key, then exposes
    //    the SAFE subset — never the publishable keys / processor IDs you don't trust on the client)
    const setup = await fetch('/api/payment-setup?merchant=merchant_42').then(r => r.json());
    const tokenizer = new Tokenizer({ environment: 'production' });

    // 2. Render Apple Pay button if native is wired
    if (setup.apple_pay?.enabled
        && setup.apple_pay.provider === 'apple_pay'
        && await isApplePayAvailable()) {
      const btn = document.createElement('apple-pay-button');
      btn.setAttribute('buttonstyle', 'black');
      btn.setAttribute('type', 'pay');
      btn.style.cursor = 'pointer';
      btn.onclick = () => {
        startApplePaySession(
          {
            basisTheoryApiKey: setup.apple_pay.metadata.basisTheoryApiKey,
            countryCode: 'FR',
            storeName: 'Acme',
          },
          { currency: 'EUR', totalAmountMinor: 4999 },
          {
            onSuccess: async (tagadaToken, contacts) => {
              await charge({
                tagadaToken,
                paymentMethod: 'apple_pay',
                customerData: {
                  email: contacts.shippingContact?.emailAddress,
                  firstName: contacts.shippingContact?.givenName,
                  lastName: contacts.shippingContact?.familyName,
                },
              });
            },
            onError: (err) => alert(err.message),
            onCancel: () => {},
          },
        );
      };
      document.getElementById('express-buttons').appendChild(btn);
    }

    // 3. Card form
    document.getElementById('card-form').addEventListener('submit', async (e) => {
      e.preventDefault();
      const tagadaToken = await tokenizer.tokenizeCard({
        cardNumber: document.getElementById('card-number').value,
        expiryDate: document.getElementById('card-expiry').value,
        cvc: document.getElementById('card-cvc').value,
      });
      await charge({
        tagadaToken,
        paymentMethod: 'card',
        customerData: { email: prompt('Email?') },
      });
    });

    async function charge({ tagadaToken, paymentMethod, customerData }) {
      const res = await fetch('/api/charge', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          merchantId: 'merchant_42',
          tagadaToken,
          paymentMethod,
          amount: 4999,
          currency: 'EUR',
          customerData,
          orderId: 'order_' + Date.now(),
        }),
      });

      const result = await res.json();

      if (result.status === 'captured') {
        window.location = `/thank-you?payment=${result.paymentId}`;
      } else if (result.status === 'threeds') {
        // Embed result.challenge.url in an iframe and resume after callback
        renderThreeDsChallenge(result.challenge);
      } else if (result.status === 'declined') {
        alert(`Declined: ${result.reason}`);
      }
    }
  </script>
</body>
</html>
```

--------------------------------

### Install TagadaPay CLI

Source: https://docs.tagada.io/developer-tools/cli/quick-start

Install the TagadaPay CLI globally using npm. Verify the installation by checking the CLI version.

```bash
npm install -g @tagadapay/plugin-cli
```

```bash
tgd --version
```

--------------------------------

### Create Preview Session Response Example

Source: https://docs.tagada.io/api-reference/funnels/create-a-preview-session

Example response returned upon successful creation of a preview session.

```json
sessionId: fs_123456789
funnelId: funnelv2_123
stepId: step_thankyou
token: eyJhbG...
customerId: cus_preview_123
```

--------------------------------

### Deploy Storefront to Netlify

Source: https://docs.tagada.io/developer-tools/headless-sdk/build-store-with-ai

Installs the Netlify CLI globally and deploys the production build.

```bash
npm install -g netlify-cli
netlify deploy --prod
```

--------------------------------

### Install Tagada SDK

Source: https://docs.tagada.io/developer-tools/node-sdk/quick-start

Install the package via npm.

```bash
npm install @tagadapay/node-sdk
```

--------------------------------

### Promote to Alias Example

Source: https://docs.tagada.io/api-reference/plugins/promote-plugin-deployment-to-alias

Example payload for promoting a deployment to an alias.

```json
{
  "deploymentId": "plugin_deployment_abc123",
  "alias": "checkout"
}
```

--------------------------------

### Complete Merchant Setup Script

Source: https://docs.tagada.io/developer-tools/node-sdk/merchant-quickstart

This script initializes the Tagada SDK and performs a full setup: creating a processor, defining a payment flow, setting up a store, creating a product with variants, building a checkout funnel, activating the funnel, and finally generating a checkout session URL. Ensure you replace 'your-api-key' with your actual API key.

```typescript
import Tagada from '@tagadapay/node-sdk';
const tagada = new Tagada('your-api-key');

// 1. Processor
const { processor } = await tagada.processors.create({
  processor: {
    name: 'Sandbox',
    type: 'sandbox',
    enabled: true,
    supportedCurrencies: ['USD'],
    baseCurrency: 'USD',
    options: { testMode: true },
  },
});

// 2. 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. Store
const store = await tagada.stores.create({
  name: 'My Store',
  baseCurrency: 'USD',
  presentmentCurrencies: ['USD', 'EUR'],
  chargeCurrencies: ['USD'],
  selectedPaymentFlowId: flow.id,
});

// 4. 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. Funnel
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
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. Checkout session — generate a link customers can open
const session = await tagada.checkout.createSession({
  storeId: store.id,
  items: [{ variantId, quantity: 1 }],
  currency: 'USD',
  checkoutUrl: funnelCheckoutUrl,
});

console.log('Checkout link:', session.redirectUrl);

```

--------------------------------

### Promote Preview Request Example

Source: https://docs.tagada.io/api-reference/plugins-v2/promote-preview-v2

Example payload for the promote preview operation, requiring deployment instance IDs and a store ID.

```yaml
previewDeploymentInstanceId: plugin_instance_preview123
productionDeploymentInstanceId: plugin_instance_prod123
storeId: store_abc123
```

--------------------------------

### Install TagadaPay Plugin SDK

Source: https://docs.tagada.io/developer-tools/sdk/standalone-guide

Install the required package via npm.

```bash
npm install @tagadapay/plugin-sdk
```

--------------------------------

### Full Workflow: Staging to Production

Source: https://docs.tagada.io/developer-tools/node-sdk/custom-checkout

A comprehensive workflow example demonstrating the steps from deploying a funnel to staging, registering and verifying a custom domain, promoting the funnel to production, and creating live checkout sessions.

```typescript
import Tagada from '@tagadapay/node-sdk';
const tagada = new Tagada('your-api-key');

// 1. Deploy + create funnel (see sections above)
// Your funnel is now live on *.cdn.tagadapay.com (staging)

// 2. Register and verify your domain
const { domain } = await tagada.domains.add({ domain: 'checkout.yourstore.com' });
// ... configure CNAME, wait for DNS ...
await tagada.domains.verify({ domainId: domain.id });

// 3. Promote — one call moves everything to production
await tagada.funnels.promote(funnel.id, {
  storeId: 'store_...',
  customDomain: 'checkout.yourstore.com',
});

// 4. Create checkout sessions pointing to the production URL
const session = await tagada.checkout.createSession({
  storeId: 'store_...',
  items: [{ variantId: 'variant_...', quantity: 1 }],
  currency: 'USD',
  checkoutUrl: 'https://checkout.yourstore.com/checkout',
});
console.log('Live checkout:', session.redirectUrl);
```
Tokens:
Raw