@kuvarpay/sdk 1.4.2 → 1.6.0

package/index.mjs

@@ -13,6 +13,45 @@ const DEFAULT_BASE = (process.env.KUVARPAY_API_BASE_URL
   || 'https://payment.kuvarpay.com'
 ).replace(/\/$/, '');
 
+/**
+ * Decode an ISO-3166 alpha-2 code from a flag emoji. Flags are two regional
+ * indicator symbols (U+1F1E6 = 'A'), so this is an exact inverse, not a guess.
+ */
+function iso2FromFlag(flag) {
+  if (typeof flag !== 'string') return null;
+  const points = Array.from(flag).map((ch) => ch.codePointAt(0));
+  if (points.length !== 2) return null;
+  const letters = points.map((cp) =>
+    cp >= 0x1f1e6 && cp <= 0x1f1ff ? String.fromCharCode(65 + (cp - 0x1f1e6)) : null
+  );
+  return letters.every(Boolean) ? letters.join('') : null;
+}
+
+/**
+ * Guarantee a `countryCode` (ISO-2) on every corridor.
+ *
+ * `/send/countries` returns `code` as a CURRENCY and `country` as a display
+ * name, so neither is the ISO-2 that `/fiat/banks?country=` and the FIAT rail
+ * on `/transactions/create` require. Newer gateways return `countryCode`
+ * directly; for older ones we recover it from the flag emoji.
+ */
+function normalizeFiatCountries(data) {
+  const list = data && Array.isArray(data.countries) ? data.countries : null;
+  if (!list) return data;
+  return Object.assign({}, data, {
+    countries: list.map((entry) => {
+      if (!entry || typeof entry !== 'object') return entry;
+      const declared = typeof entry.countryCode === 'string' ? entry.countryCode.toUpperCase() : null;
+      const fromCountry = /^[A-Za-z]{2}$/.test(String(entry.country || ''))
+        ? String(entry.country).toUpperCase()
+        : null;
+      return Object.assign({}, entry, {
+        countryCode: declared || fromCountry || iso2FromFlag(entry.flag) || null,
+      });
+    }),
+  });
+}
+
 export class KuvarPayServer {
   /**
    * @param {Object} config
@@ -65,7 +104,14 @@ export class KuvarPayServer {
       let json;
       try { json = text ? JSON.parse(text) : null; } catch (e) { json = null; }
       if (!res.ok) {
-        const msg = (json && (json.error || json.message)) || `HTTP ${res.status}`;
+        // The gateway returns errors as either { error: 'msg' }, { message: 'msg' },
+        // or { error: { code, message, status } }. Flatten to a readable string so
+        // err.message is never '[object Object]'. Full payload stays on err.body.
+        const errField = json && json.error;
+        const msg =
+          (errField && typeof errField === 'object' ? (errField.message || errField.code) : errField) ||
+          (json && json.message) ||
+          `HTTP ${res.status}`;
         const err = new Error(msg);
         err.status = res.status;
         err.body = json || text;
@@ -86,17 +132,36 @@ export class KuvarPayServer {
     return this._request('POST', path, body, extraHeaders);
   }
 
+  async _patch(path, body, extraHeaders = {}) {
+    return this._request('PATCH', path, body, extraHeaders);
+  }
+
   /**
    * Signature Verification for Webhooks
-   * @param {string|Buffer} payload - Raw request body
+   *
+   * The gateway sends `X-KuvarPay-Signature: sha256=<hex>`. The prefix is
+   * stripped here, and bare-hex signatures still verify, so this works
+   * whichever format the header arrives in.
+   *
+   * Always returns a boolean — never throws. A handler that throws on a bad
+   * signature returns 5xx, which the gateway treats as a failed delivery and
+   * retries, so malformed input must fail closed rather than blow up.
+   *
+   * @param {string|Buffer} payload - Raw request body (pre-JSON.parse)
    * @param {string} signature - Value from X-KuvarPay-Signature header
    * @param {string} secret - Your Webhook Secret from the dashboard
+   * @returns {boolean}
    */
   verifyWebhookSignature(payload, signature, secret) {
-    if (!signature || !secret) return false;
-    const hmac = crypto.createHmac('sha256', secret);
-    const digest = hmac.update(payload).digest('hex');
-    return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
+    if (!signature || typeof signature !== 'string' || !secret) return false;
+    const received = signature.startsWith('sha256=') ? signature.slice(7) : signature;
+    const digest = crypto.createHmac('sha256', secret).update(payload).digest('hex');
+    // Decoding as hex is case-insensitive and silently truncates on any
+    // non-hex character, so the length check below also rejects junk input.
+    const expectedBuf = Buffer.from(digest, 'hex');
+    const receivedBuf = Buffer.from(received, 'hex');
+    if (receivedBuf.length !== expectedBuf.length) return false;
+    return crypto.timingSafeEqual(expectedBuf, receivedBuf);
   }
 
   async getSessionStatus(sessionId) {
@@ -105,11 +170,24 @@ export class KuvarPayServer {
     }
     const data = await this._get(`/api/v1/checkout-sessions/${encodeURIComponent(sessionId)}`);
     const status = data?.status || data?.checkoutSession?.status || data?.data?.status;
-    const transactionId = data?.transactionId || data?.data?.transactionId || null;
+    // The transaction may be exposed either as a flat `transactionId` or, for
+    // fiat/crypto checkouts, nested in a `transactions` array on the session
+    // body — fall back through both so this is populated for fiat sessions too.
+    const transactionId = data?.transactionId
+      || data?.data?.transactionId
+      || data?.data?.transactions?.[0]?.id
+      || data?.transactions?.[0]?.id
+      || null;
+    // Fiat checkouts: the linked deposit projection (depositId, status,
+    // nextAction, paymentInstructions, quote) is attached to the session so a
+    // server-side/headless integrator can recover it by polling — no browser
+    // SSE required. Null for crypto checkouts or before a fiat tx is created.
+    const fiatDeposit = data?.data?.fiatDeposit ?? data?.fiatDeposit ?? null;
     return {
       sessionId: data?.id || data?.sessionId || sessionId,
       status,
       transactionId,
+      fiatDeposit,
       metadata: data?.metadata || data?.checkoutSession?.metadata || data?.data?.metadata || null,
       raw: data,
     };
@@ -120,14 +198,33 @@ export class KuvarPayServer {
       throw new Error('transactionId is required');
     }
     const data = await this._get(`/api/v1/transactions/${encodeURIComponent(transactionId)}`);
+    // The gateway wraps the transaction in a `{ success, data }` envelope, so
+    // read fields off `data.data` (falling back to the root for older shapes).
+    const body = data?.data || data;
     return {
-      transactionId: data?.id || transactionId,
-      status: data?.status,
-      metadata: data?.metadata || data?.data?.metadata || null,
+      transactionId: body?.id || transactionId,
+      status: body?.status,
+      metadata: body?.metadata || data?.metadata || null,
       raw: data,
     };
   }
 
+  /**
+   * Update a transaction's status
+   * PATCH /api/v1/transactions/{id}/status
+   */
+  async updateTransactionStatus(transactionId, data) {
+    return this._patch(`/api/v1/transactions/${encodeURIComponent(transactionId)}/status`, data);
+  }
+
+  /**
+   * Simulate a payment (Sandbox only)
+   * POST /api/v1/transactions/{id}/demo-pay
+   */
+  async demoPay(transactionId) {
+    return this._post(`/api/v1/transactions/${encodeURIComponent(transactionId)}/demo-pay`, {});
+  }
+
   async getTransactionStatusByReference(reference) {
     if (!reference) throw new Error('reference is required');
     return this._get(`/api/v1/transactions/status/${encodeURIComponent(reference)}`);
@@ -212,15 +309,18 @@ export class KuvarPayServer {
       fromNetwork: data.fromNetwork,
       description: data.description,
       metadata: data.metadata,
+      // FIAT rail context. The gateway hard-rejects a FIAT transaction with no
+      // country, so these must be forwarded — dropping them silently produced
+      // `400 country is required for FIAT transactions`. For a fiat collection
+      // prefer createFiatPayment(), which also waits for the deposit.
+      ...(data.country ? { country: data.country } : {}),
+      ...(data.methodId ? { methodId: data.methodId } : {}),
+      ...(data.phone ? { phone: data.phone } : {}),
     };
 
     return this.createTransaction(transactionData);
   }
 
-  async sendInvoiceEmail(sessionId) {
-    return this._post(`/api/v1/invoices/${encodeURIComponent(sessionId)}/send-email`, {});
-  }
-
   // --- Subaccount Management ---
 
   async createSubaccount(subaccountData) {
@@ -306,33 +406,352 @@ export class KuvarPayServer {
   }
 
   /**
-   * List supported banks
-   * GET /api/v1/banks or GET /api/v1/banks/:currency
-   * @param {string|Object} [params] - Currency string or params object { currency, type, country }
-   * @param {Object} [options] - Additional query params if first arg is currency string
+   * List supported payment methods (banks / mobile-money operators) for a
+   * corridor, from the fiat gateway. Returns ONLY the corridor's primary-rail
+   * methods (e.g. an NGN corridor routed via Yellow Card returns YC methods
+   * only), each as an opaque `methodId`.
+   *
+   * Pass EITHER `country` (ISO-3166 alpha-2, e.g. 'NG') OR `currency`
+   * (ISO-4217, e.g. 'NGN') — a currency is resolved to its corridor country
+   * server-side, and when both are given `currency` further filters the list.
+   * A bare string is treated as a currency for backward compatibility.
+   * GET /api/v1/fiat/banks
+   * @param {string|Object} params - Currency string, or { country?, currency?, type?, direction? }
+   * @param {Object} [options] - Extra params when the first arg is a currency string
+   * @returns {Promise<{ methods: Array<{ methodId: string, name: string, currency: string, type: 'bank'|'mobile_money' }> }>}
    */
   async getBanks(params = {}, options = {}) {
-    // Handle (currency, options) signature
-    if (typeof params === 'string') {
-      const query = new URLSearchParams(options).toString();
-      const path = query ? `/api/v1/banks/${encodeURIComponent(params)}?${query}` : `/api/v1/banks/${encodeURIComponent(params)}`;
-      return this._get(path);
+    // Back-compat: getBanks('NGN', { type }) → treat the string as a currency.
+    if (typeof params === 'string') params = Object.assign({ currency: params }, options);
+    // Default to the collection (deposit) rail — getBanks is used to populate a
+    // checkout's "pay with" method picker. Pass direction:'outbound' for payout
+    // (settlement) methods.
+    const { country, currency, type, direction = 'inbound' } = params || {};
+    if (!country && !currency) throw new Error('country or currency is required');
+    const qs = new URLSearchParams();
+    if (country) qs.set('country', country);
+    if (currency) qs.set('currency', currency);
+    if (type) qs.set('type', type);
+    if (direction) qs.set('direction', direction);
+    return this._get(`/api/v1/fiat/banks?${qs.toString()}`);
+  }
+
+  /**
+   * @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 { currency, ...rest } = params || {};
-    if (currency) {
-      const query = new URLSearchParams(rest).toString();
-      const path = query ? `/api/v1/banks/${encodeURIComponent(currency)}?${query}` : `/api/v1/banks/${encodeURIComponent(currency)}`;
-      return this._get(path);
+    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) ---
+
+  /** Supported fiat collection corridors (public). GET /api/v1/send/countries */
+  async getFiatCountries() {
+    const data = await this._get('/api/v1/send/countries');
+    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.
+   */
+  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()}`);
+  }
 
-    const query = new URLSearchParams(rest).toString();
-    const path = query ? `/api/v1/banks?${query}` : '/api/v1/banks';
-    return this._get(path);
+  /** Preview the local amount a customer must pay to settle a checkout amount. */
+  async getFiatCheckoutQuote(params = {}) {
+    const { amount, baseCurrency, currency, country } = params;
+    if (!amount || !baseCurrency || !currency || !country) {
+      throw new Error('amount, baseCurrency, currency and country are required');
+    }
+    const qs = new URLSearchParams({
+      amount: String(amount), baseCurrency, currency, country,
+    });
+    return this._get(`/api/v1/fiat/checkout-quote?${qs.toString()}`);
   }
 
-  async resolveBankAccount(data) {
-    return this._post('/api/v1/banks/resolve', data);
+  /**
+   * Create a FIAT collection transaction on a checkout session (async — the
+   * deposit projection arrives on getSessionStatus().raw.data.fiatDeposit).
+   */
+  async createFiatTransaction(data = {}) {
+    const { checkoutSessionId, fromCurrency, country } = data;
+    if (!checkoutSessionId || !fromCurrency || !country) {
+      throw new Error('checkoutSessionId, fromCurrency and country are required');
+    }
+    return this._post('/api/v1/transactions/create', {
+      ...data,
+      fromNetwork: 'FIAT',
+    });
+  }
+
+  /** Poll a fiat deposit (public; self-healing reconcile server-side). */
+  async getFiatDeposit(depositId) {
+    if (!depositId) throw new Error('depositId is required');
+    return this._get(`/api/v1/fiat/deposits/${encodeURIComponent(depositId)}`);
+  }
+
+  /** Drive the next required step on a fiat deposit (CONFIRM_QUOTE / SUBMIT_OTP). */
+  async submitFiatDepositAction(depositId, action, otp) {
+    if (!depositId) throw new Error('depositId is required');
+    if (!action) throw new Error('action is required');
+    return this._post(`/api/v1/fiat/deposits/${encodeURIComponent(depositId)}/action`, {
+      action, ...(otp ? { otp } : {}),
+    });
+  }
+
+  /** SANDBOX-ONLY: force-complete a stuck fiat deposit. */
+  async simulateFiatDepositComplete(depositId) {
+    if (!depositId) throw new Error('depositId is required');
+    return this._post(`/api/v1/fiat/deposits/${encodeURIComponent(depositId)}/simulate-complete`, {});
+  }
+
+  /**
+   * Wait for the fiat deposit projection to appear on a checkout session.
+   * Bounded deadline + backoff, so a stalled worker times out cleanly instead
+   * of spinning. Pass `until` to wait for a different state (e.g. CREDITED).
+   * Throws an Error with code `FIAT_DEPOSIT_TIMEOUT` on expiry.
+   */
+  async waitForFiatDeposit(sessionId, options = {}) {
+    if (!sessionId) throw new Error('sessionId is required');
+    const {
+      timeoutMs = 30000,
+      pollIntervalMs = 1000,
+      maxIntervalMs = 5000,
+      until,
+    } = options;
+    const isReady = typeof until === 'function'
+      ? until
+      : (d) => Boolean(d && d.depositId);
+
+    const deadline = Date.now() + timeoutMs;
+    let interval = pollIntervalMs;
+    let lastDeposit = null;
+
+    for (;;) {
+      let deposit = null;
+      try {
+        const session = await this.getSessionStatus(sessionId);
+        deposit = session.fiatDeposit || null;
+      } catch (err) {
+        if (Date.now() >= deadline) throw err;
+      }
+
+      if (deposit) lastDeposit = deposit;
+      if (deposit && isReady(deposit)) return deposit;
+
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        const err = new Error(
+          `Timed out after ${timeoutMs}ms waiting for the fiat deposit on session ${sessionId}`
+        );
+        err.code = 'FIAT_DEPOSIT_TIMEOUT';
+        err.sessionId = sessionId;
+        err.lastDeposit = lastDeposit;
+        throw err;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, Math.min(interval, remaining)));
+      interval = Math.min(Math.ceil(interval * 1.5), maxIntervalMs);
+    }
+  }
+
+  /**
+   * One-shot local-currency collection: session + fiat transaction + wait for
+   * the deposit. Stops at the quote — confirming locks the FX rate and fires
+   * the customer's prompt, and instructions are withheld until it happens.
+   * Completion arrives on the `payment.confirmed` webhook, as with crypto.
+   */
+  async createFiatPayment(data = {}) {
+    const {
+      amount, currency, description, customerEmail, customerName,
+      redirectUrl, callbackUrl, expiresIn, metadata, subaccount,
+      split_code, splitCode,
+      fromCurrency, country, methodId, phone,
+      waitForDeposit = true,
+      autoConfirmQuote = false,
+      timeoutMs, pollIntervalMs,
+    } = data;
+
+    if (!fromCurrency) throw new Error('fromCurrency is required');
+    if (!country) throw new Error('country is required');
+
+    const session = await this.createCheckoutSession({
+      amount, currency, description, customerEmail, customerName,
+      redirectUrl, callbackUrl, expiresIn, metadata, subaccount,
+      split_code: split_code || splitCode,
+    });
+
+    const transaction = await this.createFiatTransaction({
+      checkoutSessionId: session.sessionId,
+      fromCurrency, country, methodId, phone,
+      customerEmail, customerName, description, metadata,
+    });
+
+    const result = {
+      sessionId: session.sessionId,
+      transactionId: transaction?.data?.transactionId ?? transaction?.transactionId ?? null,
+      depositId: null,
+      nextAction: null,
+      quote: null,
+      paymentInstructions: null,
+      deposit: null,
+      session: session.raw,
+      transaction,
+    };
+
+    if (!waitForDeposit) return result;
+
+    let deposit = await this.waitForFiatDeposit(session.sessionId, { timeoutMs, pollIntervalMs });
+
+    if (autoConfirmQuote && deposit.nextAction === 'CONFIRM_QUOTE') {
+      // CONFIRM_QUOTE echoes the fresh projection back, including the
+      // paymentInstructions that were withheld pre-confirm — so use it
+      // directly and skip a round-trip. Only re-read if the response came
+      // back without instructions (e.g. a provider that defers them).
+      const confirmed = await this.submitFiatDepositAction(deposit.depositId, 'CONFIRM_QUOTE');
+      if (confirmed && confirmed.paymentInstructions) {
+        deposit = { ...deposit, ...confirmed };
+      } else {
+        try {
+          deposit = await this.getFiatDeposit(deposit.depositId);
+        } catch (err) {
+          /* keep the pre-confirm deposit rather than losing it */
+        }
+      }
+    }
+
+    result.deposit = deposit;
+    result.depositId = deposit?.depositId ?? null;
+    result.nextAction = deposit?.nextAction ?? null;
+    result.quote = deposit?.quote ?? null;
+    result.paymentInstructions = deposit?.paymentInstructions ?? null;
+    return result;
+  }
+
+  // --- Payouts (Sends) — SECRET key only ---
+  //
+  // These move money OUT of your USD balance. The gateway requires a SECRET
+  // API key here and rejects client/publishable keys, so payouts must only
+  // ever run server-side. ownerType/ownerId default to your business
+  // (MERCHANT). Payouts complete asynchronously — listen for the webhook
+  // (verify it with verifyWebhookSignature) rather than polling.
+
+  /**
+   * Verify (resolve) a payout recipient's name before sending.
+   * POST /api/v1/fiat/resolve-recipient
+   * @param {Object} data
+   * @param {string} data.methodId - Payout method id (bank / MoMo operator).
+   * @param {string} [data.accountNumber] - Bank account number.
+   * @param {string} [data.phone] - Wallet / mobile-money phone.
+   */
+  async resolveRecipient(data = {}) {
+    const { methodId, accountNumber, phone } = data;
+    if (!methodId) throw new Error('methodId is required');
+    if (!accountNumber && !phone) throw new Error('accountNumber or phone is required');
+    return this._post('/api/v1/fiat/resolve-recipient', { methodId, accountNumber, phone });
+  }
+
+  /**
+   * Initiate a fiat payout (bank / mobile money) debited from your USD balance.
+   * Provide EXACTLY ONE amount side: `sourceAmountUsd` (USD-input — the
+   * recipient's local floats) OR `destinationAmount` (recipient receives this
+   * exact local amount; USD locked at confirm).
+   * POST /api/v1/fiat/sends
+   * @param {Object} data
+   * @param {string} data.destinationCountry - ISO country (e.g. 'NG', 'KE').
+   * @param {string} data.destinationCurrency - Local currency (e.g. 'NGN').
+   * @param {Object} data.recipient - { methodId, accountNumber?, accountName?, phone?, manualInput? }
+   * @param {number} [data.sourceAmountUsd]
+   * @param {number} [data.destinationAmount]
+   * @param {string} [data.narration]
+   * @param {Object} [data.metadata]
+   * @param {string} [data.ownerType='MERCHANT']
+   * @param {string} [data.ownerId] - defaults to your businessId.
+   * @returns {Promise<{sendId:string}>}
+   */
+  async createFiatSend(data = {}) {
+    const { destinationCountry, destinationCurrency, recipient, sourceAmountUsd, destinationAmount } = data;
+    if (!destinationCountry || !destinationCurrency) {
+      throw new Error('destinationCountry and destinationCurrency are required');
+    }
+    if (!recipient || !recipient.methodId) throw new Error('recipient.methodId is required');
+    if (sourceAmountUsd == null && destinationAmount == null) {
+      throw new Error('Provide exactly one of sourceAmountUsd or destinationAmount');
+    }
+    const payload = {
+      ownerType: data.ownerType || 'MERCHANT',
+      ownerId: data.ownerId || this.businessId,
+      destinationCountry,
+      destinationCurrency,
+      recipient,
+      ...(sourceAmountUsd != null ? { sourceAmountUsd } : {}),
+      ...(destinationAmount != null ? { destinationAmount } : {}),
+      ...(data.depositId ? { depositId: data.depositId } : {}),
+      ...(data.narration ? { narration: data.narration } : {}),
+      ...(data.metadata ? { metadata: data.metadata } : {}),
+    };
+    return this._post('/api/v1/fiat/sends', payload);
+  }
+
+  /**
+   * Poll a fiat payout (send) status. Owner-scoped to your business.
+   * Payouts settle asynchronously; prefer the completion webhook, but this is
+   * useful for server-side reconciliation (and sandbox, where there may be no
+   * public webhook endpoint).
+   * GET /api/v1/fiat/sends/:id
+   * @param {string} sendId
+   * @returns {Promise<{ sendId: string, status: string, sourceAmountUsd: number, destinationCountry: string, destinationCurrency: string, destinationAmount: number|null, settledAt: string|null, createdAt: string, updatedAt: string }>}
+   */
+  async getFiatSend(sendId) {
+    if (!sendId) throw new Error('sendId is required');
+    return this._get(`/api/v1/fiat/sends/${encodeURIComponent(sendId)}`);
   }
 
   // --- Sandbox Simulator ---
@@ -396,8 +815,16 @@ export class KuvarPayServer {
     return this._post('/api/v1/subscriptions/relay/revokeAuth', body);
   }
 
-  async createRenewalCheckoutSession(body) {
-    return this._post('/api/v1/subscriptions/renewal-checkout-sessions', body);
+  /**
+   * Create a renewal checkout session for an existing subscription.
+   * POST /api/v1/subscriptions/{subscriptionId}/renew
+   * @param {Object} body - { subscriptionId | id, ...renewalOptions }
+   */
+  async createRenewalCheckoutSession(body = {}) {
+    const { subscriptionId, id, ...rest } = body;
+    const target = subscriptionId || id;
+    if (!target) throw new Error('subscriptionId is required');
+    return this._post(`/api/v1/subscriptions/${encodeURIComponent(target)}/renew`, rest);
   }
 
   async renewSubscription(subscriptionId, body = {}) {

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@kuvarpay/sdk",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "Official KuvarPay Server SDK for Node.js",
   "main": "index.js",
   "module": "index.mjs",
   "types": "index.d.ts",
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "index.js",
     "index.mjs",
@@ -27,4 +30,4 @@
   },
   "author": "KuvarPay Team",
   "license": "MIT"
-}
+}