TagadaPay API

The TagadaPay API is a REST API that lets you process payments, manage subscriptions, handle customers, deploy plugins, and orchestrate checkout funnels — all programmatically.

Base URL

https://app.tagadapay.com/api/public/v1

A sandbox environment is available for testing:

https://app.tagadapay.dev/api/public/v1

Authentication

Authenticate every request with a Bearer token in the Authorization header. Get your API key from the TagadaPay Dashboard.

curl https://app.tagadapay.com/api/public/v1/auth/test \
  -H "Authorization: Bearer your-api-key"

Keep your API keys secure. Never expose them in client-side code, public repositories, or logs.

Authentication troubleshooting

A missing, empty, or malformed Authorization header returns 401 with a message explaining what was wrong:

{
  "code": "NOT_AUTHORIZED",
  "message": "Missing or invalid API key. No `Authorization` header (or an empty Bearer token) was provided. Authenticate by sending your API key as a Bearer token: `Authorization: Bearer <your-api-key>`. ..."
}

Common causes:

Empty shell variable — Authorization: Bearer $KEY with $KEY unset sends an empty token. Verify with echo ${#KEY} before calling.
Wrong header — the key must be in Authorization: Bearer <key>, not in a custom header.
Wrong key type — public API endpoints accept dashboard API keys (Settings → API Keys) and TPA-restricted tp_sk_… partner keys.

Older API versions surfaced this situation as a confusing 500 mentioning Clerk: auth() was called but Clerk can't detect usage of clerkMiddleware(). If you see that error, it means the same thing: your API key did not reach the server — fix the Authorization header.

Request format

All requests must use HTTPS
Set Content-Type: application/json for POST/PUT requests
All responses return JSON

curl -X POST https://app.tagadapay.com/api/public/v1/payments \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"page": 1, "pageSize": 20}}'

Rate limits

Plan	Requests/min	Burst
Standard	100	150
Premium	500	750

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Error codes

Code	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions
404	Resource not found
409	Conflict with another request
429	Rate limited
500	Server error

Error responses follow this structure:

{
  "code": "ERROR",
  "message": "Human-readable error description",
  "data": {}
}

Pagination

List endpoints support pagination via request body parameters:

Offset pagination
Simple pagination

Used by payments, orders, customers, and block rules.

{
  "pagination": {
    "page": 1,
    "pageSize": 20
  },
  "sortBy": {
    "field": "createdAt",
    "direction": "desc"
  }
}

Used by subscriptions.

{
  "page": 1,
  "per_page": 20,
  "sort": "subscriptions.createdAt",
  "sort_order": "desc"
}

Filtering

Most list endpoints accept a filters object. Common patterns:

{
  "filters": {
    "status": ["active", "trialing"],
    "currency": ["USD", "EUR"],
    "date": {
      "condition": "is-after-date",
      "value": ["2024-01-01"]
    },
    "email": {
      "condition": "contains",
      "value": "john@"
    }
  }
}

Date filter conditions: is-equal-date, is-between-date, is-after-date, is-before-date.

Webhooks

Register webhook endpoints to receive real-time event notifications for payments, orders, subscriptions, and more. See the Webhooks API section.

SDKs

Node.js SDK

Server-side SDK for Node.js / TypeScript

Plugin SDK

Build custom checkout plugins with React

Plugin CLI

Deploy and manage plugins from the command line

Need help?

Email: api-support@tagadapay.com
Dashboard: app.tagadapay.com

IAM Overview

​TagadaPay API

​Base URL

​Authentication

​Authentication troubleshooting

​Request format

​Rate limits

​Error codes

​Pagination

​Filtering

​Webhooks

​SDKs

Node.js SDK

Plugin SDK

Plugin CLI

​Need help?

TagadaPay API

Base URL

Authentication

Authentication troubleshooting

Request format

Rate limits

Error codes

Pagination

Filtering

Webhooks

SDKs

Need help?