@kuvarpay/sdk 1.4.2 → 1.5.0

package/index.js

@@ -15,6 +15,46 @@ 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. Everything else
+ * on the payload is passed through untouched.
+ */
+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,
+      });
+    }),
+  });
+}
+
 class KuvarPayServer {
   /**
    * @param {Object} config
@@ -67,7 +107,14 @@ 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;
@@ -88,6 +135,10 @@ class KuvarPayServer {
     return this._request('POST', path, body, extraHeaders);
   }
 
+  async _patch(path, body, extraHeaders = {}) {
+    return this._request('PATCH', path, body, extraHeaders);
+  }
+
   /**
    * Fetch checkout session status by sessionId
    * GET {Payment API Base}/api/v1/checkout-sessions/{sessionId}
@@ -96,15 +147,30 @@ class KuvarPayServer {
    */
   /**
    * 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) {
@@ -113,11 +179,24 @@ 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,
     };
@@ -134,10 +213,13 @@ 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,
     };
   }
@@ -275,7 +357,7 @@ class KuvarPayServer {
 
     const session = await this.createCheckoutSession(sessionData);
 
-    // 2. Create Transaction using the session. We omit toAmount/toCurrency 
+    // 2. Create Transaction using the session. We omit toAmount/toCurrency
     // to let the API use the values already locked into the session.
     const transactionData = {
       checkoutSessionId: session.sessionId,
@@ -283,18 +365,18 @@ 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);
   }
 
-  /**
-   * Email an invoice to a customer
-   */
-  async sendInvoiceEmail(sessionId) {
-    return this._post(`/api/v1/invoices/${encodeURIComponent(sessionId)}/send-email`, {});
-  }
-
   // --- Subaccount Management ---
 
   /**
@@ -436,29 +518,34 @@ class KuvarPayServer {
   // --- Banks & Account Verification ---
 
   /**
-   * 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);
-    }
-
-    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 query = new URLSearchParams(rest).toString();
-    const path = query ? `/api/v1/banks?${query}` : '/api/v1/banks';
-    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()}`);
   }
 
   /**
@@ -470,6 +557,349 @@ class KuvarPayServer {
     return this._post('/api/v1/banks/resolve', data);
   }
 
+  // --- 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 corridor.
+   * GET /api/v1/fiat/banks?country=KE&type=mobile_money&direction=inbound
+   *
+   * 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 corridor identifier as `code`,
+   * which is a CURRENCY, so passing that straight through as `country=KES`
+   * silently returned `{ methods: [] }`. Route by length instead: 2 chars →
+   * country, 3 chars → currency. Pass `currency` explicitly to be unambiguous.
+   *
+   * @param {Object} params - { country?, currency?, type?, sandbox?, direction? }
+   */
+  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()}`);
+  }
+
+  /**
+   * Preview the local amount a customer must pay to settle a checkout amount
+   * (inverse deposit pricing — the customer bears spread + gate fee).
+   * GET /api/v1/fiat/checkout-quote
+   * @param {Object} params - { amount, baseCurrency, currency, country }
+   */
+  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()}`);
+  }
+
+  /**
+   * Create a FIAT collection transaction on a checkout session. Async: the
+   * gateway initiates the provider collection in a worker; recover the
+   * deposit (id, nextAction, paymentInstructions, quote) from
+   * getSessionStatus(sessionId).raw.data.fiatDeposit or the
+   * `transaction.ready` session SSE.
+   * POST /api/v1/transactions/create  (fromNetwork=FIAT)
+   * @param {Object} data - { checkoutSessionId, fromCurrency, country, methodId?, phone?, customerEmail?, customerName?, ... }
+   */
+  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).
+   * GET /api/v1/fiat/deposits/:id
+   */
+  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.
+   * POST /api/v1/fiat/deposits/:id/action
+   * @param {string} depositId
+   * @param {'CONFIRM_QUOTE'|'SUBMIT_OTP'} action
+   * @param {string} [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 (drives the full
+   * completion pipeline incl. session COMPLETED + merchant webhooks).
+   * POST /api/v1/fiat/deposits/:id/simulate-complete
+   */
+  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.
+   *
+   * `createFiatTransaction` returns immediately with status INITIALIZING — a
+   * worker initiates the provider collection and only then does the deposit
+   * (depositId, nextAction, quote) attach to the session. This polls until it
+   * shows up, with a bounded deadline and gentle backoff so a stalled worker
+   * degrades into a clean timeout instead of a hot loop.
+   *
+   * @param {string} sessionId
+   * @param {Object} [options]
+   * @param {number} [options.timeoutMs=30000] - Total time budget.
+   * @param {number} [options.pollIntervalMs=1000] - First delay between polls.
+   * @param {number} [options.maxIntervalMs=5000] - Backoff ceiling.
+   * @param {(deposit: any) => boolean} [options.until] - Custom stop condition.
+   *   Defaults to "the deposit exists". Pass e.g.
+   *   `d => d.status === 'CREDITED'` to wait for settlement instead.
+   * @returns {Promise<any>} The deposit projection.
+   * @throws {Error} code `FIAT_DEPOSIT_TIMEOUT` with `.lastDeposit` attached.
+   */
+  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) {
+        // A transient read failure shouldn't abort the wait, but don't swallow
+        // it either — if the budget is spent, the real error is the useful one.
+        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: create the checkout session, start the
+   * fiat transaction, and wait for the deposit — the fiat analogue of
+   * `createDirectPayment`.
+   *
+   * This stops at the QUOTE rather than running to settlement. Confirming a
+   * quote locks the FX rate and (for mobile money) fires the prompt on the
+   * customer's phone, so that stays an explicit step by default — and the
+   * gateway withholds `paymentInstructions` until it happens. Completion is
+   * signalled by the `payment.confirmed` webhook, exactly as for crypto.
+   *
+   * @param {Object} data
+   *   Session: { amount, currency, description?, customerEmail?, customerName?,
+   *              redirectUrl?, callbackUrl?, expiresIn?, metadata?, subaccount?, split_code? }
+   *   Fiat rail: { fromCurrency, country, methodId?, phone? }
+   *   Control: { waitForDeposit=true, autoConfirmQuote=false, timeoutMs?, pollIntervalMs? }
+   * @returns {Promise<{ sessionId, transactionId, depositId, nextAction, quote,
+   *                     paymentInstructions, deposit, session, transaction }>}
+   */
+  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 ---
 
   async startSandboxSimulator() {
@@ -553,11 +983,22 @@ class KuvarPayServer {
   }
 
   /**
-   * Create a renewal checkout session for an existing subscription
-   * POST {Payment API Base}/api/v1/subscriptions/renewal-checkout-sessions
-   */
-  async createRenewalCheckoutSession(body) {
-    return this._post('/api/v1/subscriptions/renewal-checkout-sessions', body);
+   * Create a renewal checkout session for an existing subscription.
+   *
+   * POST {Payment API Base}/api/v1/subscriptions/{subscriptionId}/renew
+   *
+   * The renewal route is keyed by subscription id and returns
+   * `{ success, data: { checkoutSession: { id, status, approval_url, expires_at } } }`.
+   * Pass the id as `subscriptionId` (or `id`); any remaining fields are
+   * forwarded as the request body.
+   *
+   * @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);
   }
 
   /**