squarefi-bff-api-module 1.36.27 → 1.36.29

package/dist/api/types/autogen/apiV1External.types.d.ts

@@ -830,7 +830,8 @@ export interface paths {
                                 postcode?: string;
                                 street1?: string;
                                 street2?: string;
-                                state_id?: number;
+                                /** @description Required when the selected country has states; countries without states may omit it */
+                                state_id?: number | null;
                             };
                         };
                         /** @description Required for crypto types (CRYPTO_EXTERNAL, CRYPTO_INTERNAL) */
@@ -3870,13 +3871,14 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within the wallet bound to the API key.
+         * @description Crypto-to-crypto exchange within the wallet bound to the API key.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` with the source funds blocked. Call `POST /api/orders/{order_id}/approve`
+         *     to execute the swap (the order lands in `COMPLETE` synchronously), or
+         *     `POST /api/orders/{order_id}/cancel` to release the blocked funds.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
+         *     Fiat legs are not supported — only crypto-to-crypto pairs are accepted.
          *
          */
         post: {
@@ -3892,7 +3894,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW, funds blocked — approve to execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4219,6 +4221,8 @@ export interface paths {
         /**
          * Approve order
          * @description Transitions the order from NEW to PROCESSING and triggers the order execution pipeline.
+         *     Exchange orders (EXCHANGE_OMNI) and internal transfers (TRANSFER_INTERNAL /
+         *     OMNIBUS_INTERNAL_TRANSFER) settle synchronously and land in COMPLETE.
          *     Only orders with status NEW can be approved.
          *
          */
@@ -4366,7 +4370,12 @@ export interface paths {
         put?: never;
         /**
          * Internal
-         * @description Transfers funds between wallets within the platform.
+         * @description Transfers funds between wallets within the platform. Two-phase: the
+         *     order is created in `NEW` status with the sender's funds blocked;
+         *     call `POST /api/orders/{id}/approve` to execute the transfer — it
+         *     settles synchronously (receiver credited, order `COMPLETE`). A `NEW`
+         *     order can be canceled via `POST /api/orders/{id}/cancel` to refund
+         *     the blocked funds.
          *     Wallet ID is automatically resolved from the API key — do **not** pass `wallet_id`.
          *
          *     `request_id` is used for idempotency: re-posting the same `request_id`
@@ -4406,7 +4415,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (funds blocked, awaiting approve) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4478,6 +4487,12 @@ export interface paths {
          *     address (or another internal wallet) via a previously-created counterparty
          *     destination.
          *
+         *     Two-phase: the order is created in `NEW` status with funds blocked;
+         *     `POST /api/orders/{id}/approve` dispatches the on-chain send. If the
+         *     destination address belongs to a wallet in the same tenant, the order is
+         *     created as `OMNIBUS_INTERNAL_TRANSFER` (no on-chain transaction) — still
+         *     `NEW` at create, settled synchronously to `COMPLETE` at approve.
+         *
          *     **Prerequisites:**
          *     - A counterparty destination of type `CRYPTO_EXTERNAL` or `CRYPTO_INTERNAL`
          *       created via `POST /api/counterparty/destinations`.
@@ -7430,6 +7445,12 @@ export interface components {
              * @example 7c8d4a2b-1e3f-4d59-9b6a-2c0e5f7d8a90
              */
             to_currency_id: string;
+            /**
+             * Format: uuid
+             * @description Idempotency key (UUID v4 recommended).
+             * @example 550e8400-e29b-41d4-a716-446655440000
+             */
+            request_id: string;
         };
         /** @description Virtual bank account */
         VirtualAccount: {

package/dist/api/types/autogen/apiV1Frontend.types.d.ts

@@ -1425,11 +1425,11 @@ export interface paths {
          * Check internal-transfer availability for a destination
          * @description Read-only check (writes nothing). Resolves the destination's payment
          *     details to an on-platform wallet within the tenant and reports whether an
-         *     instant internal transfer is available.
+         *     internal (off-chain) transfer is available.
          *
          *     A `true` answer means the caller can create an INTERNAL destination to
          *     `target_wallet_id` and transfer to it. Any recipient that cannot receive
-         *     an instant internal transfer is uniformly reported as `available:false`
+         *     an internal transfer is uniformly reported as `available:false`
          *     with `target_wallet_id:null` — the check does not disclose the reason.
          *
          *     Detects crypto (address), INTERNAL (stored target wallet) and banking
@@ -4830,13 +4830,15 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within a wallet.
+         * @description Crypto-to-crypto exchange within a wallet.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` with the source funds blocked. Call `POST /frontend/orders/{order_id}/approve`
+         *     (OTP-gated via `request_id`) to execute the swap — the order lands in
+         *     `COMPLETE` synchronously — or `POST /frontend/orders/{order_id}/cancel`
+         *     to release the blocked funds.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
+         *     Fiat legs are not supported — only crypto-to-crypto pairs are accepted.
          *     Caller must be `admin` of the wallet.
          *
          */
