TypeScript SDK

Install

npm install @qashx/sdk
# or
bun add @qashx/sdk

The SDK ships ESM and CJS builds. TypeScript types are generated from the OpenAPI spec.

Initialise the client

import { QashX } from "@qashx/sdk";

const client = new QashX({
  apiKey: process.env.QASHX_API_KEY!,
  env: "sandbox",            // "sandbox" | "live"
  timeoutMs: 15000,          // default 30s
  maxRetries: 3,             // exponential backoff on 5xx / 429
});

Payments

Create

const payment = await client.payments.create({
  amount: 1500,
  currency: "EUR",
  capability: "card_payment",
  customer: { email: "buyer@example.com" },
  metadata: { orderId: "ord_123" },
}, { idempotencyKey: crypto.randomUUID() });

Retrieve, list, refund, cancel

await client.payments.retrieve("pay_...");
await client.payments.list({ limit: 20 });
await client.payments.refund("pay_...", { amount: 500 });
await client.payments.cancel("pay_...");

Webhooks

import { verifyWebhook } from "@qashx/sdk/webhooks";

app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  const event = verifyWebhook({
    payload: req.body,
    signature: req.headers["x-qashx-signature"] as string,
    secret: process.env.QASHX_WEBHOOK_SECRET!,
  });
  // event.type, event.data
  res.sendStatus(200);
});

Errors & retries

import { QashXError } from "@qashx/sdk";

try {
  await client.payments.create({ /* … */ });
} catch (err) {
  if (err instanceof QashXError) {
    console.log(err.type, err.code, err.requestId);
    if (err.type === "rate_limit_error") { /* honour Retry-After */ }
  } else { throw err; }
}

See the Errors reference for the complete taxonomy.

Types

Every response is typed from the OpenAPI spec. Import the shapes you need:

import type { Payment, PaymentStatus, Refund } from "@qashx/sdk";

Changelog

SDK releases follow the API changelog: /docs/changelog.html. Breaking SDK changes only ship in major versions.