@kuvarpay/sdk 1.4.2 → 1.5.0

package/README.md

@@ -1,6 +1,14 @@
 # KuvarPay Server SDK
 
-Official Node.js SDK for integrating **KuvarPay**, the ultimate fiat gateway for the crypto economy. This SDK allows you to handle checkout sessions, direct crypto-to-fiat transactions, recurring subscriptions, and split payments with ease.
+Official Node.js SDK for **KuvarPay** — the payments gateway bridging crypto and local-currency rails. Collect from customers in **crypto _or_ local currency**, pay out to **bank / mobile money**, and run subscriptions and split payments — all from your backend.
+
+**Capabilities**
+- **Collect in crypto** — checkout sessions + crypto deposit addresses (USDT, USDC, BTC, … across BSC, Ethereum, Polygon, Tron, Solana, and more).
+- **Collect in local currency (fiat)** — customers pay by bank transfer or mobile money (NGN, KES, GHS, ZAR, UGX, …); you still settle in your chosen currency. See [Fiat Collection](#-fiat-collection-pay-with-local-currency).
+- **Pay out (fiat Sends)** — send to a recipient's bank account or mobile-money wallet, debited from your USD balance. See [Payouts](#-payouts-sends--secret-key-only).
+- **Subscriptions** — fixed & metered recurring billing.
+- **Split payments** — distribute revenue across subaccounts (bank / mobile money / crypto).
+- **Hosted-checkout controls** — restrict rails, crypto tokens, and fiat countries (per business or per session).
 
 Detailed documentation is available at [developers.kuvarpay.com](https://developers.kuvarpay.com).
 
@@ -87,31 +95,143 @@ The SDK defaults to the KuvarPay Production API (`https://payment.kuvarpay.com`)
 
 | Method | Description |
 | :--- | :--- |
-| `getBanks(currency)` | List supported settlement banks for a specific currency. |
+| `getBanks({ country? \| currency?, type? })` | List a corridor's **primary-rail** payment methods (banks / mobile money). Pass a country (ISO-2) or currency (ISO-4217). |
 | `resolveBankAccount(data)` | Verify bank account names before creating subaccounts. |
 
+### 🌍 Fiat Collection (Pay with Local Currency)
+
+| Method | Description |
+| :--- | :--- |
+| **`createFiatPayment(data)`** | **One-shot**: checkout session + fiat transaction + wait for the deposit. Returns `{ sessionId, transactionId, depositId, nextAction, quote, paymentInstructions }`. |
+| `getFiatCountries()` | Supported corridors. `code` is a **currency**; use **`countryCode`** (ISO-2) for any `country` param, and filter on `depositAvailable`. |
+| `getFiatMethods({ country \| currency, type? })` | Banks / mobile-money operators. Takes ISO-2 `country` **or** ISO-4217 `currency`. Each entry carries a `methodId`. Unknown corridor → `{ methods: [] }`, not an error. |
+| `getFiatCheckoutQuote({ amount, baseCurrency, currency, country })` | Preview the local amount a customer pays. |
+| `createFiatTransaction(data)` | Create a fiat collection on a checkout session. |
+| `waitForFiatDeposit(sessionId, options?)` | Bounded poll until the deposit attaches. Rejects with `FIAT_DEPOSIT_TIMEOUT`. |
+| `getFiatDeposit(depositId)` | Poll a fiat deposit's status (self-reconciles with the provider on each read). |
+| `submitFiatDepositAction(depositId, action, otp?)` | Drive the next step (`CONFIRM_QUOTE` / `SUBMIT_OTP`). |
+
+The one-shot mirrors `createDirectPayment` but stops at the **quote** rather
+than returning a ready-to-pay artifact: confirming locks the FX rate and fires
+the customer's payment prompt, and the gateway withholds `paymentInstructions`
+until then. Show `quote`, confirm, then show instructions.
+
+```javascript
+const { methods } = await kv.getFiatMethods({ country: 'KE', type: 'mobile_money' });
+
+const payment = await kv.createFiatPayment({
+  amount: 5000, currency: 'NGN',           // you settle in NGN
+  fromCurrency: 'KES', country: 'KE',       // customer pays in KES
+  methodId: methods[0].methodId,
+  phone: '+254701234567',
+  callbackUrl: 'https://your.app/webhooks',
+});
+
+if (payment.nextAction === 'CONFIRM_QUOTE') {
+  await kv.submitFiatDepositAction(payment.depositId, 'CONFIRM_QUOTE');
+}
+// Completion arrives on the payment.confirmed webhook — same as crypto.
+```
+
+#### Tracking a fiat deposit — three ways
+
+| Channel | For | How |
+| :--- | :--- | :--- |
+| **Webhook** | Any backend | Set `callbackUrl`; KuvarPay POSTs the final status. The canonical "done" signal — verify with `verifyWebhookSignature`. |
+| **Polling** | Headless / server-side | `getSessionStatus(sessionId).fiatDeposit` → `getFiatDeposit(depositId)`. No browser required. |
+| **SSE** | Browser checkout | Real-time `transaction.ready` push (the hosted checkout uses it) — a latency optimization, never a requirement. |
+
+Server-side deposit flow with **no SSE** — poll the session for the `fiatDeposit` projection, confirm the quote, then poll the deposit to completion:
+
+```javascript
+// 1. Create a session (+ webhook) and a fiat collection on it. createFiatPayment
+//    does steps 1-2 in one call; the long-hand is shown here for clarity.
+const session = await kv.createCheckoutSession({ amount: 5, currency: 'USD', callbackUrl: 'https://you.com/webhook' });
+await kv.createFiatTransaction({ checkoutSessionId: session.sessionId, fromCurrency: 'KES', country: 'KE', methodId, phone: '+2547...' });
+
+// 2. The deposit is created async by the worker — wait for it to attach.
+//    Bounded with backoff; rejects with code FIAT_DEPOSIT_TIMEOUT on expiry.
+const deposit = await kv.waitForFiatDeposit(session.sessionId, { timeoutMs: 30000 });
+
+// 3. Confirm the quote → returns paymentInstructions (account/MoMo to pay, or fires the STK push).
+const confirmed = await kv.submitFiatDepositAction(deposit.depositId, 'CONFIRM_QUOTE');
+console.log(confirmed.paymentInstructions);
+
+// 4. Customer pays. The payment.confirmed webhook is the canonical signal —
+//    only block like this if you genuinely need a synchronous result.
+const settled = await kv.waitForFiatDeposit(session.sessionId, {
+  until: d => ['CREDITED', 'EXPIRED', 'REFUNDED', 'FAILED'].includes(String(d.status).toUpperCase()),
+  timeoutMs: 600000,      // customers take minutes, not seconds
+  pollIntervalMs: 5000,
+});
+```
+
+### 💸 Payouts (Sends) — Secret key only
+
+Payouts move money **out** of your USD balance to a recipient's bank or mobile-money account. The gateway **rejects client/publishable keys** on these endpoints — they must only ever run server-side with your secret key. Payouts settle asynchronously; listen for the completion **webhook** (verify it with `verifyWebhookSignature`), or poll `getFiatSend(sendId)` for server-side reconciliation.
+
+| Method | Description |
+| :--- | :--- |
+| `getFiatMethods({ country, type?, direction: 'outbound' })` | List payout (outbound) banks / mobile-money operators. |
+| `resolveRecipient({ methodId, accountNumber?, phone? })` | Name-enquiry on a payout recipient before sending. |
+| `createFiatSend(data)` | Initiate a bank / mobile-money payout (USD-debited). |
+| `getFiatSend(sendId)` | Poll a payout's status (`PROCESSING` → `COMPLETED`/`FAILED`/`REFUNDED`). |
+
+```javascript
+// Discover payout methods, then verify the recipient name before sending.
+const { methods } = await kv.getFiatMethods({ country: 'NG', type: 'bank', direction: 'outbound' });
+const recipient = await kv.resolveRecipient({ methodId: methods[0].methodId, accountNumber: '0123456789' });
+
+// Fiat payout: recipient receives exactly 50,000 NGN; USD debited from your balance.
+if (recipient.resolved) {
+  const { sendId } = await kv.createFiatSend({
+    destinationCountry: 'NG',
+    destinationCurrency: 'NGN',
+    destinationAmount: 50000,
+    recipient: { methodId: methods[0].methodId, accountNumber: '0123456789', accountName: recipient.accountName },
+    narration: 'Vendor payout',
+  });
+
+  // Prefer the completion webhook; getFiatSend is available for reconciliation.
+  const send = await kv.getFiatSend(sendId);
+  console.log(send.status); // PROCESSING | COMPLETED | FAILED | REFUNDED
+}
+```
+
+> `ownerType`/`ownerId` default to your business (`MERCHANT` + your `businessId`), so you don't need to pass them.
+
 ---
 
 ## 🔒 Security: Webhook Verification
 
-Verify that incoming webhooks are genuinely from KuvarPay using HMAC-SHA256:
+Verify that incoming webhooks are genuinely from KuvarPay using HMAC-SHA256.
+
+Two things matter: verify against the **raw** request body (the signature is
+computed over the exact bytes sent, so a re-serialized `req.body` will not
+match), and pass your **webhook secret** as the third argument.
 
 ```javascript
-app.post('/webhooks/kuvarpay', (req, res) => {
+// Mount the raw body parser on the webhook route only.
+app.post('/webhooks/kuvarpay', express.raw({ type: 'application/json' }), (req, res) => {
   const signature = req.headers['x-kuvarpay-signature'];
-  const payload = req.body; // Raw body object
 
-  const isValid = kv.verifyWebhookSignature(payload, signature);
+  // req.body is a Buffer here — that is what gets signed.
+  const isValid = kv.verifyWebhookSignature(req.body, signature, process.env.KUVARPAY_WEBHOOK_SECRET);
 
-  if (isValid) {
-    // Process payment (e.g. status === 'completed')
-    res.status(200).send();
-  } else {
-    res.status(401).send('Invalid signature');
-  }
+  if (!isValid) return res.status(401).send('Invalid signature');
+
+  const event = JSON.parse(req.body.toString('utf8'));
+  // Process payment (e.g. event.event === 'payment.confirmed')
+  res.status(200).send();
 });
 ```
 
+The gateway sends the header as `sha256=<hex>`. `verifyWebhookSignature`
+strips that prefix for you and accepts a bare hex digest too, so pass the
+header through unmodified. It returns `false` on a bad or malformed
+signature and never throws — always reply `2xx` once you have accepted an
+event, since any `5xx` is treated as a failed delivery and retried.
+
 ---
 
 ## 🧩 TypeScript Support

package/index.d.ts

@@ -6,10 +6,66 @@ export interface KuvarPayServerConfig {
   fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 }
 
+/**
+ * Linked fiat-deposit projection attached to a checkout session, so a
+ * server-side integrator can track a local-currency payment by polling
+ * `getSessionStatus()` instead of relying on the browser SSE stream.
+ * `null` for crypto checkouts or before a fiat transaction is created.
+ */
+/**
+ * The next step the payer must take on a fiat deposit, as derived by the
+ * gateway. `CONFIRM_QUOTE` and `ENTER_OTP` are driven via
+ * `submitFiatDepositAction`; `ENTER_PIN` needs no API call (the customer
+ * approves on their handset) — keep polling. `NONE` means nothing is pending.
+ *
+ * Widened with `(string & {})` so a new server-side value cannot break a build,
+ * while literal autocomplete still works.
+ */
+export type FiatNextAction =
+  | 'CONFIRM_QUOTE'
+  | 'ENTER_OTP'
+  | 'ENTER_PIN'
+  | 'NONE'
+  | (string & {});
+
+export interface FiatCountry {
+  /** ISO-4217 currency code (KES, NGN, …). NOT a country code. */
+  code: string;
+  /** Currency display name ("Kenyan Shillings"). */
+  name: string;
+  /** Country display name ("Kenya"). May echo the currency on un-backfilled rows. */
+  country: string;
+  /** Resolved ISO-3166 alpha-2 ("KE"). Use this for any `country` parameter. */
+  countryCode: string | null;
+  symbol?: string;
+  flag?: string;
+  supportsBank?: boolean;
+  supportsMobileMoney?: boolean;
+  /** Corridor has no active provider — neither deposit nor payout works. */
+  comingSoon?: boolean;
+  /** A collection (deposit) channel is live right now. Filter on this. */
+  depositAvailable?: boolean;
+}
+
+export interface FiatDepositProjection {
+  depositId: string;
+  status: string;
+  nextAction: FiatNextAction | null;
+  paymentInstructions: any | null;
+  quote: any | null;
+  channelKind?: 'mobile_money' | 'bank' | null;
+  currency?: string | null;
+  depositedAmount?: number | null;
+  creditedAmountUsd?: number | null;
+  expiresAt?: string | null;
+}
+
 export interface SessionStatusResult {
   sessionId: string;
   status?: string;
   transactionId: string | null;
+  /** Fiat deposit projection (poll this for headless/no-SSE integrations). */
+  fiatDeposit?: FiatDepositProjection | null;
   metadata?: Record<string, any>;
   raw: any;
 }
@@ -55,11 +111,14 @@ export class KuvarPayServer {
   getSessionStatus(sessionId: string): Promise<SessionStatusResult>;
   getTransactionStatus(transactionId: string): Promise<TransactionStatusResult>;
   getTransactionStatusByReference(reference: string): Promise<any>;
+  updateTransactionStatus(transactionId: string, data: Record<string, any>): Promise<any>;
+  /** Sandbox only. */
+  demoPay(transactionId: 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>;
+  getCurrencies(params?: { network?: string; ticker?: string; search?: string; scope?: 'stablecoins' | 'popular' | 'all'; limit?: number; offset?: number; [key: string]: any }): Promise<any>;
   calculatePayment(data: { fromCurrency: string; fromNetwork: string; toCurrency: string; toAmount: number }): Promise<any>;
   createCheckoutSession(checkoutSessionData: {
     amount: number;
@@ -73,6 +132,16 @@ export class KuvarPayServer {
     subaccount?: string;
     split_code?: string;
     metadata?: Record<string, any>;
+    /**
+     * Per-session hosted-checkout controls — override the merchant's dashboard
+     * defaults for this session. Omit to inherit the business defaults.
+     */
+    checkoutConfig?: {
+      methods?: Array<'crypto' | 'fiat'>;          // which rails to offer
+      cryptoScope?: 'stablecoins' | 'popular' | 'all';
+      cryptoAllowlist?: string[] | null;           // token keys "TICKER|network"; overrides scope
+      fiatCountries?: string[] | null;             // ISO-3166 alpha-2 allow-list
+    };
     [key: string]: any;
   }): Promise<{ sessionId: string; authToken?: string; approvalUrl?: string; raw: any }>;
 
@@ -89,6 +158,10 @@ export class KuvarPayServer {
     metadata?: Record<string, any>;
     subaccount?: string;
     splitCode?: string;
+    /** FIAT rail only (fromNetwork: 'FIAT'). `country` is required by the gateway. */
+    country?: string;
+    methodId?: string;
+    phone?: string;
     [key: string]: any;
   }): Promise<any>;
 
@@ -115,7 +188,6 @@ export class KuvarPayServer {
   }): Promise<any>;
 
   getOptimalTransferFee(amount: number, currency?: string): Promise<any>;
-  sendInvoiceEmail(sessionId: string): Promise<any>;
 
   createSubaccount(subaccountData: CreateSubaccountRequest): Promise<any>;
   listSubaccounts(params?: { page?: number; perPage?: number }): Promise<any>;
@@ -158,14 +230,139 @@ export class KuvarPayServer {
   revokeRelayAuthorization(body: Record<string, any>): Promise<any>;
 
   // Renewal
-  createRenewalCheckoutSession(body: Record<string, any>): Promise<any>;
+  createRenewalCheckoutSession(body: { subscriptionId?: string; id?: string; [key: string]: any }): Promise<any>;
   renewSubscription(subscriptionId: string, body?: Record<string, any>): Promise<any>;
 
   // Banks
-  getBanks(currency: string, options?: { type?: 'bank' | 'mobile_money'; country?: string }): Promise<any>;
-  getBanks(params?: { currency?: string; type?: 'bank' | 'mobile_money'; country?: string }): Promise<any>;
+  getBanks(currency: string, options?: { type?: 'bank' | 'mobile_money'; direction?: 'inbound' | 'outbound' }): Promise<{ methods: Array<{ methodId: string; name: string; currency: string; type: 'bank' | 'mobile_money'; manualInput?: boolean; minAmount?: number | null; maxAmount?: number | null }> }>;
+  getBanks(params: { country?: string; currency?: string; type?: 'bank' | 'mobile_money'; direction?: 'inbound' | 'outbound' }): Promise<{ methods: Array<{ methodId: string; name: string; currency: string; type: 'bank' | 'mobile_money'; manualInput?: boolean; minAmount?: number | null; maxAmount?: number | null }> }>;
   resolveBankAccount(data: { bank_code: string; account_number: string; country_code?: string }): Promise<any>;
 
+  // Fiat collection (Pay with Local Currency)
+  /**
+   * Supported corridors. Note `code` is an ISO-4217 CURRENCY and `country` is
+   * a display name — use **`countryCode`** wherever an ISO-2 is required
+   * (`getFiatMethods`, `createFiatPayment`, `createFiatTransaction`). The SDK
+   * guarantees `countryCode` even on gateways that don't yet return it.
+   * Only corridors with `depositAvailable` can accept a collection.
+   */
+  getFiatCountries(): Promise<{ success: boolean; countries: FiatCountry[] }>;
+  /**
+   * Accepts an ISO-3166 alpha-2 country ("KE") or an ISO-4217 currency
+   * ("KES"). Note `getFiatCountries()` returns its identifier as `code`,
+   * which is a CURRENCY — pass it as `currency`, or as `country` and the SDK
+   * will route 3-letter codes correctly.
+   */
+  getFiatMethods(params: { country?: string; currency?: string; type?: 'bank' | 'mobile_money'; sandbox?: boolean; direction?: 'inbound' | 'outbound' }): Promise<{ methods: Array<{ methodId: string; name: string; currency: string; type: 'bank' | 'mobile_money'; manualInput?: boolean; minAmount?: number | null; maxAmount?: number | null }> }>;
+  getFiatCheckoutQuote(params: { amount: number; baseCurrency: string; currency: string; country: string }): Promise<any>;
+  createFiatTransaction(data: {
+    checkoutSessionId: string;
+    fromCurrency: string;
+    country: string;
+    methodId?: string;
+    phone?: string;
+    customerEmail?: string;
+    customerName?: string;
+    [key: string]: any;
+  }): Promise<any>;
+  getFiatDeposit(depositId: string): Promise<any>;
+  submitFiatDepositAction(depositId: string, action: 'CONFIRM_QUOTE' | 'SUBMIT_OTP', otp?: string): Promise<any>;
+  simulateFiatDepositComplete(depositId: string): Promise<any>;
+
+  /**
+   * Poll a checkout session until its fiat deposit projection appears.
+   * Bounded by `timeoutMs` with backoff; rejects with an Error carrying
+   * `code: 'FIAT_DEPOSIT_TIMEOUT'` and `lastDeposit` on expiry.
+   */
+  waitForFiatDeposit(
+    sessionId: string,
+    options?: {
+      timeoutMs?: number;
+      pollIntervalMs?: number;
+      maxIntervalMs?: number;
+      /** Defaults to "deposit exists". e.g. `d => d.status === 'CREDITED'`. */
+      until?: (deposit: FiatDepositProjection) => boolean;
+    }
+  ): Promise<FiatDepositProjection>;
+
+  /**
+   * One-shot local-currency collection: checkout session + fiat transaction +
+   * wait for the deposit. Stops at the quote unless `autoConfirmQuote` is set —
+   * confirming locks the FX rate and fires the customer's payment prompt, and
+   * `paymentInstructions` stay null until it happens.
+   */
+  createFiatPayment(data: {
+    amount: number;
+    currency: string;
+    fromCurrency: string;
+    country: string;
+    methodId?: string;
+    phone?: string;
+    description?: string;
+    customerEmail?: string;
+    customerName?: string;
+    redirectUrl?: string;
+    callbackUrl?: string;
+    expiresIn?: number;
+    metadata?: Record<string, any>;
+    subaccount?: string;
+    split_code?: string;
+    /** Skip the poll and return as soon as the transaction is created. */
+    waitForDeposit?: boolean;
+    /** Confirm the quote automatically. Off by default — this charges. */
+    autoConfirmQuote?: boolean;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+  }): Promise<{
+    sessionId: string;
+    transactionId: string | null;
+    depositId: string | null;
+    nextAction: FiatNextAction | null;
+    quote: any | null;
+    paymentInstructions: any | null;
+    deposit: FiatDepositProjection | null;
+    session: any;
+    transaction: any;
+  }>;
+
+  // Payouts (Sends) — SECRET key only. Money OUT of your USD balance.
+  resolveRecipient(data: { methodId: string; accountNumber?: string; phone?: string }): Promise<{
+    supported: boolean;
+    resolved: boolean;
+    accountName: string | null;
+    bankName?: string;
+    reason?: string | null;
+  }>;
+  createFiatSend(data: {
+    destinationCountry: string;
+    destinationCurrency: string;
+    recipient: {
+      methodId: string;
+      accountNumber?: string;
+      accountName?: string;
+      phone?: string;
+      manualInput?: Record<string, any>;
+    };
+    sourceAmountUsd?: number;
+    destinationAmount?: number;
+    depositId?: string;
+    narration?: string;
+    metadata?: Record<string, any>;
+    ownerType?: 'MERCHANT' | 'USER';
+    ownerId?: string;
+  }): Promise<{ sendId: string }>;
+  getFiatSend(sendId: string): Promise<{
+    sendId: string;
+    status: 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'REFUNDED' | 'DISPUTED' | string;
+    sourceAmountUsd: number;
+    destinationCountry: string;
+    destinationCurrency: string;
+    destinationAmount: number | null;
+    settledAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+  }>;
+
   // Sandbox
   startSandboxSimulator(): Promise<any>;
   stopSandboxSimulator(): Promise<any>;