@@ -4853,7 +4855,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW, funds blocked — approve to execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4921,7 +4923,11 @@ export interface paths {
         put?: never;
         /**
          * Internal
-         * @description Transfers funds between two wallets within the platform.
+         * @description Transfers funds between two wallets within the platform. Two-phase:
+         *     the order is created in `NEW` status with the sender's funds blocked;
+         *     `POST /frontend/orders/{id}/approve` (OTP-gated via the `request_id`)
+         *     executes the transfer synchronously — receiver credited, order
+         *     `COMPLETE`. A `NEW` order can be canceled to refund the blocked funds.
          *     Caller must be `admin` of the source wallet.
          *
          */
@@ -4956,7 +4962,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (funds blocked, awaiting approve) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -5024,10 +5030,13 @@ export interface paths {
         put?: never;
         /**
          * Crypto
-         * @description Sends crypto from an omnibus wallet to an external address.
-         *     If the destination address belongs to a wallet in the same tenant,
-         *     the order is created as `OMNIBUS_INTERNAL_TRANSFER` with instant completion
-         *     (no on-chain transaction).
+         * @description Sends crypto from an omnibus wallet to an external address. Two-phase:
+         *     the order is created in `NEW` status with funds blocked;
+         *     `POST /frontend/orders/{id}/approve` (OTP-gated via the `request_id`)
+         *     dispatches the on-chain send. If the destination address belongs to a
+         *     wallet in the same tenant, the order is created as
+         *     `OMNIBUS_INTERNAL_TRANSFER` (no on-chain transaction) — still `NEW` at
+         *     create, settled synchronously to `COMPLETE` at approve.
          *
          */
         post: {
@@ -5697,7 +5706,11 @@ export interface paths {
         put?: never;
         /**
          * Approve an order
-         * @description Moves a NEW order to PROCESSING, triggering its workflow. Validates the order's request_id via OTP.
+         * @description Moves a NEW order to PROCESSING, triggering its workflow. Exchange orders
+         *     (EXCHANGE_OMNI) and internal transfers (TRANSFER_INTERNAL /
+         *     OMNIBUS_INTERNAL_TRANSFER) settle synchronously and land in COMPLETE.
+         *     Validates the order's request_id via OTP.
+         *
          */
         post: {
             parameters: {
@@ -8869,7 +8882,7 @@ export interface paths {
          *
          *     **Access Control**: User must own the wallet
          *
-         *     **Note**: The system will automatically use the appropriate provider (Utila or Processing) based on tenant configuration.
+         *     **Note**: New addresses are always provisioned via Utila. The legacy Processing (Accepta) provider was decommissioned; existing `processing` addresses remain readable.
          *
          */
         post: {
@@ -10835,6 +10848,11 @@ export interface components {
              * @description Destination currency UUID
              */
             to_currency_id: string;
+            /**
+             * Format: uuid
+             * @description Idempotency key (UUID); OTP-verified at approve
+             */
+            request_id: string;
         };
         /** @description Wallet invitation record */
         WalletInvite: {

package/dist/api/types/autogen/apiV1Legacy.types.d.ts

@@ -364,7 +364,7 @@ export interface paths {
         put?: never;
         /**
          * Create a new wallet address
-         * @description Create a new blockchain address for a wallet with Utila or Processing integration
+         * @description Create a new blockchain address for a wallet with Utila integration
          */
         post: {
             parameters: {
@@ -8977,6 +8977,108 @@ export interface components {
              */
             has_more?: boolean;
         };
+        /** @description Profile information of the payment sender */
+        L2FOriginatorProfile: {
+            /**
+             * @description Name of the sender
+             * @example FS AI, A SERIES OF FINSIGHT SPECI
+             */
+            name?: string;
+            /** @description Sender's address information */
+            address?: {
+                address_line1?: string | null;
+                city?: string | null;
+                state?: string | null;
+                postal_code?: string | null;
+                country?: string | null;
+            };
+        };
+        /** @description Bank account information of the sender */
+        L2FOriginatorAccountInfo: {
+            /**
+             * @description Bank account number
+             * @example 202504243736
+             */
+            account_number?: string;
+            /**
+             * @description Routing number (for US payments)
+             * @example 91311229
+             */
+            routing_number?: string | null;
+            /** @description SWIFT BIC code (for international transfers) */
+            swift_bic?: string | null;
+            /** @description Name of the bank/institution */
+            institution_name?: string | null;
+        };
+        /**
+         * @description Standardized originator (sender) information for L2F ONRAMP orders.
+         *     Available for order types: L2F_ACH_ONRAMP, L2F_WIRE_ONRAMP, L2F_SEPA_ONRAMP, L2F_SWIFT_ONRAMP.
+         *     This field appears in order.meta.originator
+         *
+         * @example {
+         *       "profile": {
+         *         "name": "FS AI, A SERIES OF FINSIGHT SPECI",
+         *         "address": {
+         *           "address_line1": "",
+         *           "city": "",
+         *           "state": "",
+         *           "postal_code": "",
+         *           "country": ""
+         *         }
+         *       },
+         *       "account_information": {
+         *         "account_number": "202504243736",
+         *         "routing_number": "91311229",
+         *         "swift_bic": "",
+         *         "institution_name": ""
+         *       },
+         *       "reference": "20251016MMQFMP2U004005",
+         *       "memo": "bfgkp5w"
+         *     }
+         */
+        L2FOriginator: {
+            profile?: components["schemas"]["L2FOriginatorProfile"];
+            account_information?: components["schemas"]["L2FOriginatorAccountInfo"];
+            /**
+             * @description Payment reference number (rail_reference from Railio)
+             * @example 20251016MMQFMP2U004005
+             */
+            reference?: string | null;
+            /**
+             * @description Payment memo/note (rail_originator_memo from Railio)
+             * @example bfgkp5w
+             */
+            memo?: string | null;
+        } | null;
+        /**
+         * @description Optional array of document objects to attach to the order.
+         *     Documents should be uploaded to a storage service beforehand and only URLs should be provided.
+         *     Maximum 50 documents per order.
+         *
+         * @example [
+         *       {
+         *         "url": "https://storage.example.com/documents/invoice-001.pdf",
+         *         "description": "Invoice for payment #001"
+         *       },
+         *       {
+         *         "url": "https://storage.example.com/documents/contract-signed.pdf",
+         *         "description": "Signed contract"
+         *       }
+         *     ]
+         */
+        OrderDocuments: {
+            /**
+             * Format: uri
+             * @description URL of the uploaded document
+             * @example https://storage.example.com/documents/invoice-123.pdf
+             */
+            url: string;
+            /**
+             * @description Optional description of the document
+             * @example Invoice for payment #12345
+             */
+            description?: string | null;
+        }[];
         VirtualAccount: {
             /**
              * Format: uuid
@@ -9261,8 +9363,6 @@ export interface components {
         CardUpdateRequest: unknown;
         IssuingProgram: unknown;
         IssuingTransactionList: unknown;
-        L2FOriginator: unknown;
-        OrderDocuments: unknown;
     };
     responses: never;
     parameters: never;

package/dist/api/types/autogen/apiV1Tenant.types.d.ts

@@ -615,7 +615,8 @@ export interface paths {
                                 postcode?: string;
                                 street1?: string;
                                 street2?: string;
-                                state_id?: number;
+                                /** @description Required when the selected country has states; countries without states may omit it */
+                                state_id?: number | null;
                             };
                         };
                         crypto_data?: {
@@ -2517,13 +2518,14 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within a wallet.
+         * @description Crypto-to-crypto exchange within a wallet.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` with the source funds blocked. Call `POST /admin/orders/{order_id}/approve`
+         *     to execute the swap (the order lands in `COMPLETE` synchronously), or
+         *     `POST /admin/orders/{order_id}/cancel` to release the blocked funds.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
+         *     Fiat legs are not supported — only crypto-to-crypto pairs are accepted.
          *
          */
         post: {
@@ -2542,7 +2544,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW, funds blocked — approve to execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -2608,7 +2610,15 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Internal */
+        /**
+         * Internal
+         * @description Transfers funds between two wallets within the platform. Two-phase:
+         *     the order is created in `NEW` status with the sender's funds blocked;
+         *     `POST /admin/orders/{id}/approve` executes the transfer synchronously —
+         *     receiver credited, order `COMPLETE`. A `NEW` order can be canceled to
+         *     refund the blocked funds.
+         *
+         */
         post: {
             parameters: {
                 query?: never;
@@ -2636,7 +2646,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (funds blocked, awaiting approve) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -2693,7 +2703,16 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Crypto */
+        /**
+         * Crypto
+         * @description Sends crypto from the wallet's omnibus balance via a counterparty
+         *     destination. Two-phase: created `NEW` with funds blocked;
+         *     `POST /admin/orders/{id}/approve` dispatches the on-chain send. A
+         *     destination address internal to the tenant downgrades the order to
+         *     `OMNIBUS_INTERNAL_TRANSFER` — still `NEW` at create, settled
+         *     synchronously to `COMPLETE` at approve.
+         *
+         */
         post: {
             parameters: {
                 query?: never;
@@ -3538,6 +3557,8 @@ export interface paths {
         /**
          * Approve order
          * @description Transitions the order from NEW to PROCESSING and triggers the order execution pipeline.
+         *     Exchange orders (EXCHANGE_OMNI) and internal transfers (TRANSFER_INTERNAL /
+         *     OMNIBUS_INTERNAL_TRANSFER) settle synchronously and land in COMPLETE.
          *     Only orders with status NEW can be approved.
          *
          */
@@ -8176,6 +8197,11 @@ export interface components {
              * @description Destination currency UUID
              */
             to_currency_id: string;
+            /**
+             * Format: uuid
+             * @description Idempotency key (UUID v4 recommended)
+             */
+            request_id: string;
         };
         TenantOrder: {
             /** Format: uuid */

package/dist/utils/apiClientFactory.js

@@ -7,7 +7,14 @@ import { isExternalAuthMode, resolveAccessToken, triggerReverification, triggerU
 import { deleteTokens, getTokens, refreshTokens } from './tokensFactory';
 // eslint-disable-next-line no-constant-condition
 // Backend signals that a sensitive request needs a fresh second-factor verification with this code.
-const TWO_FACTOR_REVERIFICATION_CODE = 'two_factor_reverification_required';
+// Backend error codes are UPPER_SNAKE_CASE, and the code can sit at either `data.code` or
+// `data.error.code`. Normalize to upper case and check both locations so the match stays robust.
+const TWO_FACTOR_REVERIFICATION_CODE = 'TWO_FACTOR_REVERIFICATION_REQUIRED';
+const isReverificationRequired = (data) => {
+    const code = data?.code ??
+        data?.error?.code;
+    return typeof code === 'string' && code.toUpperCase() === TWO_FACTOR_REVERIFICATION_CODE;
+};
 const apiV1BaseURL = process.env.API_URL ?? 'ENV variable API_URL is not defined';
 const apiV2BaseURL = process.env.API_V2_URL ?? 'ENV variable API_V2_URL is not defined';
 const apiTOTPBaseURL = process.env.API_TOTP_URL ?? 'ENV variable API_TOTP_URL is not defined';
@@ -46,7 +53,7 @@ export const createApiClient = ({ baseURL, isBearerToken, tenantId }) => {
         // Step-up 2FA: the backend rejects a sensitive request until the user re-verifies their
         // second factor. Hand off to the consumer's reverification handler and retry once on success.
         if (error?.response?.status === ResponseStatus.FORBIDDEN &&
-            error?.response?.data?.code === TWO_FACTOR_REVERIFICATION_CODE &&
+            isReverificationRequired(error?.response?.data) &&
             !error?.response?.config.context?.isRetryRequest) {
             const { response, config: failedRequestConfig } = error;
             return triggerReverification(response.data).then((didReverify) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.36.27",
+  "version": "1.36.29",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",