TypeScript / Node.js SDK

# npm
npm install @superchatbd/sdk

# bun
bun add @superchatbd/sdk

# pnpm
pnpm add @superchatbd/sdk

import { Superchat, constructWebhookEvent } from "@superchatbd/sdk";

const superchat = new Superchat({
  apiKey: process.env.SUPERCHAT_API_KEY!, // sk_live_... or sk_test_...
});

// 1. Create a hosted checkout session and redirect the customer to checkoutUrl
const payment = await superchat.payments.create({
  amount: 750,
  currency: "BDT",
  success_url: "https://myshop.com/orders/success",
  cancel_url: "https://myshop.com/cart",
  customer: { name: "Karim Rahman", email: "[email protected]" },
  metadata: { orderId: "order_9921" },
});

console.log(payment.id, payment.checkoutUrl, payment.netAmount);

// 2. Verify every incoming webhook before trusting it
const event = constructWebhookEvent({
  payload: rawBody, // raw request body, exactly as received
  signatureHeader: request.headers.get("x-superchat-signature")!,
  secret: process.env.SUPERCHAT_WEBHOOK_SECRET!, // whsec_...
});

if (event.event === "payment.completed") {
  await fulfilOrder(event.data.metadata.orderId);
}

import { SuperchatAPIError, SuperchatConnectionError, SuperchatError } from "@superchatbd/sdk";

try {
  await superchat.payments.create({
    amount: 750,
    success_url: "https://myshop.com/orders/success",
    cancel_url: "https://myshop.com/cart",
  });
} catch (error) {
  if (error instanceof SuperchatAPIError) {
    console.error(error.statusCode, error.message, error.body); // 400, "…", { statusCode, message, error }
  } else if (error instanceof SuperchatConnectionError) {
    console.error(error.code); // "network_error" | "timeout" | "aborted"
  } else if (error instanceof SuperchatError) {
    console.error(error.code, error.message);
  }
}

import { constructWebhookEvent, SuperchatSignatureError } from "@superchatbd/sdk";

try {
  const event = constructWebhookEvent<{ id: string; metadata: Record<string, string> }>({
    payload: rawBody,
    signatureHeader: req.headers["x-superchat-signature"] as string,
    secret: process.env.SUPERCHAT_WEBHOOK_SECRET!,
  });

  // event: { id: "evt_...", event: "payment.completed", created_at: "...", data: {...} }
  if (event.event === "payment.completed") {
    await fulfilOrder(event.data.metadata.orderId);
  }
} catch (error) {
  if (error instanceof SuperchatSignatureError) {
    // error.code: "malformed_header" | "timestamp_outside_tolerance" | "signature_mismatch"
    return new Response("invalid signature", { status: 400 });
  }
  throw error;
}

import { verifyWebhookSignature } from "@superchatbd/sdk";

// Safe for middleware: never throws on untrusted input.
const isValid = verifyWebhookSignature({
  payload: rawBody, // string | Buffer | Uint8Array
  signatureHeader: req.headers["x-superchat-signature"] as string,
  secret: process.env.SUPERCHAT_WEBHOOK_SECRET!,
  toleranceInSeconds: 300, // default; 0 disables the replay check
});

if (!isValid) {
  return new Response("invalid signature", { status: 400 });
}

// The SDK generates an Idempotency-Key per call, so a retried request
// can never create a second charge.
await superchat.payments.create(paymentParams);

// Pass your own key to deduplicate across processes:
await superchat.payments.create(paymentParams, {
  idempotencyKey: `order_${order.id}`,
});

// Refunds accept a key too — without one they are never retried.
await superchat.payments.refund(paymentId, { reason: "Customer request" }, {
  idempotencyKey: `refund_${paymentId}`,
});