@bhooai/nexus-payments 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @bhooai/nexus-payments
+
+Unified `PaymentProvider` interface across five gateways with per-provider
+webhook signature verification.
+
+## Providers
+
+| provider | status | notes |
+| --- | --- | --- |
+| Razorpay | **full** | REST orders + signature verify |
+| PayPal | **full** | Orders v2 |
+| PayU | happy-path | hash-based |
+| Skrill | happy-path | Quick Checkout |
+| Payoneer | happy-path | hosted flow |
+
+Razorpay + PayPal are fully implemented and tested. PayU/Skrill/Payoneer have
+happy-path + sandbox tests (documented seams — their Node SDKs are weak, so some
+flows use raw HTTP). See `docs/IMPROVEMENTS.md`.
+
+## Exports
+
+- `createPayments(config)` → `PaymentsService` with `createOrder/capture/refund/
+  getOrderStatus/verifyWebhook` and a `webhookRouter(handler)`.
+- Per-provider classes, `http` + `signature` helpers, typed errors.
+
+The browser-facing routes live in `apps/backend` (`registerPaymentRoutes`);
+webhooks mount separately at `config.payments.webhookPath`.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@bhooai/nexus-payments",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+/** Payment-domain error. `code` is machine-readable; `provider` names the gateway. */
+export class PaymentError extends Error {
+  readonly code: string;
+  readonly provider: string;
+  readonly status?: number;
+  readonly raw?: unknown;
+  constructor(message: string, opts: { code: string; provider: string; status?: number; raw?: unknown }) {
+    super(message);
+    this.name = 'PaymentError';
+    this.code = opts.code;
+    this.provider = opts.provider;
+    this.status = opts.status;
+    this.raw = opts.raw;
+  }
+}

package/src/http.ts

