paytrack docs
SDKs
Use the JavaScript/TypeScript SDK foundation for typed paytrack integrations.
JavaScript and TypeScript
The SDK lives in sdk/javascript and covers every v1 API resource (customers, tracks, payments, reminders, reports, ledger, webhooks, account, collection schedules, payment mandates, and collection attempts), with retries, timeouts, and idempotency-key support. It is not yet published to npm or any other registry — npm install @paytrack/sdk will not work today. See Connect to paytrack for current status across the SDK, CLI, and MCP server.
Initialization
import { PaytrackClient } from "@paytrack/sdk";
const paytrack = new PaytrackClient({
apiKey: process.env.PAYTRACK_API_KEY,
baseUrl: "https://paytrack.ng/api/v1",
timeoutMs: 15000,
retries: 2,
});Create customer
const customer = await paytrack.customers.create({
name: "ABC Furniture",
phone: "+2348012345678",
email: "finance@example.com",
});Create track
const track = await paytrack.tracks.create({
customerId: customer.id,
title: "Samsung TV installment",
amount: 420000,
currency: "NGN",
installments: 12,
});Record a payment
payments.record()logs a payment that already happened outside paytrack (e.g. a bank transfer you've confirmed) — it does not charge anyone or move money.
await paytrack.payments.record(
{ trackId: track.id, amount: 25000, method: "bank_transfer" },
{ idempotencyKey: "retry-safe-key-1" } // optional — safe to retry on network errors
);Fetch a report and handle errors
try {
const summary = await paytrack.reports.summary();
console.log(summary);
} catch (error) {
if (error instanceof PaytrackApiError) {
console.error(error.requestId, error.status, error.code, error.message);
}
}Retry behavior and test mode
The SDK retries transient failures with backoff, preserves request IDs, and never retries a business/validation error (a PaytrackApiError). Use ptrk_test_ keys while building and ptrk_live_ keys only after production review — the SDK, CLI, and MCP server all read the key's own prefix rather than needing a separate test/live flag.