@kuvarpay/sdk 1.6.0 → 1.9.0

package/README.md

@@ -6,6 +6,7 @@ Official Node.js SDK for **KuvarPay** — the payments gateway bridging crypto a
 - **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).
+- **KuvarSend account linking** — securely authorize a KuvarSend account as a reusable payout destination with state + PKCE.
 - **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).
@@ -55,11 +56,28 @@ The SDK defaults to the KuvarPay Production API (`https://payment.kuvarpay.com`)
 
 | Option | Description | Env Fallback |
 | :--- | :--- | :--- |
-| `businessId` | Your KuvarPay Business ID | - |
-| `secretApiKey` | Your Production Secret Key | - |
+| `businessId` | Your KuvarPay Business ID | `KUVARPAY_BUSINESS_ID` |
+| `secretApiKey` | Your Secret Key (`rsp_secret_…`) | `KUVARPAY_SECRET_API_KEY`, `PAYMENT_SECRET_API_KEY` |
+| `sandbox` | Set `true` when the key belongs to a **sandbox-mode** business. See [Sandbox](#-sandbox). | `KUVARPAY_SANDBOX` |
 | `baseUrl` | Overrides the API endpoint | `KUVARPAY_API_BASE_URL` |
 | `timeoutMs` | Request timeout (default 60s) | - |
 
+### 🧪 Sandbox
+
+Live and sandbox are **separate `methodId` spaces** — the same bank has a different id in
+each, and the sandbox list is much smaller. Set `sandbox: true` on the client (or per call
+on `getBanks`) so method lists come back in the mode your key actually operates in:
+
+```javascript
+const kv = new KuvarPayServer({ businessId, secretApiKey, sandbox: true });
+```
+
+`getBanks` is served by a public endpoint that cannot see your key, so **it defaults to the
+live list** unless you set this. Everything downstream *does* read the mode from your key, so
+a live `methodId` used with a sandbox key fails with `reason: 'METHOD_MODE_MISMATCH'` on
+`resolveRecipient` and `createFiatSend`. That error means the id came from the wrong
+environment — not that the account is invalid.
+
 ---
 
 ## 📖 API Reference
@@ -95,16 +113,33 @@ The SDK defaults to the KuvarPay Production API (`https://payment.kuvarpay.com`)
 
 | Method | Description |
 | :--- | :--- |
-| `getBanks({ country? \| currency?, type? })` | List a corridor's **primary-rail** payment methods (banks / mobile money). Pass a country (ISO-2) or currency (ISO-4217). |
+| `getBanks({ country? \| currency?, type?, direction?, sandbox? })` | List a corridor's **primary-rail** payment methods (banks / mobile money). Pass a country (ISO-2) or currency (ISO-4217); a 3-letter `country` is read as a currency, so `getFiatCountries().code` can be passed straight through. `direction` defaults to `'inbound'` — pass `'outbound'` for payout methods. |
+| `resolveRecipient({ methodId, accountNumber? \| phone? })` | Name-enquiry before a payout. See [Name enquiry coverage](#name-enquiry-coverage). |
 | `resolveBankAccount(data)` | **Deprecated** alias for `resolveRecipient` — takes `methodId`, not `bank_code`. |
 
+#### Name enquiry coverage
+
+Name enquiry resolves **NGN bank accounts**. Every other currency — and all mobile money —
+returns `supported: false`. That is a normal response, **not** an error:
+
+```javascript
+const r = await kv.resolveRecipient({ methodId, accountNumber });
+
+if (r.resolved)        // use r.accountName
+else if (!r.supported) // corridor can't be verified — collect the name from the user
+else                   // supported but not found — ask them to check the number
+```
+
+Never block a payout on `r.resolved`: outside NGN it is always `false`, and gating on it
+makes every other corridor un-payable. Methods flagged `manualInput` behave the same way.
+
 ### 🌍 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. |
+| `getFiatMethods(...)` | **Deprecated** alias for `getBanks` — same endpoint, same params. |
 | `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`. |
@@ -117,7 +152,7 @@ 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 { methods } = await kv.getBanks({ country: 'KE', type: 'mobile_money' });
 
 const payment = await kv.createFiatPayment({
   amount: 5000, currency: 'NGN',           // you settle in NGN
@@ -172,33 +207,155 @@ Payouts move money **out** of your USD balance to a recipient's bank or mobile-m
 
 | Method | Description |
 | :--- | :--- |
-| `getFiatMethods({ country, type?, direction: 'outbound' })` | List payout (outbound) banks / mobile-money operators. |
+| `getBanks({ 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' });
+const { methods } = await kv.getBanks({ country: 'NG', type: 'bank', direction: 'outbound' });
+const methodId = methods[0].methodId;
+const r = await kv.resolveRecipient({ methodId, accountNumber: '0123456789' });
+
+// `supported: false` just means this corridor can't be verified (anything outside NGN
+// bank) — fall back to the name your user typed rather than blocking the payout.
+if (r.supported && !r.resolved) throw new Error('Account not found — check the number.');
+const accountName = r.accountName ?? userSuppliedName;
 
 // 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',
+const { sendId } = await kv.createFiatSend({
+  destinationCountry: 'NG',
+  destinationCurrency: 'NGN',
+  destinationAmount: 50000,
+  recipient: { methodId, accountNumber: '0123456789', 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.
+
+---
+
+### 🔗 KuvarSend Account Linking
+
+Account linking runs from your backend because it uses your KuvarPay secret key. The SDK generates
+the state and PKCE values, but your backend must persist them in the signed-in user's server-side
+session before redirecting the browser.
+
+First register the exact callback URI under **KuvarPay Dashboard → Developers → Account Linking**.
+LIVE and SANDBOX registrations are separate.
+
+```javascript
+// POST /withdraw/kuvarsend/link — your authenticated backend route
+const pending = kv.prepareKuvarSendAccountLink({
+  externalUserReference: req.user.id, // stable ID from your database; never email/phone
+  redirectUri: 'https://app.example.com/kuvarsend/callback',
+  idempotencyKey: `kuvarsend-link:${req.user.id}:${linkAttemptId}`,
+});
+
+// Persist BEFORE the network call so an ambiguous timeout can safely reuse it.
+req.session.kuvarSendLink = pending;
+
+const authorization = await kv.createKuvarSendAccountLink(pending);
+res.redirect(authorization.authorizationUrl);
+```
+
+KuvarSend returns the user to the registered callback. Load the state and verifier from the same
+server-side session; the SDK rejects a different callback path, mismatched state, malformed code,
+or denial before exchanging the one-time code.
+
+```javascript
+// GET /kuvarsend/callback — your registered backend callback
+const pending = req.session.kuvarSendLink;
+
+try {
+  const linked = await kv.completeKuvarSendAccountLink({
+    // Anchor to the persisted redirect URI; never trust the inbound Host header.
+    callbackUrl: new URL(req.originalUrl, pending.redirectUri).toString(),
+    expectedState: pending.state,
+    redirectUri: pending.redirectUri,
+    codeVerifier: pending.codeVerifier,
   });
 
-  // Prefer the completion webhook; getFiatSend is available for reconciliation.
-  const send = await kv.getFiatSend(sendId);
-  console.log(send.status); // PROCESSING | COMPLETED | FAILED | REFUNDED
+  // Save this opaque id as the user's KuvarSend payout destination.
+  await users.saveKuvarSendLinkedAccount(req.user.id, linked.linked_account_id);
+  delete req.session.kuvarSendLink;
+  res.redirect('/withdraw?kuvarsend=linked');
+} catch (error) {
+  if (error.code === 'ACCESS_DENIED') return res.redirect('/withdraw?kuvarsend=denied');
+  throw error;
 }
 ```
 
-> `ownerType`/`ownerId` default to your business (`MERCHANT` + your `businessId`), so you don't need to pass them.
+If the user approves on a different device than the one they started on — a desktop checkout where
+they scan the `authorizationUrl` as a QR code — no code comes back to your callback. Poll instead
+with the `requestId`, holding the verifier in the same server-side session:
+
+```javascript
+// The desktop page renders authorization.authorizationUrl as a QR code and opens an SSE/socket.
+const linked = await kv.waitForKuvarSendAccountLink({
+  requestId: authorization.requestId,
+  redirectUri: pending.redirectUri,
+  codeVerifier: pending.codeVerifier,
+  timeoutMs: 10 * 60 * 1000,       // default; rejects with AUTHORIZATION_LINK_TIMEOUT
+});
+```
+
+`waitForKuvarSendAccountLink` polls until approval and then completes the exchange for you. To drive
+the polling yourself, call `completeKuvarSendAccountLink({ requestId, redirectUri, codeVerifier })`
+directly — it resolves once approved and throws a 409 `AUTHORIZATION_NOT_READY` until then.
+
+Use `getKuvarSendAccountLink(linkedAccountId)` for reconciliation and
+`revokeKuvarSendAccountLink(linkedAccountId)` when the user disconnects KuvarSend.
+
+Once linked, credit that KuvarSend wallet directly from your backend. Create a restricted secret
+key with `account_links:read`, `account_links:write`, `payouts:read`, and `payouts:write`; never put
+that key or these SDK calls in browser/mobile code. The payout is synchronous and atomic: a
+successful response means the merchant's USD wallet was debited and the user's KuvarSend balance
+was credited in the same database transaction. You name the amount the **user receives**, in any
+currency KuvarSend supports; we debit the USD equivalent at the quoted rate. Quote first with
+`quoteKuvarSendPayout` to show the user what they will get before they confirm.
+
+```javascript
+const payout = await kv.createKuvarSendPayout({
+  linkedAccountId: linked.linked_account_id,
+  amount: '50000',                 // exact major units; use a decimal string
+  currency: 'RWF',
+  externalReference: 'withdrawal_123',
+  idempotencyKey: 'kuvarsend-payout:withdrawal_123',
+});
+
+console.log(payout.payout_id, payout.status); // kwp_… COMPLETED
+
+// Reconciliation can poll one payout or walk cursor-based pages.
+const saved = await kv.getKuvarSendPayout(payout.payout_id);
+const page = await kv.listKuvarSendPayouts({
+  linkedAccountId: linked.linked_account_id,
+  limit: 50,
+});
+```
+
+Retry an ambiguous timeout with the same idempotency key and identical body. The API returns the
+same payout receipt without a second debit or wallet credit. Reusing the key with a changed amount,
+currency, link, or reference is rejected. Live and sandbox links and balances are isolated; create
+and authorize a separate link in each environment.
+
+Subscribe your merchant webhook to `kuvarsend.payout.completed` for durable payout completion and
+`account_link.revoked` for authority changes. Both payloads include an opaque `event_id`, event
+timestamp, business/environment, and link or payout identifiers. They never include the KuvarSend
+user ID, contact details, wallet balance, or internal ledger IDs. Verify the raw request body with
+`verifyWebhookSignature` and deduplicate processing by `event_id`.
+
+The authorization URL is a verified HTTPS Universal/App Link. If KuvarSend is installed, it opens
+the native consent screen. Otherwise it opens a KuvarSend install page. V1 does not approve links
+in a web browser and does not silently preserve a request through an app-store installation: after
+installing, the user taps **Open KuvarSend** on the page, or restarts withdrawal if the short-lived
+request expired.
 
 ---
 
@@ -248,4 +405,4 @@ const kv = new KuvarPayServer({ ... });
 
 ## 📄 License
 
-MIT © KuvarPay Development Team
+MIT © KuvarPay Development Team

package/index.d.ts

@@ -2,6 +2,12 @@ export interface KuvarPayServerConfig {
   baseUrl?: string;
   businessId?: string;
   secretApiKey?: string;
+  /**
+   * Set true when the key belongs to a sandbox-mode business. Live and sandbox
+   * are separate `methodId` spaces, so `getBanks()` must be fetched in the same
+   * mode the key resolves/pays out in. Defaults to `KUVARPAY_SANDBOX=true`.
+   */
+  sandbox?: boolean;
   timeoutMs?: number;
   fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 }
@@ -86,6 +92,102 @@ export interface VerifyPaymentResult {
   raw: any;
 }
 
+export interface PrepareKuvarSendAccountLinkInput {
+  /** Stable user id from your own database. KuvarPay stores only a keyed hash. */
+  externalUserReference: string;
+  /** Exact URI registered under Dashboard → Developers → Account Linking. */
+  redirectUri: string;
+  /** Persist and reuse this value when retrying an ambiguous API request. */
+  idempotencyKey?: string;
+}
+
+export interface PreparedKuvarSendAccountLink {
+  externalUserReference: string;
+  redirectUri: string;
+  state: string;
+  codeVerifier: string;
+  codeChallenge: string;
+  idempotencyKey: string;
+}
+
+export interface KuvarSendAccountLinkAuthorization extends PreparedKuvarSendAccountLink {
+  requestId: string;
+  authorizationUrl: string;
+  expiresAt: string;
+}
+
+export interface KuvarSendLinkedAccount {
+  linked_account_id: string;
+  status: 'ACTIVE' | 'REVOKED' | string;
+  scope: 'payouts:receive';
+  display_name: string | null;
+  kuvar_tag: string;
+  linked_at: string;
+  revoked_at?: string;
+}
+
+export interface KuvarSendListPage<T> {
+  data: T[];
+  next_cursor: string | null;
+}
+
+export interface CreateKuvarSendPayoutInput {
+  linkedAccountId: string;
+  /** Exact major-unit decimal; pass a string to avoid floating-point rounding. */
+  amount: string;
+  currency: string;
+  externalReference?: string;
+  /** Persist and reuse for retries of this exact payout request. */
+  idempotencyKey: string;
+}
+
+export interface KuvarSendPayout {
+  payout_id: string;
+  status: 'COMPLETED' | string;
+  linked_account_id: string;
+  amount: string;
+  currency: string;
+  external_reference?: string;
+  created_at: string;
+}
+
+export interface KuvarSendPayoutQuote {
+  quote_id: string;
+  linked_account_id: string;
+  amount: string;
+  currency: string;
+  source_currency: 'USD';
+  source_amount: string;
+  rate: string;
+  expires_at: string;
+}
+
+export interface CompleteKuvarSendAccountLinkInput {
+  /** Full HTTPS URL received by your registered callback handler. */
+  callbackUrl: string;
+  /** State read from the same server-side session as the code verifier. */
+  expectedState: string;
+  redirectUri: string;
+  codeVerifier: string;
+}
+
+/** Cross-device completion: the user approved on another device (QR flow). */
+export interface CompleteKuvarSendAccountLinkByRequestInput {
+  requestId: string;
+  redirectUri: string;
+  codeVerifier: string;
+}
+
+export interface WaitForKuvarSendAccountLinkInput {
+  requestId: string;
+  redirectUri: string;
+  codeVerifier: string;
+  /** Poll interval. Default 3000. */
+  pollMs?: number;
+  /** Give up and reject after this long. Default 10 minutes. */
+  timeoutMs?: number;
+}
+
 export interface CreateSubaccountRequest {
   business_name: string;
   percentage_charge?: number | string;
@@ -234,8 +336,13 @@ export class KuvarPayServer {
   renewSubscription(subscriptionId: string, body?: Record<string, any>): Promise<any>;
 
   // Banks
-  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 }> }>;
+  getBanks(currency: string, options?: { type?: 'bank' | 'mobile_money'; direction?: 'inbound' | 'outbound'; sandbox?: boolean }): Promise<{ methods: Array<{ methodId: string; name: string; currency: string; type: 'bank' | 'mobile_money'; manualInput?: boolean; minAmount?: number | null; maxAmount?: number | null }> }>;
+  /**
+   * `sandbox` must match the mode of the business your key belongs to — live and
+   * sandbox are separate methodId spaces. Defaults to the client-level `sandbox`
+   * option. Using the wrong one yields `reason: 'METHOD_MODE_MISMATCH'` on resolve.
+   */
+  getBanks(params: { country?: string; currency?: string; type?: 'bank' | 'mobile_money'; direction?: 'inbound' | 'outbound'; sandbox?: boolean }): Promise<{ methods: Array<{ methodId: string; name: string; currency: string; type: 'bank' | 'mobile_money'; manualInput?: boolean; minAmount?: number | null; maxAmount?: number | null }> }>;
   /**
    * @deprecated Use `resolveRecipient`. Thin alias over
    * `POST /api/v1/fiat/resolve-recipient`.
@@ -276,6 +383,7 @@ export class KuvarPayServer {
    * which is a CURRENCY — pass it as `currency`, or as `country` and the SDK
    * will route 3-letter codes correctly.
    */
+  /** @deprecated Alias for `getBanks`, which it delegates to. */
   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: {
@@ -386,10 +494,47 @@ export class KuvarPayServer {
     updatedAt: string;
   }>;
 
+  // KuvarSend account authorization — SECRET key / merchant backend only.
+  prepareKuvarSendAccountLink(input: PrepareKuvarSendAccountLinkInput): PreparedKuvarSendAccountLink;
+  createKuvarSendAccountLink(
+    input: PrepareKuvarSendAccountLinkInput | PreparedKuvarSendAccountLink,
+  ): Promise<KuvarSendAccountLinkAuthorization>;
+  parseKuvarSendAccountLinkCallback(
+    callbackUrl: string,
+    options: { expectedState: string; redirectUri: string },
+  ): { code: string; state: string };
+  completeKuvarSendAccountLink(
+    input: CompleteKuvarSendAccountLinkInput | CompleteKuvarSendAccountLinkByRequestInput,
+  ): Promise<KuvarSendLinkedAccount>;
+  /**
+   * Cross-device: polls until the user approves on their phone, then completes
+   * the exchange. Rejects with AUTHORIZATION_LINK_TIMEOUT when it runs out.
+   */
+  waitForKuvarSendAccountLink(input: WaitForKuvarSendAccountLinkInput): Promise<KuvarSendLinkedAccount>;
+  getKuvarSendAccountLink(linkedAccountId: string): Promise<KuvarSendLinkedAccount>;
+  listKuvarSendAccountLinks(input?: {
+    status?: 'ACTIVE' | 'REVOKED';
+    limit?: number;
+    cursor?: string;
+  }): Promise<KuvarSendListPage<KuvarSendLinkedAccount>>;
+  revokeKuvarSendAccountLink(linkedAccountId: string): Promise<KuvarSendLinkedAccount>;
+  createKuvarSendPayout(input: CreateKuvarSendPayoutInput): Promise<KuvarSendPayout>;
+  quoteKuvarSendPayout(input: {
+    linkedAccountId: string;
+    amount: string;
+    currency: string;
+  }): Promise<KuvarSendPayoutQuote>;
+  getKuvarSendPayout(payoutId: string): Promise<KuvarSendPayout>;
+  listKuvarSendPayouts(input?: {
+    linkedAccountId?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<KuvarSendListPage<KuvarSendPayout>>;
+
   // Sandbox
   startSandboxSimulator(): Promise<any>;
   stopSandboxSimulator(): Promise<any>;
   getSandboxSimulatorStatus(): Promise<any>;
 }
 
-export default KuvarPayServer;
+export default KuvarPayServer;

package/index.js

@@ -9,6 +9,7 @@
  */
 
 const crypto = require('crypto');
+const { isIP } = require('net');
 
 const DEFAULT_BASE = (process.env.KUVARPAY_API_BASE_URL
   || process.env.PAYMENT_API_BASE_URL
@@ -55,6 +56,35 @@ function normalizeFiatCountries(data) {
   });
 }
 
+function kuvarSendLinkError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function validateKuvarSendRedirectUri(value) {
+  if (typeof value !== 'string' || value.length < 12 || value.length > 2048 || value.trim() !== value
+    || /[*{}?#]/.test(value)) {
+    throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri must be an exact public HTTPS URL');
+  }
+  let url;
+  try { url = new URL(value); } catch { throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri is invalid'); }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const safeHost = host.endsWith('.') ? host.slice(0, -1) : host;
+  if (url.protocol !== 'https:' || !host || safeHost === 'localhost' || safeHost.endsWith('.localhost')
+    || isIP(safeHost) !== 0 || url.username || url.password || url.search || url.hash) {
+    throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri must be an exact public HTTPS URL');
+  }
+  return value;
+}
+
+function equalSecretText(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  const a = Buffer.from(left, 'utf8');
+  const b = Buffer.from(right, 'utf8');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
 class KuvarPayServer {
   /**
    * @param {Object} config
@@ -64,10 +94,16 @@ class KuvarPayServer {
    * @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 } = {}) {
+  constructor({ baseUrl, businessId, secretApiKey, timeoutMs, fetchImpl, sandbox } = {}) {
     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;
+    // Set this to true when the key belongs to a sandbox-mode business, so
+    // getBanks() returns sandbox methodIds. Mixing the two spaces produces
+    // METHOD_MODE_MISMATCH on resolve and payout.
+    this.sandbox = sandbox != null
+      ? !!sandbox
+      : String(process.env.KUVARPAY_SANDBOX || '').toLowerCase() === 'true';
     this.timeoutMs = timeoutMs || 60000;
     this.fetchImpl = fetchImpl || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
 
@@ -139,6 +175,10 @@ class KuvarPayServer {
     return this._request('PATCH', path, body, extraHeaders);
   }
 
+  async _delete(path, body) {
+    return this._request('DELETE', path, body);
+  }
+
   /**
    * Fetch checkout session status by sessionId
    * GET {Payment API Base}/api/v1/checkout-sessions/{sessionId}
@@ -540,11 +580,27 @@ class KuvarPayServer {
     // (settlement) methods.
     const { country, currency, type, direction = 'inbound' } = params || {};
     if (!country && !currency) throw new Error('country or currency is required');
+    // Live and sandbox are SEPARATE methodId spaces — the same bank has a
+    // different id in each. A methodId from the wrong space is rejected
+    // downstream with reason METHOD_MODE_MISMATCH, so the list must be fetched
+    // in the same mode the key's business is in. Defaults to the client-level
+    // `sandbox` flag when the call doesn't override it.
+    const sandbox = params.sandbox != null ? params.sandbox : this.sandbox;
+
     const qs = new URLSearchParams();
-    if (country) qs.set('country', country);
-    if (currency) qs.set('currency', currency);
+    if (currency) qs.set('currency', String(currency).toUpperCase());
+    if (country) {
+      // A country and a currency go in DIFFERENT query params, and
+      // getFiatCountries() returns its identifier as `code` — which is a
+      // CURRENCY. Passing that straight through as `country=KES` silently
+      // returns { methods: [] }. 2 chars -> country, 3 chars -> currency.
+      const code = String(country).toUpperCase();
+      if (!currency && code.length === 3) qs.set('currency', code);
+      else qs.set('country', code);
+    }
     if (type) qs.set('type', type);
     if (direction) qs.set('direction', direction);
+    if (sandbox) qs.set('sandbox', 'true');
     return this._get(`/api/v1/fiat/banks?${qs.toString()}`);
   }
 
@@ -606,21 +662,14 @@ class KuvarPayServer {
    *
    * @param {Object} params - { country?, currency?, type?, sandbox?, direction? }
    */
+  /**
+   * @deprecated Use `getBanks`, which this now delegates to. Both hit
+   * `GET /api/v1/fiat/banks`; having two names for one endpoint is how the
+   * missing `sandbox` support on `getBanks` went unnoticed. Kept as an alias so
+   * existing integrations keep working.
+   */
   async getFiatMethods(params = {}) {
-    const { country, currency, type, sandbox, direction = 'inbound' } = params;
-    if (!country && !currency) throw new Error('country or currency is required');
-
-    const qs = new URLSearchParams({ direction });
-    if (currency) qs.set('currency', String(currency).toUpperCase());
-    if (country) {
-      const code = String(country).toUpperCase();
-      // A 3-letter code is a currency, not a country.
-      if (!currency && code.length === 3) qs.set('currency', code);
-      else qs.set('country', code);
-    }
-    if (type) qs.set('type', type);
-    if (sandbox) qs.set('sandbox', 'true');
-    return this._get(`/api/v1/fiat/banks?${qs.toString()}`);
+    return this.getBanks(params);
   }
 
   /**
@@ -925,6 +974,266 @@ class KuvarPayServer {
     return this._get(`/api/v1/fiat/sends/${encodeURIComponent(sendId)}`);
   }
 
+  /**
+   * Prepare state, PKCE and idempotency material before creating an account
+   * link. Persist the returned object in the merchant's server-side session.
+   */
+  prepareKuvarSendAccountLink({ externalUserReference, redirectUri, idempotencyKey } = {}) {
+    if (typeof externalUserReference !== 'string' || !externalUserReference || externalUserReference.length > 255) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalUserReference is required');
+    }
+    const exactRedirectUri = validateKuvarSendRedirectUri(redirectUri);
+    const state = crypto.randomBytes(32).toString('base64url');
+    const codeVerifier = crypto.randomBytes(64).toString('base64url');
+    const codeChallenge = crypto.createHash('sha256').update(codeVerifier, 'ascii').digest('base64url');
+    const retryKey = idempotencyKey || crypto.randomUUID();
+    if (typeof retryKey !== 'string' || !retryKey || retryKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    return { externalUserReference, redirectUri: exactRedirectUri, state, codeVerifier, codeChallenge, idempotencyKey: retryKey };
+  }
+
+  async createKuvarSendAccountLink(input = {}) {
+    const prepared = input.state && input.codeVerifier
+      ? Object.assign({}, input)
+      : this.prepareKuvarSendAccountLink(input);
+    const redirectUri = validateKuvarSendRedirectUri(prepared.redirectUri);
+    if (typeof prepared.externalUserReference !== 'string' || !prepared.externalUserReference || prepared.externalUserReference.length > 255) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalUserReference is required');
+    }
+    if (typeof prepared.state !== 'string' || prepared.state.length < 22 || prepared.state.length > 512
+      || /[\u0000-\u001f\u007f]/.test(prepared.state)) {
+      throw kuvarSendLinkError('INVALID_STATE', 'state is invalid');
+    }
+    if (typeof prepared.codeVerifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(prepared.codeVerifier)) {
+      throw kuvarSendLinkError('INVALID_CODE_VERIFIER', 'codeVerifier is invalid');
+    }
+    const codeChallenge = crypto.createHash('sha256').update(prepared.codeVerifier, 'ascii').digest('base64url');
+    if (prepared.codeChallenge && !equalSecretText(prepared.codeChallenge, codeChallenge)) {
+      throw kuvarSendLinkError('PKCE_MISMATCH', 'codeChallenge does not match codeVerifier');
+    }
+    if (typeof prepared.idempotencyKey !== 'string' || !prepared.idempotencyKey || prepared.idempotencyKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    const response = await this._post('/api/v1/payouts/account-link-requests', {
+      external_user_reference: prepared.externalUserReference,
+      redirect_uri: redirectUri,
+      state: prepared.state,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      scope: 'payouts:receive',
+    }, { 'Idempotency-Key': prepared.idempotencyKey });
+    const data = response?.data || response;
+    return {
+      requestId: data.id,
+      authorizationUrl: data.authorization_url,
+      expiresAt: data.expires_at,
+      state: prepared.state,
+      codeVerifier: prepared.codeVerifier,
+      redirectUri,
+      idempotencyKey: prepared.idempotencyKey,
+    };
+  }
+
+  parseKuvarSendAccountLinkCallback(callbackUrl, { expectedState, redirectUri } = {}) {
+    const exactRedirectUri = validateKuvarSendRedirectUri(redirectUri);
+    let callback;
+    try { callback = new URL(callbackUrl); } catch { throw kuvarSendLinkError('INVALID_CALLBACK', 'Callback URL is invalid'); }
+    const expected = new URL(exactRedirectUri);
+    if (callback.protocol !== expected.protocol || callback.host !== expected.host || callback.pathname !== expected.pathname
+      || callback.username || callback.password || callback.hash) {
+      throw kuvarSendLinkError('REDIRECT_URI_MISMATCH', 'Callback URL does not match redirectUri');
+    }
+    const states = callback.searchParams.getAll('state');
+    if (states.length !== 1 || !equalSecretText(states[0], expectedState)) {
+      throw kuvarSendLinkError('STATE_MISMATCH', 'Account-link callback state does not match');
+    }
+    const errors = callback.searchParams.getAll('error');
+    if (errors.length) {
+      if (errors.length !== 1 || errors[0] !== 'access_denied'
+        || callback.searchParams.getAll('code').length
+        || [...callback.searchParams.keys()].some((key) => !['error', 'state'].includes(key))) {
+        throw kuvarSendLinkError('AUTHORIZATION_ERROR', 'KuvarSend authorization failed');
+      }
+      throw kuvarSendLinkError('ACCESS_DENIED', 'The user denied KuvarSend account linking');
+    }
+    const codes = callback.searchParams.getAll('code');
+    if (codes.length !== 1 || !/^kpal_[A-Za-z0-9_-]{43}$/.test(codes[0])) {
+      throw kuvarSendLinkError('INVALID_AUTHORIZATION_CODE', 'Authorization code is missing or invalid');
+    }
+    if ([...callback.searchParams.keys()].some((key) => !['code', 'state'].includes(key))) {
+      throw kuvarSendLinkError('INVALID_CALLBACK', 'Callback URL contains unsupported parameters');
+    }
+    return { code: codes[0], state: states[0] };
+  }
+
+  async completeKuvarSendAccountLink(input = {}) {
+    if (typeof input.codeVerifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(input.codeVerifier)) {
+      throw kuvarSendLinkError('INVALID_CODE_VERIFIER', 'codeVerifier is invalid');
+    }
+    // Cross-device shape: the desktop session identifies the request directly
+    // and polls until the phone approves. No code ever crosses devices.
+    if (input.requestId != null) {
+      if (!/^alr_[0-9a-f]{32}$/.test(String(input.requestId))) {
+        throw kuvarSendLinkError('INVALID_REQUEST_ID', 'requestId is invalid');
+      }
+      const response = await this._post('/api/v1/payouts/account-links/exchange', {
+        request_id: input.requestId,
+        redirect_uri: input.redirectUri,
+        code_verifier: input.codeVerifier,
+      });
+      return response?.data || response;
+    }
+    const callback = this.parseKuvarSendAccountLinkCallback(input.callbackUrl, {
+      expectedState: input.expectedState,
+      redirectUri: input.redirectUri,
+    });
+    const response = await this._post('/api/v1/payouts/account-links/exchange', {
+      code: callback.code,
+      redirect_uri: input.redirectUri,
+      code_verifier: input.codeVerifier,
+    });
+    return response?.data || response;
+  }
+
+  /**
+   * Cross-device completion: polls `completeKuvarSendAccountLink({ requestId, … })`
+   * while the request is still pending, so a desktop session finishes on its own
+   * the moment the user approves in KuvarSend.
+   */
+  async waitForKuvarSendAccountLink({
+    requestId,
+    redirectUri,
+    codeVerifier,
+    pollMs = 3000,
+    timeoutMs = 10 * 60 * 1000,
+  } = {}) {
+    if (!/^alr_[0-9a-f]{32}$/.test(String(requestId || ''))) {
+      throw kuvarSendLinkError('INVALID_REQUEST_ID', 'requestId is invalid');
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      try {
+        return await this.completeKuvarSendAccountLink({ requestId, redirectUri, codeVerifier });
+      } catch (error) {
+        // The gateway answers 409 AUTHORIZATION_NOT_READY while approval is
+        // pending (err.body carries the JSON). Anything else is real.
+        const notReady = error?.body?.code === 'AUTHORIZATION_NOT_READY'
+          || error?.code === 'AUTHORIZATION_NOT_READY';
+        if (!notReady) throw error;
+        if (Date.now() >= deadline) {
+          throw kuvarSendLinkError('AUTHORIZATION_LINK_TIMEOUT', 'The account-link request was not approved in time.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.max(250, pollMs)));
+      }
+    }
+  }
+
+  async getKuvarSendAccountLink(linkedAccountId) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const response = await this._get(`/api/v1/payouts/account-links/${encodeURIComponent(linkedAccountId)}`);
+    return response?.data || response;
+  }
+
+  async listKuvarSendAccountLinks({ status, limit = 50, cursor } = {}) {
+    if (status != null && !['ACTIVE', 'REVOKED'].includes(status)) {
+      throw kuvarSendLinkError('INVALID_STATUS', 'status must be ACTIVE or REVOKED');
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw kuvarSendLinkError('INVALID_LIMIT', 'limit must be an integer from 1 to 100');
+    }
+    if (cursor != null && !/^kal_[0-9a-f]{32}$/.test(String(cursor))) {
+      throw kuvarSendLinkError('INVALID_CURSOR', 'cursor is invalid');
+    }
+    const query = new URLSearchParams();
+    if (status) query.set('status', status);
+    query.set('limit', String(limit));
+    if (cursor) query.set('cursor', cursor);
+    return this._get(`/api/v1/payouts/account-links?${query}`);
+  }
+
+  async createKuvarSendPayout({ linkedAccountId, amount, currency, externalReference, idempotencyKey } = {}) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const exactAmount = String(amount ?? '');
+    if (!/^\d+(?:\.\d+)?$/.test(exactAmount) || exactAmount.length > 80) {
+      throw kuvarSendLinkError('INVALID_AMOUNT', 'amount must be a positive decimal string');
+    }
+    const exactCurrency = String(currency || '').toUpperCase();
+    if (!/^[A-Z]{3,5}$/.test(exactCurrency)) {
+      throw kuvarSendLinkError('INVALID_CURRENCY', 'currency must be a 3-5 letter code');
+    }
+    if (externalReference != null && (typeof externalReference !== 'string' || !externalReference || externalReference.length > 255)) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalReference must be 1-255 characters');
+    }
+    if (typeof idempotencyKey !== 'string' || !idempotencyKey || idempotencyKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    const response = await this._post('/api/v1/payouts/kuvarsend', {
+      linked_account_id: linkedAccountId,
+      amount: exactAmount,
+      currency: exactCurrency,
+      ...(externalReference ? { external_reference: externalReference } : {}),
+    }, { 'Idempotency-Key': idempotencyKey });
+    return response?.data || response;
+  }
+
+  async quoteKuvarSendPayout({ linkedAccountId, amount, currency } = {}) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const exactAmount = String(amount ?? '');
+    if (!/^\d+(?:\.\d+)?$/.test(exactAmount) || exactAmount.length > 80) {
+      throw kuvarSendLinkError('INVALID_AMOUNT', 'amount must be a positive decimal string');
+    }
+    const exactCurrency = String(currency || '').toUpperCase();
+    if (!/^[A-Z]{3,5}$/.test(exactCurrency)) {
+      throw kuvarSendLinkError('INVALID_CURRENCY', 'currency must be a 3-5 letter code');
+    }
+    const response = await this._post('/api/v1/payouts/kuvarsend/quote', {
+      linked_account_id: linkedAccountId,
+      amount: exactAmount,
+      currency: exactCurrency,
+    });
+    return response?.data || response;
+  }
+
+  async getKuvarSendPayout(payoutId) {
+    if (!/^kwp_[0-9a-f]{32}$/.test(String(payoutId || ''))) {
+      throw kuvarSendLinkError('INVALID_PAYOUT_ID', 'payoutId is invalid');
+    }
+    const response = await this._get(`/api/v1/payouts/kuvarsend/${encodeURIComponent(payoutId)}`);
+    return response?.data || response;
+  }
+
+  async listKuvarSendPayouts({ linkedAccountId, limit = 50, cursor } = {}) {
+    if (linkedAccountId != null && !/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw kuvarSendLinkError('INVALID_LIMIT', 'limit must be an integer from 1 to 100');
+    }
+    if (cursor != null && !/^kwp_[0-9a-f]{32}$/.test(String(cursor))) {
+      throw kuvarSendLinkError('INVALID_CURSOR', 'cursor is invalid');
+    }
+    const query = new URLSearchParams();
+    if (linkedAccountId) query.set('linked_account_id', linkedAccountId);
+    query.set('limit', String(limit));
+    if (cursor) query.set('cursor', cursor);
+    return this._get(`/api/v1/payouts/kuvarsend?${query}`);
+  }
+
+  async revokeKuvarSendAccountLink(linkedAccountId) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const response = await this._delete(`/api/v1/payouts/account-links/${encodeURIComponent(linkedAccountId)}`);
+    return response?.data || response;
+  }
+
   // --- Sandbox Simulator ---
 
   async startSandboxSimulator() {
@@ -1035,4 +1344,4 @@ class KuvarPayServer {
   }
 }
 
-module.exports = { KuvarPayServer };
+module.exports = { KuvarPayServer };

package/index.mjs

@@ -7,6 +7,7 @@
  */
 
 import crypto from 'node:crypto';
+import { isIP } from 'node:net';
 
 const DEFAULT_BASE = (process.env.KUVARPAY_API_BASE_URL
   || process.env.PAYMENT_API_BASE_URL
@@ -52,6 +53,35 @@ function normalizeFiatCountries(data) {
   });
 }
 
+function kuvarSendLinkError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function validateKuvarSendRedirectUri(value) {
+  if (typeof value !== 'string' || value.length < 12 || value.length > 2048 || value.trim() !== value
+    || /[*{}?#]/.test(value)) {
+    throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri must be an exact public HTTPS URL');
+  }
+  let url;
+  try { url = new URL(value); } catch { throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri is invalid'); }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const safeHost = host.endsWith('.') ? host.slice(0, -1) : host;
+  if (url.protocol !== 'https:' || !host || safeHost === 'localhost' || safeHost.endsWith('.localhost')
+    || isIP(safeHost) !== 0 || url.username || url.password || url.search || url.hash) {
+    throw kuvarSendLinkError('INVALID_REDIRECT_URI', 'redirectUri must be an exact public HTTPS URL');
+  }
+  return value;
+}
+
+function equalSecretText(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  const a = Buffer.from(left, 'utf8');
+  const b = Buffer.from(right, 'utf8');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
 export class KuvarPayServer {
   /**
    * @param {Object} config
@@ -61,10 +91,16 @@ export class KuvarPayServer {
    * @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 } = {}) {
+  constructor({ baseUrl, businessId, secretApiKey, timeoutMs, fetchImpl, sandbox } = {}) {
     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;
+    // Set this to true when the key belongs to a sandbox-mode business, so
+    // getBanks() returns sandbox methodIds. Mixing the two spaces produces
+    // METHOD_MODE_MISMATCH on resolve and payout.
+    this.sandbox = sandbox != null
+      ? !!sandbox
+      : String(process.env.KUVARPAY_SANDBOX || '').toLowerCase() === 'true';
     this.timeoutMs = timeoutMs || 60000;
     this.fetchImpl = fetchImpl || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
 
@@ -136,6 +172,10 @@ export class KuvarPayServer {
     return this._request('PATCH', path, body, extraHeaders);
   }
 
+  async _delete(path, body) {
+    return this._request('DELETE', path, body);
+  }
+
   /**
    * Signature Verification for Webhooks
    *
@@ -428,11 +468,27 @@ export class KuvarPayServer {
     // (settlement) methods.
     const { country, currency, type, direction = 'inbound' } = params || {};
     if (!country && !currency) throw new Error('country or currency is required');
+    // Live and sandbox are SEPARATE methodId spaces — the same bank has a
+    // different id in each. A methodId from the wrong space is rejected
+    // downstream with reason METHOD_MODE_MISMATCH, so the list must be fetched
+    // in the same mode the key's business is in. Defaults to the client-level
+    // `sandbox` flag when the call doesn't override it.
+    const sandbox = params.sandbox != null ? params.sandbox : this.sandbox;
+
     const qs = new URLSearchParams();
-    if (country) qs.set('country', country);
-    if (currency) qs.set('currency', currency);
+    if (currency) qs.set('currency', String(currency).toUpperCase());
+    if (country) {
+      // A country and a currency go in DIFFERENT query params, and
+      // getFiatCountries() returns its identifier as `code` — which is a
+      // CURRENCY. Passing that straight through as `country=KES` silently
+      // returns { methods: [] }. 2 chars → country, 3 chars → currency.
+      const code = String(country).toUpperCase();
+      if (!currency && code.length === 3) qs.set('currency', code);
+      else qs.set('country', code);
+    }
     if (type) qs.set('type', type);
     if (direction) qs.set('direction', direction);
+    if (sandbox) qs.set('sandbox', 'true');
     return this._get(`/api/v1/fiat/banks?${qs.toString()}`);
   }
 
@@ -480,28 +536,14 @@ export class KuvarPayServer {
     return normalizeFiatCountries(data);
   }
 
-  /** Payment methods (banks / MoMo operators) for a country. */
   /**
-   * Payment methods for a corridor. Accepts an ISO-3166 alpha-2 country ("KE")
-   * or an ISO-4217 currency ("KES") — the gateway resolves either, but they go
-   * in DIFFERENT query params. `getFiatCountries()` returns its identifier as
-   * `code`, which is a CURRENCY, so passing it through as `country=KES`
-   * silently returned `{ methods: [] }`. 2 chars → country, 3 chars → currency.
+   * @deprecated Use {@link getBanks}, which this now delegates to. Both hit
+   * `GET /api/v1/fiat/banks`; having two names for one endpoint is how the
+   * missing `sandbox` support on `getBanks` went unnoticed. Kept as an alias so
+   * existing integrations keep working.
    */
   async getFiatMethods(params = {}) {
-    const { country, currency, type, sandbox, direction = 'inbound' } = params;
-    if (!country && !currency) throw new Error('country or currency is required');
-
-    const qs = new URLSearchParams({ direction });
-    if (currency) qs.set('currency', String(currency).toUpperCase());
-    if (country) {
-      const code = String(country).toUpperCase();
-      if (!currency && code.length === 3) qs.set('currency', code);
-      else qs.set('country', code);
-    }
-    if (type) qs.set('type', type);
-    if (sandbox) qs.set('sandbox', 'true');
-    return this._get(`/api/v1/fiat/banks?${qs.toString()}`);
+    return this.getBanks(params);
   }
 
   /** Preview the local amount a customer must pay to settle a checkout amount. */
@@ -754,6 +796,261 @@ export class KuvarPayServer {
     return this._get(`/api/v1/fiat/sends/${encodeURIComponent(sendId)}`);
   }
 
+  prepareKuvarSendAccountLink({ externalUserReference, redirectUri, idempotencyKey } = {}) {
+    if (typeof externalUserReference !== 'string' || !externalUserReference || externalUserReference.length > 255) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalUserReference is required');
+    }
+    const exactRedirectUri = validateKuvarSendRedirectUri(redirectUri);
+    const state = crypto.randomBytes(32).toString('base64url');
+    const codeVerifier = crypto.randomBytes(64).toString('base64url');
+    const codeChallenge = crypto.createHash('sha256').update(codeVerifier, 'ascii').digest('base64url');
+    const retryKey = idempotencyKey || crypto.randomUUID();
+    if (typeof retryKey !== 'string' || !retryKey || retryKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    return { externalUserReference, redirectUri: exactRedirectUri, state, codeVerifier, codeChallenge, idempotencyKey: retryKey };
+  }
+
+  async createKuvarSendAccountLink(input = {}) {
+    const prepared = input.state && input.codeVerifier
+      ? Object.assign({}, input)
+      : this.prepareKuvarSendAccountLink(input);
+    const redirectUri = validateKuvarSendRedirectUri(prepared.redirectUri);
+    if (typeof prepared.externalUserReference !== 'string' || !prepared.externalUserReference || prepared.externalUserReference.length > 255) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalUserReference is required');
+    }
+    if (typeof prepared.state !== 'string' || prepared.state.length < 22 || prepared.state.length > 512
+      || /[\u0000-\u001f\u007f]/.test(prepared.state)) {
+      throw kuvarSendLinkError('INVALID_STATE', 'state is invalid');
+    }
+    if (typeof prepared.codeVerifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(prepared.codeVerifier)) {
+      throw kuvarSendLinkError('INVALID_CODE_VERIFIER', 'codeVerifier is invalid');
+    }
+    const codeChallenge = crypto.createHash('sha256').update(prepared.codeVerifier, 'ascii').digest('base64url');
+    if (prepared.codeChallenge && !equalSecretText(prepared.codeChallenge, codeChallenge)) {
+      throw kuvarSendLinkError('PKCE_MISMATCH', 'codeChallenge does not match codeVerifier');
+    }
+    if (typeof prepared.idempotencyKey !== 'string' || !prepared.idempotencyKey || prepared.idempotencyKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    const response = await this._post('/api/v1/payouts/account-link-requests', {
+      external_user_reference: prepared.externalUserReference,
+      redirect_uri: redirectUri,
+      state: prepared.state,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      scope: 'payouts:receive',
+    }, { 'Idempotency-Key': prepared.idempotencyKey });
+    const data = response?.data || response;
+    return {
+      requestId: data.id,
+      authorizationUrl: data.authorization_url,
+      expiresAt: data.expires_at,
+      state: prepared.state,
+      codeVerifier: prepared.codeVerifier,
+      redirectUri,
+      idempotencyKey: prepared.idempotencyKey,
+    };
+  }
+
+  parseKuvarSendAccountLinkCallback(callbackUrl, { expectedState, redirectUri } = {}) {
+    const exactRedirectUri = validateKuvarSendRedirectUri(redirectUri);
+    let callback;
+    try { callback = new URL(callbackUrl); } catch { throw kuvarSendLinkError('INVALID_CALLBACK', 'Callback URL is invalid'); }
+    const expected = new URL(exactRedirectUri);
+    if (callback.protocol !== expected.protocol || callback.host !== expected.host || callback.pathname !== expected.pathname
+      || callback.username || callback.password || callback.hash) {
+      throw kuvarSendLinkError('REDIRECT_URI_MISMATCH', 'Callback URL does not match redirectUri');
+    }
+    const states = callback.searchParams.getAll('state');
+    if (states.length !== 1 || !equalSecretText(states[0], expectedState)) {
+      throw kuvarSendLinkError('STATE_MISMATCH', 'Account-link callback state does not match');
+    }
+    const errors = callback.searchParams.getAll('error');
+    if (errors.length) {
+      if (errors.length !== 1 || errors[0] !== 'access_denied'
+        || callback.searchParams.getAll('code').length
+        || [...callback.searchParams.keys()].some((key) => !['error', 'state'].includes(key))) {
+        throw kuvarSendLinkError('AUTHORIZATION_ERROR', 'KuvarSend authorization failed');
+      }
+      throw kuvarSendLinkError('ACCESS_DENIED', 'The user denied KuvarSend account linking');
+    }
+    const codes = callback.searchParams.getAll('code');
+    if (codes.length !== 1 || !/^kpal_[A-Za-z0-9_-]{43}$/.test(codes[0])) {
+      throw kuvarSendLinkError('INVALID_AUTHORIZATION_CODE', 'Authorization code is missing or invalid');
+    }
+    if ([...callback.searchParams.keys()].some((key) => !['code', 'state'].includes(key))) {
+      throw kuvarSendLinkError('INVALID_CALLBACK', 'Callback URL contains unsupported parameters');
+    }
+    return { code: codes[0], state: states[0] };
+  }
+
+  async completeKuvarSendAccountLink(input = {}) {
+    if (typeof input.codeVerifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(input.codeVerifier)) {
+      throw kuvarSendLinkError('INVALID_CODE_VERIFIER', 'codeVerifier is invalid');
+    }
+    // Cross-device shape: the desktop session identifies the request directly
+    // and polls until the phone approves. No code ever crosses devices.
+    if (input.requestId != null) {
+      if (!/^alr_[0-9a-f]{32}$/.test(String(input.requestId))) {
+        throw kuvarSendLinkError('INVALID_REQUEST_ID', 'requestId is invalid');
+      }
+      const response = await this._post('/api/v1/payouts/account-links/exchange', {
+        request_id: input.requestId,
+        redirect_uri: input.redirectUri,
+        code_verifier: input.codeVerifier,
+      });
+      return response?.data || response;
+    }
+    const callback = this.parseKuvarSendAccountLinkCallback(input.callbackUrl, {
+      expectedState: input.expectedState,
+      redirectUri: input.redirectUri,
+    });
+    const response = await this._post('/api/v1/payouts/account-links/exchange', {
+      code: callback.code,
+      redirect_uri: input.redirectUri,
+      code_verifier: input.codeVerifier,
+    });
+    return response?.data || response;
+  }
+
+  /**
+   * Cross-device completion: polls `completeKuvarSendAccountLink({ requestId, … })`
+   * while the request is still pending, so a desktop session finishes on its own
+   * the moment the user approves in KuvarSend. Resolves with the linked account.
+   */
+  async waitForKuvarSendAccountLink({
+    requestId,
+    redirectUri,
+    codeVerifier,
+    pollMs = 3000,
+    timeoutMs = 10 * 60 * 1000,
+  } = {}) {
+    if (!/^alr_[0-9a-f]{32}$/.test(String(requestId || ''))) {
+      throw kuvarSendLinkError('INVALID_REQUEST_ID', 'requestId is invalid');
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      try {
+        return await this.completeKuvarSendAccountLink({ requestId, redirectUri, codeVerifier });
+      } catch (error) {
+        // The gateway answers 409 AUTHORIZATION_NOT_READY while approval is
+        // pending (err.body carries the JSON). Anything else is real.
+        const notReady = error?.body?.code === 'AUTHORIZATION_NOT_READY'
+          || error?.code === 'AUTHORIZATION_NOT_READY';
+        if (!notReady) throw error;
+        if (Date.now() >= deadline) {
+          throw kuvarSendLinkError('AUTHORIZATION_LINK_TIMEOUT', 'The account-link request was not approved in time.');
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.max(250, pollMs)));
+    }
+  }
+
+  async getKuvarSendAccountLink(linkedAccountId) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const response = await this._get(`/api/v1/payouts/account-links/${encodeURIComponent(linkedAccountId)}`);
+    return response?.data || response;
+  }
+
+  async listKuvarSendAccountLinks({ status, limit = 50, cursor } = {}) {
+    if (status != null && !['ACTIVE', 'REVOKED'].includes(status)) {
+      throw kuvarSendLinkError('INVALID_STATUS', 'status must be ACTIVE or REVOKED');
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw kuvarSendLinkError('INVALID_LIMIT', 'limit must be an integer from 1 to 100');
+    }
+    if (cursor != null && !/^kal_[0-9a-f]{32}$/.test(String(cursor))) {
+      throw kuvarSendLinkError('INVALID_CURSOR', 'cursor is invalid');
+    }
+    const query = new URLSearchParams();
+    if (status) query.set('status', status);
+    query.set('limit', String(limit));
+    if (cursor) query.set('cursor', cursor);
+    return this._get(`/api/v1/payouts/account-links?${query}`);
+  }
+
+  async createKuvarSendPayout({ linkedAccountId, amount, currency, externalReference, idempotencyKey } = {}) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const exactAmount = String(amount ?? '');
+    if (!/^\d+(?:\.\d+)?$/.test(exactAmount) || exactAmount.length > 80) {
+      throw kuvarSendLinkError('INVALID_AMOUNT', 'amount must be a positive decimal string');
+    }
+    const exactCurrency = String(currency || '').toUpperCase();
+    if (!/^[A-Z]{3,5}$/.test(exactCurrency)) {
+      throw kuvarSendLinkError('INVALID_CURRENCY', 'currency must be a 3-5 letter code');
+    }
+    if (externalReference != null && (typeof externalReference !== 'string' || !externalReference || externalReference.length > 255)) {
+      throw kuvarSendLinkError('INVALID_EXTERNAL_REFERENCE', 'externalReference must be 1-255 characters');
+    }
+    if (typeof idempotencyKey !== 'string' || !idempotencyKey || idempotencyKey.length > 255) {
+      throw kuvarSendLinkError('INVALID_IDEMPOTENCY_KEY', 'idempotencyKey must be 1-255 characters');
+    }
+    const response = await this._post('/api/v1/payouts/kuvarsend', {
+      linked_account_id: linkedAccountId,
+      amount: exactAmount,
+      currency: exactCurrency,
+      ...(externalReference ? { external_reference: externalReference } : {}),
+    }, { 'Idempotency-Key': idempotencyKey });
+    return response?.data || response;
+  }
+
+  async quoteKuvarSendPayout({ linkedAccountId, amount, currency } = {}) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const exactAmount = String(amount ?? '');
+    if (!/^\d+(?:\.\d+)?$/.test(exactAmount) || exactAmount.length > 80) {
+      throw kuvarSendLinkError('INVALID_AMOUNT', 'amount must be a positive decimal string');
+    }
+    const exactCurrency = String(currency || '').toUpperCase();
+    if (!/^[A-Z]{3,5}$/.test(exactCurrency)) {
+      throw kuvarSendLinkError('INVALID_CURRENCY', 'currency must be a 3-5 letter code');
+    }
+    const response = await this._post('/api/v1/payouts/kuvarsend/quote', {
+      linked_account_id: linkedAccountId,
+      amount: exactAmount,
+      currency: exactCurrency,
+    });
+    return response?.data || response;
+  }
+
+  async getKuvarSendPayout(payoutId) {
+    if (!/^kwp_[0-9a-f]{32}$/.test(String(payoutId || ''))) {
+      throw kuvarSendLinkError('INVALID_PAYOUT_ID', 'payoutId is invalid');
+    }
+    const response = await this._get(`/api/v1/payouts/kuvarsend/${encodeURIComponent(payoutId)}`);
+    return response?.data || response;
+  }
+  async listKuvarSendPayouts({ linkedAccountId, limit = 50, cursor } = {}) {
+    if (linkedAccountId != null && !/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw kuvarSendLinkError('INVALID_LIMIT', 'limit must be an integer from 1 to 100');
+    }
+    if (cursor != null && !/^kwp_[0-9a-f]{32}$/.test(String(cursor))) {
+      throw kuvarSendLinkError('INVALID_CURSOR', 'cursor is invalid');
+    }
+    const query = new URLSearchParams();
+    if (linkedAccountId) query.set('linked_account_id', linkedAccountId);
+    query.set('limit', String(limit));
+    if (cursor) query.set('cursor', cursor);
+    return this._get(`/api/v1/payouts/kuvarsend?${query}`);
+  }
+
+  async revokeKuvarSendAccountLink(linkedAccountId) {
+    if (!/^kal_[0-9a-f]{32}$/.test(String(linkedAccountId || ''))) {
+      throw kuvarSendLinkError('INVALID_LINKED_ACCOUNT_ID', 'linkedAccountId is invalid');
+    }
+    const response = await this._delete(`/api/v1/payouts/account-links/${encodeURIComponent(linkedAccountId)}`);
+    return response?.data || response;
+  }
+
   // --- Sandbox Simulator ---
 
   async startSandboxSimulator() {
@@ -830,4 +1127,4 @@ export class KuvarPayServer {
   async renewSubscription(subscriptionId, body = {}) {
     return this._post(`/api/v1/subscriptions/${encodeURIComponent(subscriptionId)}/renew`, body);
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuvarpay/sdk",
-  "version": "1.6.0",
+  "version": "1.9.0",
   "description": "Official KuvarPay Server SDK for Node.js",
   "main": "index.js",
   "module": "index.mjs",
@@ -23,6 +23,8 @@
     "kuvarpay",
     "blockchain",
     "fiat-payout",
+    "kuvarsend",
+    "account-linking",
     "split-payments"
   ],
   "publishConfig": {