@@ -0,0 +1,53 @@
+import type { HttpTransport, HttpRequest, HttpResponse } from './types.js';
+import { PaymentError } from './errors.js';
+
+/**
+ * Default HTTP transport built on the global `fetch` (Node >= 18). Providers
+ * accept any `HttpTransport`, so tests inject a mock and never touch the network.
+ */
+export const fetchTransport: HttpTransport = async (req: HttpRequest): Promise<HttpResponse> => {
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.body,
+  });
+  const text = await res.text();
+  const headers: Record<string, string> = {};
+  res.headers.forEach((v, k) => {
+    headers[k] = v;
+  });
+  return { status: res.status, body: text, headers };
+};
+
+/** Run a JSON request through `transport`, parse JSON, and throw PaymentError on non-2xx. */
+export async function jsonRequest(
+  transport: HttpTransport,
+  provider: string,
+  req: HttpRequest,
+): Promise<any> {
+  const res = await transport(req);
+  const parsed = safeJson(res.body);
+  if (res.status < 200 || res.status >= 300) {
+    throw new PaymentError(`${provider} request failed: HTTP ${res.status}`, {
+      code: 'HTTP_ERROR',
+      provider,
+      status: res.status,
+      raw: parsed ?? res.body,
+    });
+  }
+  return parsed;
+}
+
+function safeJson(body: string): any {
+  if (!body) return undefined;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Basic-auth header value from `user:pass`. */
+export function basicAuth(user: string, pass: string): string {
+  return 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './http.js';
+export * from './signature.js';
+export * from './providers/RazorpayProvider.js';
+export * from './providers/PayPalProvider.js';
+export * from './providers/PayUProvider.js';
+export * from './providers/SkrillProvider.js';
+export * from './providers/PayoneerProvider.js';
+export * from './webhooks.js';
+
+import type { PaymentProvider, HttpTransport, ProviderConfig } from './types.js';
+import { fetchTransport } from './http.js';
+import { RazorpayProvider } from './providers/RazorpayProvider.js';
+import { PayPalProvider } from './providers/PayPalProvider.js';
+import { PayUProvider } from './providers/PayUProvider.js';
+import { SkrillProvider } from './providers/SkrillProvider.js';
+import { PayoneerProvider } from './providers/PayoneerProvider.js';
+import { WebhookRouter } from './webhooks.js';
+import type { WebhookEvent } from './types.js';
+
+export interface PaymentsOptions {
+  /** Override the HTTP transport (tests inject a mock; default uses fetch). */
+  transport?: HttpTransport;
+}
+
+export interface PaymentsService {
+  /** Enabled providers keyed by name (razorpay, paypal, payu, skrill, payoneer). */
+  providers: Map<string, PaymentProvider>;
+  /** Get a provider by name, or throw if not enabled. */
+  get(name: string): PaymentProvider;
+  /** Rebuild the enabled-provider map from (possibly updated) config in place,
+   *  so admin toggles/keys take effect without a restart. */
+  refresh(config: Parameters<typeof createPayments>[0]): void;
+  /** Build a webhook router for `POST <webhookPath>`. */
+  webhookRouter(onEvent: (event: WebhookEvent) => Promise<void> | void): WebhookRouter;
+}
+
+/**
+ * Build the payments service from a `payments` config section. A provider
+ * activates when `enabled: true` OR all of its credential keys are set — so a
+ * user who adds keys (via config or `NEXUS_PAYMENTS_*` env) without remembering
+ * the `enabled` flag still gets a working provider. Explicit `enabled: false`
+ * with keys is the only way to keep a configured provider off.
+ */
+export function createPayments(
+  config: {
+    razorpay?: ProviderConfig;
+    paypal?: ProviderConfig;
+    payu?: ProviderConfig;
+    skrill?: ProviderConfig;
+    payoneer?: ProviderConfig;
+  },
+  opts: PaymentsOptions = {},
+): PaymentsService {
+  const transport = opts.transport ?? fetchTransport;
+  const providers = new Map<string, PaymentProvider>();
+
+  const active = (cfg: ProviderConfig | undefined, keys: string[]): boolean => {
+    if (!cfg) return false;
+    const hasKeys = keys.every((k) => {
+      const v = (cfg as Record<string, unknown>)[k];
+      return typeof v === 'string' && v.length > 0;
+    });
+    if (!hasKeys) return false; // never instantiate without the required keys
+    // Keys present → provider works (matches "add keys and it activates"),
+    // unless explicitly disabled.
+    return cfg.enabled !== false;
+  };
+
+  const populate = (cfg: Parameters<typeof createPayments>[0]): void => {
+    providers.clear();
+    if (active(cfg.razorpay, ['keyId', 'keySecret'])) {
+      providers.set('razorpay', new RazorpayProvider(cfg.razorpay as any, transport));
+    }
+    if (active(cfg.paypal, ['clientId', 'clientSecret'])) {
+      providers.set('paypal', new PayPalProvider(cfg.paypal as any, transport));
+    }
+    if (active(cfg.payu, ['merchantKey', 'salt'])) {
+      providers.set('payu', new PayUProvider(cfg.payu as any, transport));
+    }
+    if (active(cfg.skrill, ['merchantEmail'])) {
+      providers.set('skrill', new SkrillProvider(cfg.skrill as any, transport));
+    }
+    if (active(cfg.payoneer, ['programId', 'apiKey'])) {
+      providers.set('payoneer', new PayoneerProvider(cfg.payoneer as any, transport));
+    }
+  };
+
+  populate(config);
+
+  return {
+    providers,
+    get(name: string): PaymentProvider {
+      const p = providers.get(name);
+      if (!p) throw new Error(`[nexus-payments] provider not enabled: ${name}`);
+      return p;
+    },
+    refresh(cfg) {
+      populate(cfg);
+    },
+    webhookRouter(onEvent) {
+      return new WebhookRouter(providers, onEvent);
+    },
+  };
+}

package/src/providers/PayPalProvider.ts

@@ -0,0 +1,192 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+  ConnectionTest,
+} from '../types.js';
+import { jsonRequest, basicAuth } from '../http.js';
+import { PaymentError } from '../errors.js';
+
+interface PayPalConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  clientId: string;
+  clientSecret: string;
+  /** Optional webhook id (used by the verify-webhook-signature API). */
+  webhookId?: string;
+}
+
+function baseUrl(sandbox: boolean): string {
+  return sandbox ? 'https://api-m.sandbox.paypal.com' : 'https://api-m.paypal.com';
+}
+
+function mapStatus(s: string): OrderStatus {
+  switch (s) {
+    case 'CREATED': return 'created';
+    case 'SAVED': case 'PAYER_ACTION_REQUIRED': return 'pending';
+    case 'APPROVED': return 'authorized';
+    case 'COMPLETED': return 'captured';
+    case 'VOIDED': return 'cancelled';
+    default: return 'pending';
+  }
+}
+
+/** Format a major-unit amount as PayPal's 2-decimal string. */
+function fmt(amount: number): string {
+  return amount.toFixed(2);
+}
+
+export class PayPalProvider implements PaymentProvider {
+  readonly name = 'paypal';
+  private readonly cfg: PayPalConfig;
+  private readonly transport: HttpTransport;
+  private token: { value: string; expiresAt: number } | null = null;
+
+  constructor(cfg: PayPalConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.clientId || !cfg.clientSecret) throw new PaymentError('paypal clientId/clientSecret required', { code: 'CONFIG', provider: 'paypal' });
+  }
+
+  private base(): string {
+    return baseUrl(this.cfg.sandbox);
+  }
+
+  /** OAuth2 client-credentials token with a 5-minute safety margin on expiry. */
+  private async tokenValue(): Promise<string> {
+    if (this.token && Date.now() < this.token.expiresAt - 300_000) return this.token.value;
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v1/oauth2/token`,
+      headers: { authorization: basicAuth(this.cfg.clientId, this.cfg.clientSecret), 'content-type': 'application/x-www-form-urlencoded' },
+      body: 'grant_type=client_credentials',
+    });
+    if (!res.access_token) throw new PaymentError('paypal token exchange failed', { code: 'AUTH', provider: 'paypal', raw: res });
+    this.token = { value: res.access_token, expiresAt: Date.now() + (res.expires_in ?? 3600) * 1000 };
+    return this.token.value;
+  }
+
+  private async authHeaders(): Promise<Record<string, string>> {
+    return { 'content-type': 'application/json', authorization: `Bearer ${await this.tokenValue()}` };
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const body = {
+      intent: 'CAPTURE',
+      purchase_units: [{
+        reference_id: input.reference,
+        amount: { currency_code: input.currency, value: fmt(input.amount) },
+        ...(input.description ? { description: input.description } : {}),
+      }],
+      ...(input.returnUrl || input.cancelUrl ? { application_context: { return_url: input.returnUrl, cancel_url: input.cancelUrl } } : {}),
+    };
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/checkout/orders`,
+      headers: await this.authHeaders(),
+      body: JSON.stringify(body),
+    });
+    const approve = (res.links ?? []).find((l: { rel: string; href: string }) => l.rel === 'approve');
+    return {
+      id: res.id,
+      reference: input.reference,
+      status: mapStatus(res.status),
+      amount: input.amount,
+      currency: input.currency,
+      paymentUrl: approve?.href,
+      raw: res,
+    };
+  }
+
+  async capture(input: CaptureInput): Promise<Order> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/checkout/orders/${input.orderId}/capture`,
+      headers: await this.authHeaders(),
+      body: '{}',
+    });
+    const unit = res.purchase_units?.[0];
+    const capture = unit?.payments?.captures?.[0];
+    return {
+      id: res.id,
+      reference: unit?.reference_id ?? '',
+      status: mapStatus(res.status),
+      amount: capture ? Number(capture.amount.value) : 0,
+      currency: capture?.amount?.currency_code ?? '',
+      paymentId: capture?.id,
+      raw: res,
+    };
+  }
+
+  async refund(input: RefundInput): Promise<RefundResult> {
+    const body = input.amount != null ? JSON.stringify({ amount: { value: fmt(input.amount), currency_code: 'USD' } }) : '{}';
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v2/payments/captures/${input.paymentId}/refund`,
+      headers: await this.authHeaders(),
+      body,
+    });
+    return { id: res.id, status: res.status, amount: res.amount ? Number(res.amount.value) : 0, raw: res };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'GET',
+      url: `${this.base()}/v2/checkout/orders/${orderId}`,
+      headers: await this.authHeaders(),
+    });
+    const unit = res.purchase_units?.[0];
+    return {
+      id: res.id,
+      reference: unit?.reference_id ?? '',
+      status: mapStatus(res.status),
+      amount: unit ? Number(unit.amount.value) : 0,
+      currency: unit?.amount?.currency_code ?? '',
+      raw: res,
+    };
+  }
+
+  /** Live probe: exchange client-credentials for an OAuth token (no order created). */
+  async testConnection(): Promise<ConnectionTest> {
+    await this.tokenValue();
+    return { ok: true, detail: `oauth2 authenticated (${this.cfg.sandbox ? 'sandbox' : 'live'})` };
+  }
+
+  /**
+   * PayPal webhook verification uses the /v1/notifications/verify-webhook-signature
+   * API (PayPal signs with a rotating certificate — local HMAC isn't possible).
+   * Requires `webhookId` configured.
+   */
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    if (!this.cfg.webhookId) return { verified: false, provider: this.name, data: 'no webhookId configured' };
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const body = JSON.stringify({
+      auth_algo: input.headers['paypal-auth-algo'] ?? input.headers['PAYPAL-AUTH-ALGO'],
+      cert_url: input.headers['paypal-cert-url'] ?? input.headers['PAYPAL-CERT-URL'],
+      transmission_id: input.headers['paypal-transmission-id'] ?? input.headers['PAYPAL-TRANSMISSION-ID'],
+      transmission_sig: input.headers['paypal-transmission-sig'] ?? input.headers['PAYPAL-TRANSMISSION-SIG'],
+      transmission_time: input.headers['paypal-transmission-time'] ?? input.headers['PAYPAL-TRANSMISSION-TIME'],
+      webhook_id: this.cfg.webhookId,
+      webhook_event: safeParse(raw),
+    });
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${this.base()}/v1/notifications/verify-webhook-signature`,
+      headers: await this.authHeaders(),
+      body,
+    });
+    const verified = res.verification_status === 'SUCCESS';
+    return { verified, event: safeParse(raw)?.event_type, data: safeParse(raw), provider: this.name };
+  }
+}
+
+function safeParse(s: string): any {
+  try { return JSON.parse(s); } catch { return undefined; }
+}

package/src/providers/PayUProvider.ts

@@ -0,0 +1,164 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+} from '../types.js';
+import { sha512Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+/**
+ * PayU India (happy-path). PayU uses a hash-based flow: the merchant computes a
+ * SHA-512 hash over the payment params + salt, POSTs to the hosted checkout, and
+ * verifies the response hash (the reverse sequence). No REST "create order";
+ * `createOrder` builds the params + hash and returns the checkout URL.
+ */
+interface PayUConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  merchantKey: string;
+  salt: string;
+}
+
+function checkoutUrl(sandbox: boolean): string {
+  return sandbox ? 'https://test.payu.in/_payment' : 'https://secure.payu.in/_payment';
+}
+
+/** Request hash = sha512(key|txnid|amount|productinfo|firstname|email|udf1..udf10|salt). */
+export function payuRequestHash(
+  key: string,
+  salt: string,
+  p: { txnid: string; amount: string; productinfo: string; firstname: string; email: string; udf: string[] },
+): string {
+  const fields = [key, p.txnid, p.amount, p.productinfo, p.firstname, p.email, ...p.udf, salt];
+  return sha512Hex(fields.join('|'));
+}
+
+/** Response hash = sha512(salt|status|udf10..udf1|email|firstname|productinfo|amount|txnid|key). */
+export function payuResponseHash(
+  key: string,
+  salt: string,
+  p: { status: string; txnid: string; amount: string; productinfo: string; firstname: string; email: string; udf: string[] },
+): string {
+  const reversedUdf = [...p.udf].reverse();
+  const fields = [salt, p.status, ...reversedUdf, p.email, p.firstname, p.productinfo, p.amount, p.txnid, key];
+  return sha512Hex(fields.join('|'));
+}
+
+function mapStatus(status: string): OrderStatus {
+  switch (status) {
+    case 'created': return 'created';
+    case 'pending': case 'in progress': return 'pending';
+    case 'captured': case 'success': return 'captured';
+    case 'failed': return 'failed';
+    case 'cancelled': return 'cancelled';
+    case 'refunded': return 'refunded';
+    default: return 'pending';
+  }
+}
+
+export class PayUProvider implements PaymentProvider {
+  readonly name = 'payu';
+  private readonly cfg: PayUConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: PayUConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.merchantKey || !cfg.salt) throw new PaymentError('payu merchantKey/salt required', { code: 'CONFIG', provider: 'payu' });
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const amount = input.amount.toFixed(2);
+    const firstname = input.customer?.name ?? 'Customer';
+    const email = input.customer?.email ?? '';
+    const productinfo = input.description ?? input.reference;
+    const udf = ['', '', '', '', '', '', '', '', '', '']; // udf1..udf10
+    const hash = payuRequestHash(this.cfg.merchantKey, this.cfg.salt, {
+      txnid: input.reference, amount, productinfo, firstname, email, udf,
+    });
+    const params = {
+      key: this.cfg.merchantKey,
+      txnid: input.reference,
+      amount,
+      productinfo,
+      firstname,
+      email,
+      udf1: '', udf2: '', udf3: '', udf4: '', udf5: '',
+      hash,
+      ...(input.returnUrl ? { surl: input.returnUrl, furl: input.returnUrl } : {}),
+    };
+    return {
+      id: input.reference,
+      reference: input.reference,
+      status: 'created',
+      amount: input.amount,
+      currency: input.currency,
+      // PayU expects a form POST to the checkout URL with `params` — return the
+      // endpoint as paymentUrl and the params in `raw` for the client to POST.
+      paymentUrl: checkoutUrl(this.cfg.sandbox),
+      raw: params,
+    };
+  }
+
+  /** PayU has no server-side capture; payments auto-capture on the hosted page. */
+  async capture(input: CaptureInput): Promise<Order> {
+    return this.getOrderStatus(input.orderId);
+  }
+
+  /** PayU refunds require the merchant panel / a separate API; v1 returns a stub. */
+  async refund(input: RefundInput): Promise<RefundResult> {
+    return { id: `refund-${input.paymentId}`, status: 'pending', amount: input.amount ?? 0, raw: { note: 'PayU refund via merchant panel (v1)' } };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    // Without a live REST credential, status is reconstructed from the webhook
+    // payload that updateOrder would have stored. v1 returns a placeholder.
+    return { id: orderId, reference: orderId, status: 'pending', amount: 0, currency: '', raw: { note: 'PayU status via webhook (v1)' } };
+  }
+
+  /**
+   * Verify a PayU webhook/redirect response. The body is form-encoded
+   * (key=value&...) with a `hash` field. We recompute the response hash and
+   * compare in constant time.
+   */
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const fields = parseForm(raw);
+    const providedHash = fields.hash;
+    if (!providedHash) return { verified: false, provider: this.name, data: 'no hash in payload' };
+    const udf = [fields.udf1, fields.udf2, fields.udf3, fields.udf4, fields.udf5, fields.udf6, fields.udf7, fields.udf8, fields.udf9, fields.udf10].map((v) => v ?? '');
+    const expected = payuResponseHash(this.cfg.merchantKey, this.cfg.salt, {
+      status: fields.status ?? '',
+      txnid: fields.txnid ?? '',
+      amount: fields.amount ?? '',
+      productinfo: fields.productinfo ?? '',
+      firstname: fields.firstname ?? '',
+      email: fields.email ?? '',
+      udf,
+    });
+    const verified = safeEqual(providedHash, expected);
+    return {
+      verified,
+      event: fields.status ? `payment.${fields.status}` : undefined,
+      data: fields,
+      provider: this.name,
+    };
+  }
+}
+
+function parseForm(body: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const pair of body.split('&')) {
+    if (!pair) continue;
+    const [k, ...rest] = pair.split('=');
+    out[decodeURIComponent(k!)] = decodeURIComponent(rest.join('='));
+  }
+  return out;
+}