@kuvarpay/sdk 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# KuvarPay Server SDK
+
+Backend-focused SDK for creating and verifying checkout sessions, subscription sessions, invoices, and transactions using your Business SECRET API key.
+
+Works with Node 18+ (global `fetch`) or any environment where you can supply a `fetch` implementation. Also includes quick PHP cURL examples.
+
+## Installation
+
+This repository includes the SDK source files. You can copy `server-sdk/index.js` (CommonJS) or `server-sdk/index.mjs` (ESM) into your backend project, or import them via your build tooling.
+
+> Requirements:
+> - Business ID
+> - SECRET API Key (server-only)
+> - Payment API Base URL (e.g., `https://pay.kuvarpay.com` or your payment host)
+
+## Node (CommonJS) Usage
+
+```js
+// index.js (Node 18+)
+const { KuvarPayServer } = require('./server-sdk/index.js');
+
+const kv = new KuvarPayServer({
+  baseUrl: process.env.PAYMENT_API_BASE_URL, // e.g., https://pay.kuvarpay.com
+  businessId: process.env.KUVARPAY_BUSINESS_ID,
+  secretApiKey: process.env.KUVARPAY_SECRET_API_KEY,
+});
+
+async function verify(sessionId) {
+  const result = await kv.verifyPayment(sessionId);
+  console.log('Verified?', result.verified, 'status:', result.status);
+}
+
+async function session(sessionId) {
+  const s = await kv.getSessionStatus(sessionId);
+  console.log('Session:', s);
+}
+
+async function txn(transactionId) {
+  const t = await kv.getTransactionStatus(transactionId);
+  console.log('Transaction:', t);
+}
+```
+
+## Node (ESM) Usage
+
+```js
+// index.mjs (Node 18+)
+import { KuvarPayServer } from './server-sdk/index.mjs';
+
+const kv = new KuvarPayServer({
+  baseUrl: process.env.PAYMENT_API_BASE_URL,
+  businessId: process.env.KUVARPAY_BUSINESS_ID,
+  secretApiKey: process.env.KUVARPAY_SECRET_API_KEY,
+});
+
+const result = await kv.verifyPayment('sess_123');
+console.log(result);
+```
+
+### Node < 18
+
+Provide your own `fetchImpl` (e.g., from `node-fetch`) when constructing:
+
+```js
+const fetch = (...args) => import('node-fetch').then(mod => mod.default(...args));
+const kv = new KuvarPayServer({ baseUrl, businessId, secretApiKey, fetchImpl: fetch });
+```
+
+## PHP cURL Examples
+
+Replace `PAYMENT_API_BASE_URL`, `BUSINESS_ID`, and `SECRET_API_KEY` with your values.
+
+### Verify Payment (Checkout Session)
+
+```php
+$base = getenv('PAYMENT_API_BASE_URL');
+$businessId = getenv('KUVARPAY_BUSINESS_ID');
+$secret = getenv('KUVARPAY_SECRET_API_KEY');
+$sessionId = 'sess_123';
+
+$ch = curl_init("$base/api/v1/checkout-sessions/" . urlencode($sessionId));
+curl_setopt($ch, CURLOPT_HTTPHEADER, [
+  "Accept: application/json",
+  "X-API-Key: $secret",
+  "X-Business-ID: $businessId"
+]);
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+$resp = curl_exec($ch);
+$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+curl_close($ch);
+
+if ($statusCode >= 200 && $statusCode < 300) {
+  $data = json_decode($resp, true);
+  $status = $data['status'] ?? ($data['data']['status'] ?? null);
+  $verified = ($status === 'COMPLETED');
+  // handle $verified
+} else {
+  // handle error
+}
+```
+
+### Transaction Status
+
+```php
+$transactionId = 'tx_123';
+$ch = curl_init("$base/api/v1/transactions/" . urlencode($transactionId));
+curl_setopt($ch, CURLOPT_HTTPHEADER, [
+  "Accept: application/json",
+  "X-API-Key: $secret",
+  "X-Business-ID: $businessId"
+]);
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+$resp = curl_exec($ch);
+$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+curl_close($ch);
+
+if ($statusCode >= 200 && $statusCode < 300) {
+  $data = json_decode($resp, true);
+  $status = $data['status'] ?? null;
+  // handle $status
+} else {
+  // handle error
+}
+```
+
+## API Reference
+
+Payments:
+- `createCheckoutSession(data)` → `{ sessionId, authToken?, approvalUrl?, raw }`
+- `getSessionStatus(sessionId)` → `{ sessionId, status, transactionId?, raw }`
+- `getTransactionStatus(transactionId)` → `{ transactionId, status, raw }`
+- `verifyPayment(sessionId)` → `{ verified: boolean, status, sessionId, transactionId?, raw }`
+
+Subscriptions:
+- `createSubscriptionCheckoutSession(data)` → `{ sessionId, approvalUrl?, raw }`
+- `getSubscriptionCheckoutSession(id)` → full session details
+- `confirmSubscriptionCheckoutSession(id, body?)` → confirmation response
+- `getSubscription(subscriptionId)` → full subscription details
+- `cancelSubscription(subscriptionId, body?)` → cancellation response
+- `createMeteredInvoice(subscriptionId, invoiceData)` → invoice response
+- `createSubscriptionInvoice(subscriptionId, invoiceData)` → alias to metered invoice
+- `scheduleSubscriptionInvoice(subscriptionId, invoiceData)` → enforces `chargeSchedule: 'SCHEDULED'`
+- `createRenewalCheckoutSession(body)` → renewal checkout creation
+- `renewSubscription(subscriptionId, body?)` → direct renew trigger
+
+Relay Authorization (metered):
+- `createRelayAuthorization(body)`
+- `getRelayAuthorizationStatus(body)`
+- `revokeRelayAuthorization(body)` (supports legacy path via `{ useLegacyPath: true }`)
+
+Notes:
+- Status values commonly include `PENDING`, `ARMED`, `PROCESSING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, etc.
+- `verifyPayment` returns `verified = true` when `status === 'COMPLETED'`.
+
+## Security
+
+- Always keep your SECRET API key in server-side environment variables. Never expose it to the browser.
+- Use HTTPS for all API calls.
+
+## Parity with Client SDK
+
+The Server SDK provides server-side equivalents of the Client SDK’s network operations (creating sessions, fetching statuses, managing subscriptions, and invoices). It does not implement browser UI features like `openPayment(...)` / `openSubscription(...)` modals, postMessage callbacks, or iframe overlays. Use the Client SDK in the browser for UI, and the Server SDK on your backend for secure API operations.

package/index.d.ts

@@ -0,0 +1,134 @@
+export interface KuvarPayServerConfig {
+  baseUrl?: string;
+  businessId?: string;
+  secretApiKey?: string;
+  timeoutMs?: number;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+
+export interface SessionStatusResult {
+  sessionId: string;
+  status?: string;
+  transactionId: string | null;
+  metadata?: Record<string, any>;
+  raw: any;
+}
+
+export interface TransactionStatusResult {
+  transactionId: string;
+  status?: string;
+  metadata?: Record<string, any>;
+  raw: any;
+}
+
+export interface VerifyPaymentResult {
+  verified: boolean;
+  status?: string;
+  sessionId: string;
+  transactionId: string | null;
+  metadata?: Record<string, any>;
+  raw: any;
+}
+
+export class KuvarPayServer {
+  constructor(config?: KuvarPayServerConfig);
+  getSessionStatus(sessionId: string): Promise<SessionStatusResult>;
+  getTransactionStatus(transactionId: string): Promise<TransactionStatusResult>;
+  getTransactionStatusByReference(reference: string): Promise<any>;
+  verifyPayment(sessionId: string): Promise<VerifyPaymentResult>;
+  verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+
+  // Payments
+  getCurrencies(params?: Record<string, any>): Promise<any>;
+  calculatePayment(data: { fromCurrency: string; fromNetwork: string; toCurrency: string; toAmount: number }): Promise<any>;
+  createCheckoutSession(checkoutSessionData: {
+    amount: number;
+    currency: string;
+    description?: string;
+    redirectUrl?: string;
+    callbackUrl?: string;
+    customerEmail?: string;
+    customerName?: string;
+    expiresIn?: number;
+    subaccount?: string;
+    split_code?: string;
+    metadata?: Record<string, any>;
+    [key: string]: any;
+  }): Promise<{ sessionId: string; authToken?: string; approvalUrl?: string; raw: any }>;
+
+  createTransaction(transactionData: {
+    amount: number;
+    currency: string;
+    fromCurrency: string;
+    fromNetwork: string;
+    toCurrency: string;
+    subaccountCode?: string;
+    splitCode?: string;
+    description?: string;
+    callbackUrl?: string;
+    metadata?: Record<string, any>;
+    [key: string]: any;
+  }): Promise<any>;
+
+  listTransactions(params?: {
+    page?: number;
+    perPage?: number;
+    status?: string;
+    fromDate?: string;
+    toDate?: string;
+  }): Promise<any>;
+
+  refundTransaction(transactionId: string, data?: { amount?: number; reason?: string }): Promise<any>;
+  getExpiredTransactions(): Promise<any>;
+  getOptimalTransferFee(amount: number, currency?: string): Promise<any>;
+  sendInvoiceEmail(sessionId: string): Promise<any>;
+
+  // Subaccounts
+  createSubaccount(subaccountData: Record<string, any>): Promise<any>;
+  listSubaccounts(params?: { page?: number; perPage?: number }): Promise<any>;
+  getSubaccount(code: string): Promise<any>;
+  updateSubaccount(code: string, subaccountData: Record<string, any>): Promise<any>;
+  deleteSubaccount(code: string): Promise<any>;
+
+  // Split Groups
+  createSplitGroup(splitGroupData: Record<string, any>): Promise<any>;
+  listSplitGroups(): Promise<any>;
+  getSplitGroup(code: string): Promise<any>;
+  updateSplitGroup(code: string, splitGroupData: Record<string, any>): Promise<any>;
+  deleteSplitGroup(code: string): Promise<any>;
+
+
+  // Subscriptions
+  createSubscriptionCheckoutSession(subscriptionData: Record<string, any>): Promise<{ sessionId: string; approvalUrl?: string; raw: any }>;
+  getSubscriptionCheckoutSession(id: string): Promise<any>;
+  confirmSubscriptionCheckoutSession(id: string, body?: Record<string, any>): Promise<any>;
+
+  // Invoices
+  createMeteredInvoice(subscriptionId: string, invoiceData: Record<string, any>): Promise<any>;
+  createSubscriptionInvoice(subscriptionId: string, invoiceData: Record<string, any>): Promise<any>;
+  scheduleSubscriptionInvoice(subscriptionId: string, invoiceData: Record<string, any>): Promise<any>;
+
+  // Subscription details & lifecycle
+  getSubscription(subscriptionId: string): Promise<any>;
+  cancelSubscription(subscriptionId: string, body?: Record<string, any>): Promise<any>;
+
+  // Relay Authorization
+  createRelayAuthorization(body: Record<string, any>): Promise<any>;
+  getRelayAuthorizationStatus(body: Record<string, any>): Promise<any>;
+  revokeRelayAuthorization(body: Record<string, any>): Promise<any>;
+
+  // Renewal
+  createRenewalCheckoutSession(body: Record<string, any>): Promise<any>;
+  renewSubscription(subscriptionId: string, body?: Record<string, any>): Promise<any>;
+
+  // Banks
+  getBanks(params?: { currency?: string; type?: 'bank' | 'mobile_money'; country?: string }): Promise<any>;
+  resolveBankAccount(data: { bank_code: string; account_number: string; country_code?: string }): Promise<any>;
+
+  // Sandbox
+  startSandboxSimulator(): Promise<any>;
+  stopSandboxSimulator(): Promise<any>;
+  getSandboxSimulatorStatus(): Promise<any>;
+}
+
+export default KuvarPayServer;

package/index.js

@@ -0,0 +1,494 @@
+'use strict';
+
+/**
+ * KuvarPay Server SDK (CommonJS)
+ *
+ * For backend/server usage only. Requires a Business ID and SECRET API key.
+ * Works with Node 18+ (global fetch). If using older Node, pass a custom fetch
+ * implementation in the constructor (e.g., node-fetch) via { fetchImpl }.
+ */
+
+const crypto = require('crypto');
+
+const DEFAULT_BASE = (process.env.PAYMENT_API_BASE_URL
+  || process.env.PAYMENT_SERVER_URL
+  || process.env.NEXT_PUBLIC_PAYMENT_API_BASE_URL
+  || 'http://localhost:3002').replace(/\/+$/, '');
+
+class KuvarPayServer {
+  /**
+   * @param {Object} config
+   * @param {string} [config.baseUrl] - Payment API Base URL (e.g., https://pay.kuvarpay.com or https://api.yourpaymenthost.com)
+   * @param {string} [config.businessId] - Business ID
+   * @param {string} [config.secretApiKey] - Secret API key for server authentication
+   * @param {number} [config.timeoutMs] - Request timeout in ms (default 60000)
+   * @param {Function} [config.fetchImpl] - Optional fetch implementation for Node < 18
+   */
+  constructor({ baseUrl, businessId, secretApiKey, timeoutMs, fetchImpl } = {}) {
+    this.baseUrl = (baseUrl || DEFAULT_BASE).replace(/\/+$/, '');
+    this.businessId = businessId || process.env.KUVARPAY_BUSINESS_ID;
+    this.secretApiKey = secretApiKey || process.env.KUVARPAY_SECRET_API_KEY || process.env.PAYMENT_SECRET_API_KEY;
+    this.timeoutMs = timeoutMs || 60000;
+    this.fetchImpl = fetchImpl || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
+
+    if (!this.secretApiKey) throw new Error('secretApiKey is required');
+    if (!this.businessId) throw new Error('businessId is required');
+    if (!this.fetchImpl) throw new Error('A fetch implementation is required (Node 18+ or provide fetchImpl)');
+  }
+
+  _headers(extra = {}) {
+    return Object.assign({
+      'Accept': 'application/json',
+      'Authorization': this.secretApiKey,
+      'X-API-Key': this.secretApiKey,
+      'X-Business-ID': this.businessId,
+    }, extra);
+  }
+
+  _buildUrl(path) {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${this.baseUrl}${normalizedPath}`;
+  }
+
+  async _request(method, path, body, extraHeaders = {}) {
+    const url = this._buildUrl(path);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: this._headers(Object.assign({
+          'Content-Type': 'application/json',
+        }, extraHeaders)),
+        body: body != null ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      const text = await res.text();
+      let json;
+      try { json = text ? JSON.parse(text) : null; } catch (e) { json = null; }
+      if (!res.ok) {
+        const msg = (json && (json.error || json.message)) || `HTTP ${res.status}`;
+        const err = new Error(msg);
+        err.status = res.status;
+        err.body = json || text;
+        throw err;
+      }
+      return json;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      throw err;
+    }
+  }
+
+  async _get(path) {
+    return this._request('GET', path);
+  }
+
+  async _post(path, body, extraHeaders = {}) {
+    return this._request('POST', path, body, extraHeaders);
+  }
+
+  /**
+   * Fetch checkout session status by sessionId
+   * GET {Payment API Base}/api/v1/checkout-sessions/{sessionId}
+   * @param {string} sessionId
+   * @returns {Promise<{ sessionId: string, status: string | undefined, transactionId: string | null, raw: any }>}
+   */
+  /**
+   * Signature Verification for Webhooks
+   * @param {string|Buffer} payload - Raw request body
+   * @param {string} signature - Value from X-KuvarPay-Signature header
+   * @param {string} secret - Your Webhook Secret from the dashboard
+   */
+  verifyWebhookSignature(payload, signature, secret) {
+    if (!signature || !secret) return false;
+    const hmac = crypto.createHmac('sha256', secret);
+    const digest = hmac.update(payload).digest('hex');
+    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
+  }
+
+  async getSessionStatus(sessionId) {
+    if (!sessionId || typeof sessionId !== 'string') {
+      throw new Error('sessionId is required');
+    }
+    const data = await this._get(`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}`);
+    const status = data?.status || data?.checkoutSession?.status || data?.data?.status;
+    const transactionId = data?.transactionId || data?.data?.transactionId || null;
+    return {
+      sessionId: data?.id || data?.sessionId || sessionId,
+      status,
+      transactionId,
+      metadata: data?.metadata || data?.checkoutSession?.metadata || data?.data?.metadata || null,
+      raw: data,
+    };
+  }
+
+  /**
+   * Fetch transaction status by transactionId
+   * GET {Payment API Base}/api/v1/transactions/{transactionId}
+   * @param {string} transactionId
+   * @returns {Promise<{ transactionId: string, status: string | undefined, raw: any }>}
+   */
+  async getTransactionStatus(transactionId) {
+    if (!transactionId || typeof transactionId !== 'string') {
+      throw new Error('transactionId is required');
+    }
+    const data = await this._get(`/api/v1/transactions/${encodeURIComponent(transactionId)}`);
+    return {
+      transactionId: data?.id || transactionId,
+      status: data?.status,
+      metadata: data?.metadata || data?.data?.metadata || null,
+      raw: data,
+    };
+  }
+
+  /**
+   * Get transaction status by merchant reference
+   * GET /api/v1/transactions/status/{reference}
+   */
+  async getTransactionStatusByReference(reference) {
+    if (!reference) throw new Error('reference is required');
+    return this._get(`/api/v1/transactions/status/${encodeURIComponent(reference)}`);
+  }
+
+  /**
+   * List all transactions
+   * @param {Object} params - { page, perPage, status, fromDate, toDate } 
+   */
+  async listTransactions(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/transactions?${query}` : '/api/v1/transactions';
+    return this._get(path);
+  }
+
+  /**
+   * Refund a transaction
+   * @param {string} transactionId 
+   * @param {Object} data - { amount?, reason? }
+   */
+  async refundTransaction(transactionId, data = {}) {
+    return this._post(`/api/v1/transactions/${encodeURIComponent(transactionId)}/refund`, data);
+  }
+
+  /**
+   * Get expired transactions
+   */
+  async getExpiredTransactions() {
+    return this._get('/api/v1/transactions/expired');
+  }
+
+  /**
+   * Calculate fees
+   */
+  async getOptimalTransferFee(amount, currency = 'NGN') {
+    return this._get(`/api/v1/optimal-transfer-fee?amount=${amount}&currency=${currency}`);
+  }
+
+  /**
+   * Calculate required crypto payment amount
+   * POST /api/v1/transactions/calculate-payment
+   * @param {Object} data - { fromCurrency, fromNetwork, toCurrency, toAmount }
+   */
+  async calculatePayment(data) {
+    return this._post('/api/v1/transactions/calculate-payment', data);
+  }
+
+  /**
+   * Convenience wrapper to verify a payment session reached a final successful state
+   * @param {string} sessionId
+   * @returns {Promise<{ verified: boolean, status: string | undefined, sessionId: string, transactionId: string | null, raw: any }>}
+   */
+  async verifyPayment(sessionId) {
+    const s = await this.getSessionStatus(sessionId);
+    const verified = s.status === 'COMPLETED';
+    return {
+      verified,
+      status: s.status,
+      sessionId: s.sessionId,
+      transactionId: s.transactionId,
+      metadata: s.metadata,
+      raw: s.raw,
+    };
+  }
+
+  /**
+   * Create a one-time checkout session
+   * POST {Payment API Base}/api/v1/checkout-sessions
+   * @param {Object} checkoutSessionData - { amount, currency, description?, redirectUrl?, callbackUrl?, customerEmail?, customerName?, expiresIn?, metadata? }
+   * @returns {Promise<{ sessionId: string, authToken?: string, approvalUrl?: string, raw: any }>} // approvalUrl may be present when using redirect flows
+   */
+  async createCheckoutSession(checkoutSessionData) {
+    const payload = Object.assign({}, checkoutSessionData, {
+      businessId: checkoutSessionData.businessId || this.businessId,
+    });
+    // payload can include 'subaccount' (string) or 'split_code' (string)
+    // Guide says /api/v1/checkout-sessions
+    const data = await this._post('/api/v1/checkout-sessions', payload);
+    return {
+      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.data?.sessionId,
+      authToken: data?.authToken || data?.data?.authToken,
+      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url || data?.data?.approval_url,
+      raw: data,
+    };
+  }
+
+  /**
+   * Create a manual transaction (SDK / Server-to-Server)
+   * POST {Payment API Base}/api/v1/transactions/create
+   * @param {Object} transactionData - { amount, currency, fromCurrency, fromNetwork, toCurrency, subaccountCode?, splitCode?, description?, callbackUrl?, metadata? }
+   * @returns {Promise<any>}
+   */
+  async getCurrencies(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/currencies?${query}` : '/api/v1/currencies';
+    return this._get(path);
+  }
+
+  async createTransaction(transactionData) {
+    const payload = Object.assign({}, transactionData, {
+      businessId: transactionData.businessId || this.businessId,
+    });
+    return this._post('/api/v1/transactions', payload);
+  }
+
+  /**
+   * Email an invoice to a customer
+   */
+  async sendInvoiceEmail(sessionId) {
+    return this._post(`/api/v1/invoices/${encodeURIComponent(sessionId)}/send-email`, {});
+  }
+
+  // --- Subaccount Management ---
+
+  /**
+   * Create a new subaccount
+   * @param {Object} subaccountData - { business_name, percentage_charge, ... }
+   */
+  async createSubaccount(subaccountData) {
+    return this._post('/api/v1/subaccounts', subaccountData);
+  }
+
+  /**
+   * List all subaccounts
+   * @param {Object} [params] - { page, perPage }
+   */
+  async listSubaccounts(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/subaccounts?${query}` : '/api/v1/subaccounts';
+    return this._get(path);
+  }
+
+  /**
+   * Get subaccount details
+   * @param {string} code - SUB_xxx
+   */
+  async getSubaccount(code) {
+    return this._get(`/api/v1/subaccounts/${encodeURIComponent(code)}`);
+  }
+
+  /**
+   * Update subaccount
+   */
+  async updateSubaccount(code, subaccountData) {
+    return this._request('PATCH', `/api/v1/subaccounts/${encodeURIComponent(code)}`, subaccountData);
+  }
+
+  /**
+   * Delete subaccount (soft delete)
+   */
+  async deleteSubaccount(code) {
+    return this._request('DELETE', `/api/v1/subaccounts/${encodeURIComponent(code)}`);
+  }
+
+  // --- Split Group Management ---
+
+  /**
+   * Create a new split group
+   * @param {Object} splitGroupData - { name, bearer_type, subaccounts: [{ subaccount, share }] }
+   */
+  async createSplitGroup(splitGroupData) {
+    return this._post('/api/v1/split', splitGroupData);
+  }
+
+  /**
+   * List all split groups
+   */
+  async listSplitGroups() {
+    return this._get('/api/v1/split');
+  }
+
+  /**
+   * Get split group details
+   * @param {string} code - SPL_xxx
+   */
+  async getSplitGroup(code) {
+    return this._get(`/api/v1/split/${encodeURIComponent(code)}`);
+  }
+
+  /**
+   * Update split group
+   */
+  async updateSplitGroup(code, splitGroupData) {
+    return this._request('PATCH', `/api/v1/split/${encodeURIComponent(code)}`, splitGroupData);
+  }
+
+  /**
+   * Delete split group
+   */
+  async deleteSplitGroup(code) {
+    return this._request('DELETE', `/api/v1/split/${encodeURIComponent(code)}`);
+  }
+
+
+  /**
+   * Create a subscription checkout session (Metered or Fixed, depending on your Payment API config)
+   * POST {Payment API Base}/api/v1/subscriptions/checkout-sessions
+   * @param {Object} subscriptionData - { billingMode?, customer?, expectedUsage?, strategy?, customMultiplier?, metadata?, businessId? }
+   * @returns {Promise<{ sessionId: string, approvalUrl?: string, raw: any }>}
+   */
+  async createSubscriptionCheckoutSession(subscriptionData) {
+    const payload = Object.assign({
+      billingMode: subscriptionData?.billingMode || 'METERED',
+      businessId: subscriptionData?.businessId || this.businessId,
+    }, subscriptionData);
+    const data = await this._post('/api/v1/subscriptions/checkout-sessions', payload);
+    return {
+      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.checkoutSession?.uid,
+      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url,
+      raw: data,
+    };
+  }
+
+  /**
+   * Get a subscription checkout session by id
+   * GET {Payment API Base}/api/v1/subscriptions/checkout-sessions/{id}
+   */
+  async getSubscriptionCheckoutSession(id) {
+    return this._get(`/api/v1/subscriptions/checkout-sessions/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * Confirm a subscription checkout session
+   * POST {Payment API Base}/api/v1/subscriptions/checkout-sessions/{id}/confirm
+   */
+  async confirmSubscriptionCheckoutSession(id, body = {}) {
+    return this._post(`/api/v1/subscriptions/checkout-sessions/${encodeURIComponent(id)}/confirm`, body);
+  }
+
+  /**
+   * Create a metered invoice for a subscription
+   * POST {Payment API Base}/api/v1/subscriptions/{subscriptionId}/metered-invoices
+   */
+  async createMeteredInvoice(subscriptionId, invoiceData) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    const payload = Object.assign({}, invoiceData);
+    const data = await this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/metered-invoices`, payload);
+    return data;
+  }
+
+  // --- Banks & Account Verification ---
+
+  /**
+   * List supported banks
+   * GET /api/v1/banks
+   * @param {Object} params - { currency, type, country }
+   */
+  async getBanks(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/banks?${query}` : '/api/v1/banks';
+    return this._get(path);
+  }
+
+  /**
+   * Resolve bank account name
+   * POST /api/v1/banks/resolve
+   * @param {Object} data - { bank_code, account_number, country_code? }
+   */
+  async resolveBankAccount(data) {
+    return this._post('/api/v1/banks/resolve', data);
+  }
+
+  // --- Sandbox Simulator ---
+
+  async startSandboxSimulator() {
+    return this._post('/api/v1/sandbox-simulator/start', {});
+  }
+
+  async stopSandboxSimulator() {
+    return this._post('/api/v1/sandbox-simulator/stop', {});
+  }
+
+  async getSandboxSimulatorStatus() {
+    return this._get('/api/v1/sandbox-simulator/status');
+  }
+
+  /**
+   * Alias for metered invoice creation
+   */
+  async createSubscriptionInvoice(subscriptionId, invoiceData) {
+    return this.createMeteredInvoice(subscriptionId, invoiceData);
+  }
+
+  /**
+   * Schedule a subscription invoice (convenience wrapper)
+   */
+  async scheduleSubscriptionInvoice(subscriptionId, invoiceData) {
+    if (!invoiceData?.dueDate) throw new Error('dueDate is required to schedule an invoice');
+    const payload = Object.assign({}, invoiceData, { chargeSchedule: 'SCHEDULED' });
+    return this.createSubscriptionInvoice(subscriptionId, payload);
+  }
+
+  /**
+   * Get subscription details by id
+   * GET {Payment API Base}/api/v1/subscriptions/{subscriptionId}
+   */
+  async getSubscription(subscriptionId) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    return this._get(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}`);
+  }
+
+  /**
+   * Cancel a subscription (confirm cancellation)
+   * POST {Payment API Base}/api/v1/subscriptions/{subscriptionId}/cancel
+   */
+  async cancelSubscription(subscriptionId, body = {}) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    return this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, body);
+  }
+
+  /**
+   * Relay Authorization APIs (for metered subscriptions)
+   */
+  async createRelayAuthorization(body) {
+    return this._post('/api/v1/subscriptions/relay/authorizations', body);
+  }
+
+  async getRelayAuthorizationStatus(body) {
+    return this._post('/api/v1/subscriptions/relay/authorization-status', body);
+  }
+
+  async revokeRelayAuthorization(body) {
+    // Some environments use '/relay/revokeAuth'; support both via path param
+    const path = body?.useLegacyPath ? '/api/v1/subscriptions/relay/revokeAuth' : '/api/v1/subscriptions/revoke-authorization';
+    return this._post(path, body);
+  }
+
+  /**
+   * Create a renewal checkout session for an existing subscription
+   * POST {Payment API Base}/api/v1/subscriptions/renewal-checkout-sessions
+   */
+  async createRenewalCheckoutSession(body) {
+    return this._post('/api/v1/subscriptions/renewal-checkout-sessions', body);
+  }
+
+  /**
+   * Trigger subscription renew
+   * POST {Payment API Base}/api/v1/subscriptions/{subscriptionId}/renew
+   */
+  async renewSubscription(subscriptionId, body = {}) {
+    return this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/renew`, body);
+  }
+}
+
+module.exports = { KuvarPayServer };

