paytrack docs
SDKs & developer tools
Install the official JavaScript/TypeScript SDK, CLI and MCP server from npm, and the Python SDK from PyPI.
Choose your tool
The JavaScript/TypeScript SDK, the CLI and the MCP server are published on npm under @paytrack-ng. The Python SDK is on PyPI as paytrack.
- JavaScript & TypeScript: typed inputs, resource methods, retries and timeouts.
- Python: a dependency-free HTTP client foundation with pagination helpers.
- CLI: terminal commands over the JavaScript SDK.
- MCP: AI assistant tools over the same API, with gated writes.
JavaScript & TypeScript
Install the SDK from npm. Node.js 18 or later is required.
npm install @paytrack-ng/sdk
A read-only first request. Set PAYTRACK_API_KEY in your server or shell environment first.
import { PaytrackClient, PaytrackApiError } from "@paytrack-ng/sdk";
const apiKey = process.env.PAYTRACK_API_KEY;
if (!apiKey) throw new Error("PAYTRACK_API_KEY is required");
const paytrack = new PaytrackClient({
apiKey,
baseUrl: "https://paytrack.ng/api/v1",
timeoutMs: 15000,
retries: 2,
});
try {
const data = await paytrack.customers.list({ limit: 25, offset: 0 });
console.log(data); // { customers: [...], pagination: { limit, offset } }
} catch (error) {
if (error instanceof PaytrackApiError) {
console.error(error.status, error.code, error.requestId);
} else {
throw error;
}
}The SDK returns the HTTP response’s data object, not the whole success envelope. A customer creation returns a data object containing customer; a list contains customers and pagination. Do not assume the result is a bare customer or array.
Writes and idempotency
Write methods accept an optional trailing idempotencyKey. A manual payment record represents money already received outside Paytrack; it does not charge a customer.
const result = await paytrack.payments.record(
{ trackId: "trk_example", amount: 25000, method: "bank_transfer" },
{ idempotencyKey: "external-payment-example-1" },
);
console.log(result); // { payment: ... }Reuse the key only for retries of that same request. Transport failures may be retried with backoff; API business errors are surfaced as PaytrackApiError.
Python SDK
Python 3.9 or later, no runtime dependencies. Install it from PyPI:
pip install paytrack
import os
from paytrack import Paytrack
client = Paytrack(
api_key=os.environ["PAYTRACK_API_KEY"],
base_url="https://paytrack.ng/api/v1",
)
page = client.customers.list(limit=25, offset=0)
for customer in page.items:
print(customer["fullName"])
print(page.limit, page.offset, page.request_id)The generic Python resource methods forward your JSON field names unchanged. For example, the payment API expects trackId, not track_id.
result = client.payments.create(
{"trackId": "trk_example", "amount": 25000, "method": "bank_transfer"},
idempotency_key="external-payment-example-1",
)
print(result["payment"])Verify webhooks against the raw request body:
from paytrack import verify_webhook_signature ok = verify_webhook_signature(raw_body, headers["paytrack-signature"], secret)
CLI
The paytrack command builds on the JavaScript SDK. It supports account inspection, customer and payment records, report requests and webhook delivery history. See the CLI guide for credentials, JSON output and write behaviour.
npm install -g @paytrack-ng/cli paytrack --help paytrack account get --json paytrack customers list --limit 25 --json
MCP server
@paytrack-ng/mcp-server lets AI assistants such as Claude, Cursor and VS Code read your workspace through the public API. One server session uses one API key, so it sees one workspace. API scopes and release availability still apply; it never reaches the database directly. Add it to your MCP client config:
{
"mcpServers": {
"paytrack": {
"command": "npx",
"args": ["-y", "@paytrack-ng/mcp-server"],
"env": { "PAYTRACK_API_KEY": "ptrk_test_..." }
}
}
}Availability is enforced by the API
Client methods and CLI commands do not activate paused backend capabilities. In particular, automatic debits, scheduled collections and reminder delivery remain subject to release availability and workspace permissions. Keep keys on trusted servers and use scoped test keys for development.