@payment_hub/sdk

Typed TypeScript client + webhook verification for the PaymentHub API. Types are generated from PaymentHub's published OpenAPI spec, so requests and responses are fully type-checked.

Sandbox-only portfolio project.

Install

npm install @payment_hub/sdk

Quickstart

import { createClient } from "@payment_hub/sdk";

const paymenthub = createClient({ apiKey: process.env.PAYMENTHUB_API_KEY! });

// One-call sandbox bootstrap (test-mode keys only):
const demo = await paymenthub.seedSandbox();
// → { api_key, merchant_id, sample_payment_ids }

// Create a payment:
const payment = await paymenthub.createPayment({
  amount_minor: 1500,
  currency: "USD",
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
});
console.log(payment.checkout_url);

// Anything else, fully typed, via the raw client:
const { data } = await paymenthub.raw.GET("/v1/payments/{payment_id}", {
  params: { path: { payment_id: payment.id } },
});

createClient defaults to the hosted gateway; pass baseUrl to point elsewhere.

Webhook verification

Verify the raw request body server-side (don't re-serialize):

import { verifyWebhook } from "@payment_hub/sdk";

const ok = verifyWebhook({
  provider: "stripe", // or "paymob"
  payload: rawBody, // string | Buffer
  signature: req.headers["x-paymenthub-signature"],
  secret: process.env.WEBHOOK_SECRET!,
});

• Stripe-style (verifyStripeSignature): t=<unix>,v1=<hex> header; HMAC-SHA256 over ${t}.${body} with a replay tolerance (default 5 min).
• Paymob-style (verifyPaymobHmac): raw HMAC-SHA256 hex digest over the body.

All comparisons are constant-time.

Development

npm install
npm run generate   # regenerate src/schema.ts from openapi.json (the BE spec)
npm run typecheck
npm run test
npm run build

src/schema.ts is generated from the vendored openapi.json; CI fails if it drifts. Refresh the spec from the backend and re-run npm run generate when the API changes.

Releasing

release.yml publishes to npm on a v* tag (or a repository_dispatch from the backend). It regenerates types, runs the test suite, and completes a sandbox payment against prod before publishing. Required repo secrets: NPM_TOKEN, PAYMENTHUB_TEST_KEY.