package/index.mjs

@@ -0,0 +1,344 @@
+/**
+ * KuvarPay Server SDK (ESM)
+ *
+ * For backend/server usage only. Requires a Business ID and SECRET API key.
+ * Works with Node 18+ (global fetch). If using older Node, pass a custom fetch
+ * implementation in the constructor (e.g., node-fetch) via { fetchImpl }.
+ */
+
+import crypto from 'node:crypto';
+
+const DEFAULT_BASE = (process.env.PAYMENT_API_BASE_URL
+  || process.env.PAYMENT_SERVER_URL
+  || process.env.NEXT_PUBLIC_PAYMENT_API_BASE_URL
+  || 'http://localhost:3002').replace(/\/+$/, '');
+
+export class KuvarPayServer {
+  /**
+   * @param {Object} config
+   * @param {string} [config.baseUrl] - Payment API Base URL (e.g., https://pay.kuvarpay.com or https://api.yourpaymenthost.com)
+   * @param {string} [config.businessId] - Business ID
+   * @param {string} [config.secretApiKey] - Secret API key for server authentication
+   * @param {number} [config.timeoutMs] - Request timeout in ms (default 60000)
+   * @param {Function} [config.fetchImpl] - Optional fetch implementation for Node < 18
+   */
+  constructor({ baseUrl, businessId, secretApiKey, timeoutMs, fetchImpl } = {}) {
+    this.baseUrl = (baseUrl || DEFAULT_BASE).replace(/\/+$/, '');
+    this.businessId = businessId || process.env.KUVARPAY_BUSINESS_ID;
+    this.secretApiKey = secretApiKey || process.env.KUVARPAY_SECRET_API_KEY || process.env.PAYMENT_SECRET_API_KEY;
+    this.timeoutMs = timeoutMs || 60000;
+    this.fetchImpl = fetchImpl || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
+
+    if (!this.secretApiKey) throw new Error('secretApiKey is required');
+    if (!this.businessId) throw new Error('businessId is required');
+    if (!this.fetchImpl) throw new Error('A fetch implementation is required (Node 18+ or provide fetchImpl)');
+  }
+
+  _headers(extra = {}) {
+    return Object.assign({
+      'Accept': 'application/json',
+      'Authorization': this.secretApiKey,
+      'X-API-Key': this.secretApiKey,
+      'X-Business-ID': this.businessId,
+    }, extra);
+  }
+
+  _buildUrl(path) {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${this.baseUrl}${normalizedPath}`;
+  }
+
+  async _request(method, path, body, extraHeaders = {}) {
+    const url = this._buildUrl(path);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: this._headers(Object.assign({
+          'Content-Type': 'application/json',
+        }, extraHeaders)),
+        body: body != null ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      const text = await res.text();
+      let json;
+      try { json = text ? JSON.parse(text) : null; } catch (e) { json = null; }
+      if (!res.ok) {
+        const msg = (json && (json.error || json.message)) || `HTTP ${res.status}`;
+        const err = new Error(msg);
+        err.status = res.status;
+        err.body = json || text;
+        throw err;
+      }
+      return json;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      throw err;
+    }
+  }
+
+  async _get(path) {
+    return this._request('GET', path);
+  }
+
+  async _post(path, body, extraHeaders = {}) {
+    return this._request('POST', path, body, extraHeaders);
+  }
+
+  /**
+   * Signature Verification for Webhooks
+   * @param {string|Buffer} payload - Raw request body
+   * @param {string} signature - Value from X-KuvarPay-Signature header
+   * @param {string} secret - Your Webhook Secret from the dashboard
+   */
+  verifyWebhookSignature(payload, signature, secret) {
+    if (!signature || !secret) return false;
+    const hmac = crypto.createHmac('sha256', secret);
+    const digest = hmac.update(payload).digest('hex');
+    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
+  }
+
+  async getSessionStatus(sessionId) {
+    if (!sessionId || typeof sessionId !== 'string') {
+      throw new Error('sessionId is required');
+    }
+    const data = await this._get(`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}`);
+    const status = data?.status || data?.checkoutSession?.status || data?.data?.status;
+    const transactionId = data?.transactionId || data?.data?.transactionId || null;
+    return {
+      sessionId: data?.id || data?.sessionId || sessionId,
+      status,
+      transactionId,
+      metadata: data?.metadata || data?.checkoutSession?.metadata || data?.data?.metadata || null,
+      raw: data,
+    };
+  }
+
+  async getTransactionStatus(transactionId) {
+    if (!transactionId || typeof transactionId !== 'string') {
+      throw new Error('transactionId is required');
+    }
+    const data = await this._get(`/api/v1/transactions/${encodeURIComponent(transactionId)}`);
+    return {
+      transactionId: data?.id || transactionId,
+      status: data?.status,
+      metadata: data?.metadata || data?.data?.metadata || null,
+      raw: data,
+    };
+  }
+
+  async getTransactionStatusByReference(reference) {
+    if (!reference) throw new Error('reference is required');
+    return this._get(`/api/v1/transactions/status/${encodeURIComponent(reference)}`);
+  }
+
+  async listTransactions(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/transactions?${query}` : '/api/v1/transactions';
+    return this._get(path);
+  }
+
+  async refundTransaction(transactionId, data = {}) {
+    return this._post(`/api/v1/transactions/${encodeURIComponent(transactionId)}/refund`, data);
+  }
+
+  async getExpiredTransactions() {
+    return this._get('/api/v1/transactions/expired');
+  }
+
+  async getOptimalTransferFee(amount, currency = 'NGN') {
+    return this._get(`/api/v1/optimal-transfer-fee?amount=${amount}&currency=${currency}`);
+  }
+
+  async calculatePayment(data) {
+    return this._post('/api/v1/transactions/calculate-payment', data);
+  }
+
+  async verifyPayment(sessionId) {
+    const s = await this.getSessionStatus(sessionId);
+    const verified = s.status === 'COMPLETED';
+    return {
+      verified,
+      status: s.status,
+      sessionId: s.sessionId,
+      transactionId: s.transactionId,
+      metadata: s.metadata,
+      raw: s.raw,
+    };
+  }
+
+  async createCheckoutSession(checkoutSessionData) {
+    const payload = Object.assign({}, checkoutSessionData, {
+      businessId: checkoutSessionData.businessId || this.businessId,
+    });
+    // payload can include 'subaccount' (string) or 'split_code' (string)
+    const data = await this._post('/api/v1/checkout-sessions', payload);
+    return {
+      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.data?.sessionId,
+      authToken: data?.authToken || data?.data?.authToken,
+      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url || data?.data?.approval_url,
+      raw: data,
+    };
+  }
+
+  async getCurrencies(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/currencies?${query}` : '/api/v1/currencies';
+    return this._get(path);
+  }
+
+  async createTransaction(transactionData) {
+    const payload = Object.assign({}, transactionData, {
+      businessId: transactionData.businessId || this.businessId,
+    });
+    return this._post('/api/v1/transactions', payload);
+  }
+
+  async sendInvoiceEmail(sessionId) {
+    return this._post(`/api/v1/invoices/${encodeURIComponent(sessionId)}/send-email`, {});
+  }
+
+  // --- Subaccount Management ---
+
+  async createSubaccount(subaccountData) {
+    return this._post('/api/v1/subaccounts', subaccountData);
+  }
+
+  async listSubaccounts(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/subaccounts?${query}` : '/api/v1/subaccounts';
+    return this._get(path);
+  }
+
+  async getSubaccount(code) {
+    return this._get(`/api/v1/subaccounts/${encodeURIComponent(code)}`);
+  }
+
+  async updateSubaccount(code, subaccountData) {
+    return this._request('PATCH', `/api/v1/subaccounts/${encodeURIComponent(code)}`, subaccountData);
+  }
+
+  async deleteSubaccount(code) {
+    return this._request('DELETE', `/api/v1/subaccounts/${encodeURIComponent(code)}`);
+  }
+
+  // --- Split Group Management ---
+
+  async createSplitGroup(splitGroupData) {
+    return this._post('/api/v1/split', splitGroupData);
+  }
+
+  async listSplitGroups() {
+    return this._get('/api/v1/split');
+  }
+
+  async getSplitGroup(code) {
+    return this._get(`/api/v1/split/${encodeURIComponent(code)}`);
+  }
+
+  async updateSplitGroup(code, splitGroupData) {
+    return this._request('PATCH', `/api/v1/split/${encodeURIComponent(code)}`, splitGroupData);
+  }
+
+  async deleteSplitGroup(code) {
+    return this._request('DELETE', `/api/v1/split/${encodeURIComponent(code)}`);
+  }
+
+
+  async createSubscriptionCheckoutSession(subscriptionData) {
+    const payload = Object.assign({
+      billingMode: subscriptionData?.billingMode || 'METERED',
+      businessId: subscriptionData?.businessId || this.businessId,
+    }, subscriptionData);
+    const data = await this._post('/api/v1/subscriptions/checkout-sessions', payload);
+    return {
+      sessionId: data?.sessionId || data?.id || data?.checkoutSession?.id || data?.checkoutSession?.uid,
+      approvalUrl: data?.approvalUrl || data?.approval_url || data?.checkoutSession?.approval_url,
+      raw: data,
+    };
+  }
+
+  async getSubscriptionCheckoutSession(id) {
+    return this._get(`/api/v1/subscriptions/checkout-sessions/${encodeURIComponent(id)}`);
+  }
+
+  async confirmSubscriptionCheckoutSession(id, body = {}) {
+    return this._post(`/api/v1/subscriptions/checkout-sessions/${encodeURIComponent(id)}/confirm`, body);
+  }
+
+  async createMeteredInvoice(subscriptionId, invoiceData) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    const payload = Object.assign({}, invoiceData);
+    const data = await this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/metered-invoices`, payload);
+    return data;
+  }
+
+  // --- Banks & Account Verification ---
+
+  async getBanks(params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const path = query ? `/api/v1/banks?${query}` : '/api/v1/banks';
+    return this._get(path);
+  }
+
+  async resolveBankAccount(data) {
+    return this._post('/api/v1/banks/resolve', data);
+  }
+
+  // --- Sandbox Simulator ---
+
+  async startSandboxSimulator() {
+    return this._post('/api/v1/sandbox-simulator/start', {});
+  }
+
+  async stopSandboxSimulator() {
+    return this._post('/api/v1/sandbox-simulator/stop', {});
+  }
+
+  async getSandboxSimulatorStatus() {
+    return this._get('/api/v1/sandbox-simulator/status');
+  }
+
+  async createSubscriptionInvoice(subscriptionId, invoiceData) {
+    return this.createMeteredInvoice(subscriptionId, invoiceData);
+  }
+
+  async scheduleSubscriptionInvoice(subscriptionId, invoiceData) {
+    if (!invoiceData?.dueDate) throw new Error('dueDate is required to schedule an invoice');
+    const payload = Object.assign({}, invoiceData, { chargeSchedule: 'SCHEDULED' });
+    return this.createSubscriptionInvoice(subscriptionId, payload);
+  }
+
+  async getSubscription(subscriptionId) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    return this._get(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}`);
+  }
+
+  async cancelSubscription(subscriptionId, body = {}) {
+    if (!subscriptionId) throw new Error('subscriptionId is required');
+    return this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, body);
+  }
+
+  async createRelayAuthorization(body) {
+    return this._post('/api/v1/subscriptions/relay/authorizations', body);
+  }
+
+  async getRelayAuthorizationStatus(body) {
+    return this._post('/api/v1/subscriptions/relay/authorization-status', body);
+  }
+
+  async revokeRelayAuthorization(body) {
+    const path = body?.useLegacyPath ? '/api/v1/subscriptions/relay/revokeAuth' : '/api/v1/subscriptions/revoke-authorization';
+    return this._post(path, body);
+  }
+
+  async createRenewalCheckoutSession(body) {
+    return this._post('/api/v1/subscriptions/renewal-checkout-sessions', body);
+  }
+
+  async renewSubscription(subscriptionId, body = {}) {
+    return this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/renew`, body);
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kuvarpay/sdk",
+  "version": "1.0.0",
+  "description": "Official KuvarPay Server SDK for Node.js",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "payments",
+    "crypto",
+    "kuvarpay",
+    "blockchain",
+    "fiat-payout",
+    "split-payments"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "KuvarPay Team",
+  "license": "MIT"
+}