@paytra/sdk

TypeScript SDK used by PAYTRA frontends (Taka-Money-web- and other clients) to talk to paytraApi.

What It Provides

• Public auth flow (/api/v1/auth/*): login, OTP verify, OTP resend, refresh
• Tenant-scoped API modules:
  • organization
  • clients
  • payments
  • billing
  • ledger
• Centralized token storage and refresh handling
• Tenant-domain request routing after OTP verification

Project Structure

paytra-sdk/
  src/
    client.ts         # Core HTTP client + interceptors + tenant request helper
    auth.ts           # Public auth flow
    organization.ts   # Organization APIs
    clients.ts        # Client APIs
    payments.ts       # Payment APIs
    billing.ts        # Billing APIs
    ledger.ts         # Ledger APIs
    index.ts          # Public exports

Install & Build

cd paytra-sdk
npm install
npm run build

Build output is generated in dist/.

Use as Local Dependency

In frontend package.json:

{
  "dependencies": {
    "@paytra/sdk": "file:../paytra-sdk"
  }
}

Then in frontend project:

npm install

Environment

Create a local env file from .env.example:

cp .env.example .env

PaytraClient resolves API base URL in this order:

1. VITE_PAYTRA_API_URL
2. PAYTRA_API_URL
3. NEXT_PUBLIC_PAYTRA_API_URL
4. fallback: http://localhost:8000

Base API path remains fixed to /api/v1.

Auth Flow (Current)

1. auth.login({ workspace, email, password })
2. if requires_otp=true, call auth.verifyOTP({ email, otp })
3. SDK stores:
   • paytra_access_token
   • paytra_refresh_token
   • paytra_tenant_domain
4. Tenant module calls use getTenantRequest(...)

Notes:

• Backend resolves workspace from user.merchant; frontend still passes workspace for compatibility.
• Tenant calls require both token and tenant domain from OTP verification response.

Quick Usage

import { auth, clients, payments } from "@paytra/sdk";

auth.init();

const login = await auth.login({
  workspace: "",
  email: "[email protected]",
  password: "OwnerPass123!"
});

if (login.requires_otp) {
  await auth.verifyOTP({ email: "[email protected]", otp: "123456" });
}

const list = await clients.listClients({ page: 1, page_size: 20 });
const incoming = await payments.listPayments({ page: 1, page_size: 50 });

Common Dev Workflow

When SDK source changes:

cd paytra-sdk
npm run build

Then in frontend:

cd ../Taka-Money-web-
npm install
npm run dev

Troubleshooting

• No tenant domain set:
  • OTP verification was not completed or tenant domain was not stored
• 401 on tenant calls:
  • access token expired and refresh failed
  • sign in again
• Frontend still using old SDK code:
  • rebuild SDK and reinstall in frontend (npm install)

ignore useless line yet another useless line