@kuvarpay/sdk 1.5.0 → 1.7.0

package/README.md

@@ -95,8 +95,8 @@ 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). |
-| `resolveBankAccount(data)` | Verify bank account names before creating subaccounts. |
+| `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). Set `sandbox: true` when your key is a sandbox-mode business — live and sandbox are separate `methodId` spaces. |
+| `resolveBankAccount(data)` | **Deprecated** alias for `resolveRecipient` — takes `methodId`, not `bank_code`. |
 
 ### 🌍 Fiat Collection (Pay with Local Currency)
 
@@ -104,7 +104,7 @@ The SDK defaults to the KuvarPay Production API (`https://payment.kuvarpay.com`)
 | :--- | :--- |
 | **`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 +117,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,14 +172,14 @@ 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 { methods } = await kv.getBanks({ 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.

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>;
 }
@@ -234,9 +240,37 @@ 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 }> }>;
-  resolveBankAccount(data: { bank_code: string; account_number: string; country_code?: string }): Promise<any>;
+  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`.
+   *
+   * The legacy `/api/v1/banks/resolve` endpoint was retired; passing `bank_code`
+   * now throws. Supply `methodId` from `getBanks({ direction: 'outbound' })`.
+   */
+  resolveBankAccount(data: {
+    methodId?: string;
+    method_id?: string;
+    accountNumber?: string;
+    account_number?: string;
+    phone?: string;
+  }): Promise<{
+    supported: boolean;
+    resolved: boolean;
+    accountName: string | null;
+    bankName?: string;
+    reason?: string | null;
+    /** Legacy alias for `accountName`. */
+    account_name: string | null;
+    /** Echo of the submitted account number. */
+    account_number: string | null;
+  }>;
 
   // Fiat collection (Pay with Local Currency)
   /**
@@ -253,6 +287,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: {

package/index.js

@@ -64,10 +64,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);
 
@@ -540,21 +546,62 @@ 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()}`);
   }
 
   /**
-   * Resolve bank account name
-   * POST /api/v1/banks/resolve
-   * @param {Object} data - { bank_code, account_number, country_code? }
+   * Resolve a bank / mobile-money account name.
+   *
+   * @deprecated Use {@link resolveRecipient}. Kept as a thin alias so existing
+   * integrations keep working.
+   *
+   * The legacy `POST /api/v1/banks/resolve` endpoint (which took a raw
+   * `bank_code`) has been retired — calling it now 404s. Name enquiry runs
+   * through `POST /api/v1/fiat/resolve-recipient`, which is keyed off the opaque
+   * `methodId` from `getBanks()`.
+   *
+   * @param {Object} data - { methodId | method_id, accountNumber | account_number, phone }
    */
-  async resolveBankAccount(data) {
-    return this._post('/api/v1/banks/resolve', data);
+  async resolveBankAccount(data = {}) {
+    const methodId = data.methodId || data.method_id;
+    const accountNumber = data.accountNumber || data.account_number;
+    const phone = data.phone;
+
+    if (!methodId) {
+      throw new Error(
+        (data.bank_code || data.bankCode)
+          ? 'resolveBankAccount no longer accepts bank_code — the legacy /api/v1/banks endpoints were retired. ' +
+            'Pass methodId from getBanks({ country, direction: "outbound" }) instead, or call resolveRecipient() directly.'
+          : 'methodId is required (get one from getBanks({ country, direction: "outbound" }))'
+      );
+    }
+
+    const result = await this.resolveRecipient({ methodId, accountNumber, phone });
+    return Object.assign({}, result, {
+      account_name: result && result.accountName != null ? result.accountName : null,
+      account_number: accountNumber != null ? accountNumber : null,
+    });
   }
 
   // --- Fiat collection (Pay with Local Currency) ---
@@ -581,21 +628,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);
   }
 
   /**

package/index.mjs

@@ -61,10 +61,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);
 
@@ -428,16 +434,64 @@ 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()}`);
   }
 
-  async resolveBankAccount(data) {
-    return this._post('/api/v1/banks/resolve', data);
+  /**
+   * @deprecated Use {@link resolveRecipient}. Kept as a thin alias so existing
+   * integrations keep working.
+   *
+   * The legacy `POST /api/v1/banks/resolve` endpoint (which took a raw
+   * `bank_code`) has been retired — calling it now 404s. Name enquiry runs
+   * through `POST /api/v1/fiat/resolve-recipient`, which is keyed off the opaque
+   * `methodId` from `getBanks()`.
+   *
+   * Accepts either the new field names or the legacy snake_case ones:
+   *   { methodId | method_id, accountNumber | account_number, phone }
+   *
+   * Returns the resolveRecipient shape ({ supported, resolved, accountName, … })
+   * plus `account_name` / `account_number` aliases for older call sites.
+   */
+  async resolveBankAccount(data = {}) {
+    const methodId = data.methodId || data.method_id;
+    const accountNumber = data.accountNumber || data.account_number;
+    const phone = data.phone;
+
+    if (!methodId) {
+      throw new Error(
+        (data.bank_code || data.bankCode)
+          ? 'resolveBankAccount no longer accepts bank_code — the legacy /api/v1/banks endpoints were retired. ' +
+            'Pass methodId from getBanks({ country, direction: "outbound" }) instead, or call resolveRecipient() directly.'
+          : 'methodId is required (get one from getBanks({ country, direction: "outbound" }))'
+      );
+    }
+
+    const result = await this.resolveRecipient({ methodId, accountNumber, phone });
+    return Object.assign({}, result, {
+      account_name: result && result.accountName != null ? result.accountName : null,
+      account_number: accountNumber != null ? accountNumber : null,
+    });
   }
 
   // --- Fiat collection (Pay with Local Currency) ---
@@ -448,28 +502,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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuvarpay/sdk",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Official KuvarPay Server SDK for Node.js",
   "main": "index.js",
   "module": "index.mjs",
@@ -30,4 +30,4 @@
   },
   "author": "KuvarPay Team",
   "license": "MIT"
-}
+}