squarefi-bff-api-module 1.36.39 → 1.36.41

package/dist/api/frontend.d.ts

@@ -13,6 +13,21 @@ export declare const frontend: {
             list: ({ status, ...params }?: API.Frontend.Issuing.Cards.List.Request) => Promise<API.Frontend.Issuing.Cards.List.Response>;
             deposit: ({ card_id, ...data }: API.Frontend.Issuing.Cards.Deposit.Request) => Promise<API.Frontend.Issuing.Cards.Deposit.Response>;
             withdraw: ({ card_id, ...data }: API.Frontend.Issuing.Cards.Withdraw.Request) => Promise<API.Frontend.Issuing.Cards.Withdraw.Response>;
+            create: (data: API.Frontend.Issuing.Cards.Create.Request) => Promise<API.Frontend.Issuing.Cards.Create.Response>;
+        };
+        cardholders: {
+            list: (params?: API.Frontend.Issuing.Cardholders.List.Request) => Promise<API.Frontend.Issuing.Cardholders.List.Response>;
+            create: (data: API.Frontend.Issuing.Cardholders.Create.Request) => Promise<API.Frontend.Issuing.Cardholders.Create.Response>;
+            getById: ({ cardholder_id, ...params }: API.Frontend.Issuing.Cardholders.Get.Request) => Promise<API.Frontend.Issuing.Cardholders.Get.Response>;
+            delete: ({ cardholder_id, ...params }: API.Frontend.Issuing.Cardholders.Delete.Request) => Promise<API.Frontend.Issuing.Cardholders.Delete.Response>;
+            update: ({ cardholder_id, wallet_id, ...data }: API.Frontend.Issuing.Cardholders.Update.Request) => Promise<API.Frontend.Issuing.Cardholders.Update.Response>;
+            eligibility: (data: API.Frontend.Issuing.Cardholders.Eligibility.Request) => Promise<API.Frontend.Issuing.Cardholders.Eligibility.Response>;
+            submit: ({ cardholder_id, ...params }: API.Frontend.Issuing.Cardholders.Submit.Request) => Promise<API.Frontend.Issuing.Cardholders.Submit.Response>;
+            documents: {
+                upload: ({ wallet_id, ...files }: API.Frontend.Issuing.Cardholders.Documents.Upload.Request) => Promise<API.Frontend.Issuing.Cardholders.Documents.Upload.Response>;
+                discard: ({ document_id, ...params }: API.Frontend.Issuing.Cardholders.Documents.Discard.Request) => Promise<void>;
+                attach: ({ cardholder_id, wallet_id, ...data }: API.Frontend.Issuing.Cardholders.Documents.Attach.Request) => Promise<API.Frontend.Issuing.Cardholders.Documents.Attach.Response>;
+            };
         };
         subAccounts: {
             deposit: ({ sub_account_id, ...data }: API.Frontend.Issuing.SubAccounts.Deposit.Request) => Promise<API.Frontend.Issuing.SubAccounts.Deposit.Response>;

package/dist/api/frontend.js

@@ -22,6 +22,62 @@ export const frontend = {
             }),
             deposit: ({ card_id, ...data }) => apiClientV1Frontend.postRequest(`/frontend/issuing/cards/${card_id}/deposit`, { data }),
             withdraw: ({ card_id, ...data }) => apiClientV1Frontend.postRequest(`/frontend/issuing/cards/${card_id}/withdraw`, { data }),
+            // Unified create — the backend routes to the balance or prepaid flow by the program's
+            // `sub_account_type`, so there is one method for both. Replaces the legacy
+            // `issuing.cards.create.*` methods. The cardholder is either an explicit `cardholder_id`
+            // or resolved from `assigned_user_data_uuid` via the user's linked cardholder (provision it
+            // first through `cardholders.*` — an unlinked user gets `400 CARDHOLDER_NOT_LINKED`).
+            // Issuing fee / initial top-up follow the group tariff; pass `currency_id` (and optionally
+            // `initial_topup`) whenever the tariff carries money.
+            create: (data) => apiClientV1Frontend.postRequest('/frontend/issuing/cards', {
+                data,
+            }),
+        },
+        // Cardholder create flow (see the OpenAPI spec for details):
+        //   1. `cardholders.create` — creates a DRAFT; no vendor is contacted. In `user_data_id` mode
+        //      the KYC documents are seeded from the verified user, so step 2 is usually unnecessary.
+        //   2. `cardholders.documents.upload` (one file per request, before or after the draft exists)
+        //      + `cardholders.documents.attach` — attach the returned upload ids to the draft.
+        //   3. `cardholders.submit` — registers at the vendor and flips the cardholder to ACTIVE.
+        // All write endpoints require the ADMIN role on the wallet; `wallet_id` travels as a query
+        // parameter for access validation.
+        cardholders: {
+            list: (params = {}) => apiClientV1Frontend.getRequest('/frontend/issuing/cardholders', { params }),
+            create: (data) => apiClientV1Frontend.postRequest('/frontend/issuing/cardholders', { data }),
+            getById: ({ cardholder_id, ...params }) => apiClientV1Frontend.getRequest(`/frontend/issuing/cardholders/${cardholder_id}`, { params }),
+            delete: ({ cardholder_id, ...params }) => apiClientV1Frontend.deleteRequest(`/frontend/issuing/cardholders/${cardholder_id}`, { params }),
+            // Complete a DRAFT's dossier (address / phone / email / tax id / gov_id fields) before
+            // submitting it — typically driven by the cardholder's `missing_kyc_fields`. `wallet_id`
+            // travels as a query parameter for access validation; everything else is the PATCH body.
+            update: ({ cardholder_id, wallet_id, ...data }) => apiClientV1Frontend.patchRequest(`/frontend/issuing/cardholders/${cardholder_id}`, { data, params: { wallet_id } }),
+            // Batch verdicts for a member picker: for each user_data uuid — can a card be issued right
+            // away (`READY`), is a draft waiting (`DRAFT`), can one be created (`CAN_CREATE`), or does
+            // the member have to verify first. `will_require` previews the fields to collect by hand;
+            // the created draft's `missing_kyc_fields` is the authoritative version.
+            eligibility: (data) => apiClientV1Frontend.postRequest('/frontend/issuing/cardholders/eligibility', { data }),
+            // Retryable: a failed submit leaves the draft untouched, so it can be called again once the
+            // dossier is complete (a `400 CARDHOLDER_SUBMISSION_INCOMPLETE` lists what is missing in
+            // `error.details.missing`). While a review is running — or once the cardholder is live —
+            // another submit returns `409 CARDHOLDER_NOT_DRAFT`.
+            submit: ({ cardholder_id, ...params }) => apiClientV1Frontend.postRequest(`/frontend/issuing/cardholders/${cardholder_id}/submit`, { params }),
+            documents: {
+                // Send the file the camera produced, unchanged (no crop/resize/re-encode — the vendor's
+                // tampering check can flag a re-encoded photo as forgery), one file per request so the UI
+                // can show per-file progress and retry. Content-Type is set by the browser via FormData.
+                upload: ({ wallet_id, ...files }) => {
+                    const formData = new FormData();
+                    Object.entries(files).forEach(([type, file]) => {
+                        if (file)
+                            formData.append(type, file);
+                    });
+                    return apiClientV1Frontend.postRequest('/frontend/issuing/cardholder-documents', { data: formData, params: { wallet_id } });
+                },
+                // Only uploads not yet attached to a cardholder can be discarded (attached ones answer 409);
+                // an upload that is never attached is deleted by a cleanup sweep anyway.
+                discard: ({ document_id, ...params }) => apiClientV1Frontend.deleteRequest(`/frontend/issuing/cardholder-documents/${document_id}`, { params }),
+                // Attaching a document of a type the cardholder already has replaces the previous one.
+                attach: ({ cardholder_id, wallet_id, ...data }) => apiClientV1Frontend.postRequest(`/frontend/issuing/cardholders/${cardholder_id}/documents`, { data, params: { wallet_id } }),
+            },
         },
         subAccounts: {
             deposit: ({ sub_account_id, ...data }) => apiClientV1Frontend.postRequest(`/frontend/issuing/sub-accounts/${sub_account_id}/deposit`, { data }),

package/dist/api/issuing.d.ts

@@ -1,11 +1,19 @@
 import { API } from './types/types';
 export declare const issuing: {
     cards: {
+        /**
+         * @deprecated The legacy `/issuing/cards/*` create routes are deprecated (SFI-2129).
+         * Use `frontend.issuing.cards.create` — the unified `POST /frontend/issuing/cards` routes
+         * by the program's `sub_account_type` and carries the same fee/top-up handling.
+         */
         create: {
             standAloneCard: {
+                /** @deprecated Use `frontend.issuing.cards.create` (SFI-2129). */
                 prepaid: (data: API.Cards.Create.StandAloneRequest) => Promise<API.Cards.Create.StandAloneResponse>;
+                /** @deprecated Use `frontend.issuing.cards.create` (SFI-2129). */
                 balance: (data: API.Cards.Create.StandAloneRequest) => Promise<API.Cards.Create.ExtendedSubAccountResponse>;
             };
+            /** @deprecated Use `frontend.issuing.cards.create` with `sub_account_id` (SFI-2129). */
             subAccountCard: (data: API.Cards.Create.SubAccountRequest) => Promise<API.Cards.Create.ExtendedSubAccountResponse>;
         };
         byWalletUuid: {

package/dist/api/issuing.js

@@ -3,9 +3,16 @@ import { defaultPaginationParams } from '../constants';
 import { makeSecureRequest } from '../utils/encrypt';
 export const issuing = {
     cards: {
+        /**
+         * @deprecated The legacy `/issuing/cards/*` create routes are deprecated (SFI-2129).
+         * Use `frontend.issuing.cards.create` — the unified `POST /frontend/issuing/cards` routes
+         * by the program's `sub_account_type` and carries the same fee/top-up handling.
+         */
         create: {
             standAloneCard: {
+                /** @deprecated Use `frontend.issuing.cards.create` (SFI-2129). */
                 prepaid: (data) => apiClientV1.postRequest('/issuing/cards/create', { data }),
+                /** @deprecated Use `frontend.issuing.cards.create` (SFI-2129). */
                 balance: async (data) => {
                     const { id: sub_account_id } = await issuing.sub_accounts.create(data.wallet_id, data.program_id);
                     const response = await apiClientV1.postRequest('/issuing/cards/balance', {
@@ -20,6 +27,7 @@ export const issuing = {
                     };
                 },
             },
+            /** @deprecated Use `frontend.issuing.cards.create` with `sub_account_id` (SFI-2129). */
             subAccountCard: async (data) => {
                 const response = await apiClientV1.postRequest('/issuing/cards/balance', {
                     data,

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

@@ -1734,6 +1734,12 @@ export interface paths {
                     wallet_id?: string;
                     /** @description Filter cardholders by issuing program ID */
                     issuing_program_id?: string;
+                    /** @description Only cardholders LINKED to this CORE user (`user_data.uuid`, via the link
+                     *     written by `user_data_id`-mode provisioning). Manually created cardholders
+                     *     have no link and never match this filter. Each returned cardholder also
+                     *     carries its link as `user_data_uuid` (null when unlinked).
+                     *      */
+                    user_data_id?: string;
                     /** @description Number of items to skip */
                     offset?: number;
                     /** @description Number of items to return */
@@ -1984,7 +1990,8 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorResponse"];
                     };
                 };
-                /** @description Cardholder with this email already exists in this wallet + issuing_program */
+                /** @description Cardholder with this email already exists in this wallet + issuing_program. `error.details.cardholder_id` names the conflicting cardholder (when it could be resolved) so the client can adopt it instead of dead-ending.
+                 *      */
                 409: {
                     headers: {
                         [name: string]: unknown;

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

@@ -2207,11 +2207,46 @@ export interface paths {
                          *
                          */
                         vendor_user_id?: string;
+                        /**
+                         * @description TOTAL wallet debit asked for at issuance: the issuing fee is subtracted and
+                         *     the remainder lands on the card's sub-account. Accepted only on group tariffs
+                         *     that already mandate an initial top-up (`initial_topup_usd > 0`); otherwise the
+                         *     group amount stands. Requires `currency_id`.
+                         *
+                         * @example 100
+                         */
+                        initial_topup?: number;
+                        /**
+                         * Format: uuid
+                         * @description Wallet currency to debit for the issuing fee / initial top-up.
+                         *     **Required whenever the group tariff carries a fee or a top-up** — the request
+                         *     is refused with 400 otherwise.
+                         *
+                         */
+                        currency_id?: string;
+                        /**
+                         * Format: uuid
+                         * @description Client-generated idempotency key. A replay with the same value returns the
+                         *     already-created card (same wallet) instead of issuing/charging again; a value
+                         *     already used by another request is refused with 409. Globally unique.
+                         *
+                         */
+                        request_id?: string;
                     };
                 };
             };
             responses: {
-                /** @description Card created successfully */
+                /** @description Card created successfully. `data` is the same fully-decorated card shape as
+                 *     `GET /frontend/issuing/cards/{card_id}` — including `data.id` and
+                 *     `data.sub_account_id` (the sub-account the card spends from; for prepaid cards it
+                 *     is provisioned by this call).
+                 *
+                 *     When the group tariff carried an issuing fee / initial top-up, `data` additionally
+                 *     reports the money outcome: `initial_topup_status` is `completed` when the top-up
+                 *     landed (or there was none to land), `topup_skipped` when no sub-account could
+                 *     receive it (nothing debited), and `topup_failed` when the top-up transfer failed —
+                 *     the card exists either way; `initial_topup_error` carries the failure reason.
+                 *      */
                 201: {
                     headers: {
                         [name: string]: unknown;
@@ -2220,7 +2255,15 @@ export interface paths {
                         "application/json": {
                             /** @example true */
                             success?: boolean;
-                            data?: components["schemas"]["IssuingCard"];
+                            data?: components["schemas"]["IssuingCard"] & {
+                                /**
+                                 * @description Outcome of the issuance-time initial top-up. Present only when the tariff charged at issuance.
+                                 * @enum {string}
+                                 */
+                                initial_topup_status?: "completed" | "topup_failed" | "topup_skipped";
+                                /** @description Reason the initial top-up was skipped or failed. Present only when initial_topup_status is not `completed`. */
+                                initial_topup_error?: string;
+                            };
                             /** @example Card created successfully */
                             message?: string;
                         };
@@ -4043,6 +4086,12 @@ export interface paths {
                     wallet_id?: string;
                     /** @description Filter cardholders by issuing program ID */
                     issuing_program_id?: string;
+                    /** @description Only cardholders LINKED to this CORE user (`user_data.uuid`, via the link
+                     *     written by `user_data_id`-mode provisioning). Manually created cardholders
+                     *     have no link and never match this filter. Each returned cardholder also
+                     *     carries its link as `user_data_uuid` (null when unlinked).
+                     *      */
+                    user_data_id?: string;
                     /** @description Number of items to skip */
                     offset?: number;
                     /** @description Number of items to return */
@@ -4282,12 +4331,31 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Cardholder with this email already exists in this wallet + issuing_program */
+                /** @description Cardholder with this email already exists in this wallet + issuing_program. `error.details.cardholder_id` names the conflicting cardholder (when it could be resolved) so the client can adopt it instead of dead-ending.
+                 *      */
                 409: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            error?: {
+                                /** @example DUPLICATE_CARDHOLDER */
+                                code?: string;
+                                /** @example A cardholder with this email already exists for this wallet and issuing program */
+                                message?: string;
+                                details?: {
+                                    /**
+                                     * Format: uuid
+                                     * @description Id of the already-existing (conflicting) cardholder
+                                     */
+                                    cardholder_id?: string;
+                                } | null;
+                            };
+                        };
+                    };
                 };
                 /** @description Internal Server Error */
                 500: {
@@ -4432,6 +4500,131 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/frontend/issuing/cardholders/eligibility": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Batch cardholder eligibility for wallet members
+         * @description For each `user_data_id`, answers whether a card can be issued to that wallet member
+         *     right away — and if not, what stands in the way. Built for member pickers: one call
+         *     per page of members, verdicts computed from LOCAL data only (memberships, verification
+         *     statuses, KYC applicant references, cardholder links) — the KYC provider is never called.
+         *
+         *     **Verdicts**:
+         *     - `READY` — an ACTIVE cardholder is linked (`cardholder_id`); create the card directly.
+         *     - `DRAFT` — a draft is linked (`cardholder_id`); complete `will_require` and submit it.
+         *     - `CAN_CREATE` — no cardholder yet, but the member clears the `user_data_id`-mode
+         *       creation gates (approved identity/face verification + KYC applicant).
+         *     - `PENDING` — a verification review is in flight; wait.
+         *     - `NEEDS_VERIFICATION` — no approved verification or no KYC applicant; the member has
+         *       to (re)run identity verification.
+         *     - `REJECTED` — a verification came back with a FINAL rejection; re-running it from the
+         *       app is not possible (support resets it), so never render a "verify now" action.
+         *     - `NOT_MEMBER` — the uuid is not an active member of this wallet.
+         *
+         *     **`will_require`**: fields the client should expect to collect BY HAND (same vocabulary
+         *     as the submit 400 `missing` list, e.g. `address.line1`, `tax_identification_number`,
+         *     `email or phone`). For `DRAFT` it is the draft's actual leftovers; for `CAN_CREATE` it
+         *     is a projection that assumes the KYC dossier covers what it usually covers — the created
+         *     draft's `missing_kyc_fields` is the authoritative version.
+         *
+         *     **Authentication**: Bearer token with x-tenant-id header; wallet ADMIN role required.
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /**
+                         * Format: uuid
+                         * @description Wallet whose members are being evaluated
+                         */
+                        wallet_id: string;
+                        /**
+                         * Format: uuid
+                         * @description Program the card would be issued under (drives the KYC bar)
+                         */
+                        issuing_program_id: string;
+                        /** @description user_data uuids of the members to evaluate */
+                        user_data_ids: string[];
+                    };
+                };
+            };
+            responses: {
+                /** @description One verdict per requested user_data_id (duplicates collapsed) */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success?: boolean;
+                            data?: {
+                                /** Format: uuid */
+                                user_data_id: string;
+                                /** @enum {string} */
+                                verdict: "READY" | "DRAFT" | "CAN_CREATE" | "PENDING" | "NEEDS_VERIFICATION" | "REJECTED" | "NOT_MEMBER";
+                                /**
+                                 * Format: uuid
+                                 * @description The linked cardholder for READY/DRAFT verdicts
+                                 */
+                                cardholder_id: string | null;
+                                /** @description Fields to collect by hand (submit `missing` vocabulary) */
+                                will_require: string[];
+                            }[];
+                        };
+                    };
+                };
+                /** @description Invalid input (missing program, empty/oversized/malformed id list), or the program is not available for the caller's user group — the same "This program is not available for your user group" failure cardholder creation gives.
+                 *      */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Access denied to this wallet */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Issuing program not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/frontend/issuing/cardholders/{cardholder_id}/submit": {
         parameters: {
             query?: never;
@@ -12266,22 +12459,78 @@ export interface components {
             /** Format: date-time */
             cleared_at?: string | null;
         };
-        /** @description Cardholder — the consumed subset (mirrors the frontend CardCardholder). The live vendor-proxied endpoint may return additional fields; only the supported subset is documented here. */
+        /** @description Cardholder wire shape: the flattened cardholder record plus flat vendor fields (`vendor_*`, `review_status`, `reject_reason`), as returned by the cardholder list/get/create/update endpoints. */
         IssuingCardholder: {
             /** Format: uuid */
             id: string;
+            /** Format: date-time */
+            created_at?: string;
             first_name: string;
             last_name: string;
             /** Format: email */
             email?: string | null;
             phone?: string | null;
-            /** @description Date of birth */
+            /** @description Date of birth (YYYY-MM-DD) */
             birth_date?: string | null;
             /**
              * @description ISO 3166 alpha-3
              * @example ESP
              */
             nationality?: string | null;
+            /** Format: uuid */
+            wallet_id?: string | null;
+            /** Format: uuid */
+            issuing_program_id?: string | null;
+            /**
+             * @description DRAFT until the cardholder is submitted and registered at the vendor.
+             * @enum {string}
+             */
+            status: "DRAFT" | "ACTIVE";
+            /** @description 'M' | 'F' where the vendor requires one */
+            gender?: string | null;
+            /** @enum {string|null} */
+            cardholder_relationship?: "EMPLOYEE" | "CONTRACTOR" | null;
+            address?: {
+                line1?: string;
+                line2?: string | null;
+                city?: string;
+                state?: string | null;
+                postal_code?: string;
+                /** @description ISO country code */
+                country?: string;
+            } | null;
+            gov_id_type?: string | null;
+            gov_id_number?: string | null;
+            gov_id_country?: string | null;
+            gov_id_issuance_date?: string | null;
+            gov_id_expiration_date?: string | null;
+            /** @description Personal tax id (US: SSN) */
+            tax_identification_number?: string | null;
+            /** @description Stored KYC file descriptors attached to the cardholder. */
+            kyc_documents?: {
+                /** @enum {string} */
+                type?: "selfie" | "gov_id_front" | "gov_id_back";
+                filename?: string | null;
+                content_type?: string;
+                size?: number;
+                /** Format: date-time */
+                uploaded_at?: string;
+            }[];
+            /** @description Fields the issuing program's KYC bar still wants from this cardholder (same vocabulary as the submit 400 `missing` list, e.g. `address.line1`, `documents: selfie`). Absent when the bar cannot be read. */
+            missing_kyc_fields?: string[];
+            /**
+             * Format: uuid
+             * @description CORE user this cardholder is linked to (user_data provisioning mode); null for manually-created cardholders.
+             */
+            user_data_uuid?: string | null;
+            vendor_id?: string | null;
+            vendor_name?: string | null;
+            vendor_type?: string | null;
+            /** @description Vendor-side cardholder id; null while a review is pending. */
+            vendor_user_id?: string | null;
+            vendor_status?: string | null;
+            review_status?: string | null;
+            reject_reason?: string | null;
         };
         /** @description Crypto wallet with nested addresses */
         CryptoWallet: {

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

@@ -1611,7 +1611,11 @@ export interface paths {
         put?: never;
         /**
          * Create a new prepaid card
-         * @description Creates a new prepaid card for the user. Initial topup amount is determined by user group settings.
+         * @deprecated
+         * @description **Deprecated.** Use `POST /frontend/issuing/cards` (unified, routes by the program's
+         *     `sub_account_type`) instead — it carries the same fee/top-up handling.
+         *
+         *     Creates a new prepaid card for the user. Initial topup amount is determined by user group settings.
          *
          *     **Cardholder is required**: Every card must be associated with a cardholder.
          *     Create a cardholder first, then pass the `cardholder_id` here.
@@ -1716,7 +1720,11 @@ export interface paths {
         put?: never;
         /**
          * Create a new balance card
-         * @description Creates a new card linked to an existing balance account for the user. Card fees and initial topup are determined by user group settings.
+         * @deprecated
+         * @description **Deprecated.** Use `POST /frontend/issuing/cards` (unified, routes by the program's
+         *     `sub_account_type`) instead — it carries the same fee/top-up handling.
+         *
+         *     Creates a new card linked to an existing balance account for the user. Card fees and initial topup are determined by user group settings.
          *
          *     **Cardholder is required**: Every card must be associated with a cardholder.
          *     Create a cardholder first, then pass the `cardholder_id` here.

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

@@ -6163,7 +6163,8 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Cardholder with this email already exists in this wallet + issuing_program */
+                /** @description Cardholder with this email already exists in this wallet + issuing_program. `error.details.cardholder_id` names the conflicting cardholder when it could be resolved.
+                 *      */
                 409: {
                     headers: {
                         [name: string]: unknown;

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

@@ -676,6 +676,11 @@ export declare namespace API {
             type CardWithdrawRoot = pathsV1Frontend['/frontend/issuing/cards/{card_id}/withdraw'];
             type SubAccountDepositRoot = pathsV1Frontend['/frontend/issuing/sub-accounts/{sub_account_id}/deposit'];
             type SubAccountWithdrawRoot = pathsV1Frontend['/frontend/issuing/sub-accounts/{sub_account_id}/withdraw'];
+            type CardholdersRoot = pathsV1Frontend['/frontend/issuing/cardholders'];
+            type CardholderRoot = pathsV1Frontend['/frontend/issuing/cardholders/{cardholder_id}'];
+            type CardholderSubmitRoot = pathsV1Frontend['/frontend/issuing/cardholders/{cardholder_id}/submit'];
+            type CardholderDocumentsUploadRoot = pathsV1Frontend['/frontend/issuing/cardholder-documents'];
+            type CardholderAttachDocumentsRoot = pathsV1Frontend['/frontend/issuing/cardholders/{cardholder_id}/documents'];
             type WithOrderStatus<T extends {
                 data?: {
                     status?: string;
@@ -705,6 +710,32 @@ export declare namespace API {
                     type Response = CardsRoot['get']['responses']['200']['content']['application/json'];
                     type Card = NonNullable<Response['data']>[number];
                 }
+                namespace Create {
+                    type Request = Omit<CardsRoot['post']['requestBody']['content']['application/json'], 'cardholder_id'> & {
+                        cardholder_id?: string;
+                        /** Card assignee (`user_data.uuid`); their linked cardholder is used. */
+                        assigned_user_data_uuid?: string;
+                        /**
+                         * TOTAL wallet debit at issuance (fee + card top-up). Accepted only on group
+                         * tariffs that already mandate an initial top-up. Requires `currency_id`.
+                         */
+                        initial_topup?: number;
+                        /** Wallet currency to debit; required whenever the tariff has a fee or a top-up. */
+                        currency_id?: string;
+                        /** Client-generated id stored with the card (idempotency/tracing reference). */
+                        request_id?: string;
+                    };
+                    type Response = CardsRoot['post']['responses']['201']['content']['application/json'] & {
+                        /**
+                         * Outcome of the tariff-mandated initial top-up when the tariff moved money:
+                         * `topup_skipped` when no top-up applied, `topup_failed` when the card was created
+                         * but the top-up could not be executed — a 201 alone is NOT proof the card is funded.
+                         */
+                        initial_topup_status?: 'completed' | 'topup_failed' | 'topup_skipped';
+                        /** Why the top-up failed; populated when `initial_topup_status` is `topup_failed`. */
+                        initial_topup_error?: string;
+                    };
+                }
                 namespace Deposit {
                     type Request = {
                         card_id: string;
@@ -718,6 +749,176 @@ export declare namespace API {
                     type Response = SubAccounts.Withdraw.Response;
                 }
             }
+            export namespace Cardholders {
+                export type Cardholder = componentsV1Frontend['schemas']['IssuingCardholder'] & {
+                    created_at?: string;
+                    wallet_id?: string | null;
+                    issuing_program_id?: string | null;
+                    /** DRAFT until the cardholder is submitted and registered at the vendor. */
+                    status?: 'DRAFT' | 'ACTIVE';
+                    gender?: string | null;
+                    cardholder_relationship?: 'EMPLOYEE' | 'CONTRACTOR' | null;
+                    address?: {
+                        line1?: string;
+                        line2?: string | null;
+                        city?: string;
+                        state?: string | null;
+                        postal_code?: string;
+                        country?: string;
+                    } | null;
+                    gov_id_type?: string | null;
+                    gov_id_number?: string | null;
+                    gov_id_country?: string | null;
+                    gov_id_issuance_date?: string | null;
+                    gov_id_expiration_date?: string | null;
+                    /** Personal tax id (US: SSN) — independent of the gov_id document. */
+                    tax_identification_number?: string | null;
+                    kyc_documents?: {
+                        type?: 'selfie' | 'gov_id_front' | 'gov_id_back';
+                        filename?: string | null;
+                        content_type?: string;
+                        size?: number;
+                        uploaded_at?: string;
+                    }[];
+                    /**
+                     * Fields the program's KYC bar still wants (submit 400 `missing` vocabulary, e.g.
+                     * `address.line1`, `documents: selfie`) — what the completion form should collect.
+                     */
+                    missing_kyc_fields?: string[];
+                    /** CORE user this cardholder is linked to; null for manually-created cardholders. */
+                    user_data_uuid?: string | null;
+                    vendor_id?: string | null;
+                    vendor_name?: string | null;
+                    vendor_type?: string | null;
+                    /** Vendor-side cardholder id; null while a review is pending. */
+                    vendor_user_id?: string | null;
+                    vendor_status?: string | null;
+                    review_status?: string | null;
+                    reject_reason?: string | null;
+                };
+                type WithCardholder<T extends {
+                    data?: unknown;
+                }> = Omit<T, 'data'> & {
+                    data?: Cardholder;
+                };
+                type WithCardholderList<T extends {
+                    data?: unknown;
+                }> = Omit<T, 'data'> & {
+                    data?: Cardholder[];
+                };
+                export namespace List {
+                    type Request = NonNullable<CardholdersRoot['get']['parameters']['query']> & {
+                        /**
+                         * Only cardholders LINKED to this CORE user (`user_data.uuid`). Manually created
+                         * cardholders have no link and never match. Added in SFI-2129.
+                         */
+                        user_data_id?: string;
+                    };
+                    type Response = WithCardholderList<CardholdersRoot['get']['responses']['200']['content']['application/json']>;
+                }
+                export namespace Create {
+                    type Request = CardholdersRoot['post']['requestBody']['content']['application/json'];
+                    type Response = WithCardholder<CardholdersRoot['post']['responses']['201']['content']['application/json']>;
+                }
+                export namespace Get {
+                    type Request = {
+                        cardholder_id: string;
+                    } & NonNullable<CardholderRoot['get']['parameters']['query']>;
+                    type Response = WithCardholder<CardholderRoot['get']['responses']['200']['content']['application/json']>;
+                }
+                export namespace Update {
+                    type Request = {
+                        cardholder_id: string;
+                        /** Query param — the wallet the cardholder belongs to (ADMIN role required). */
+                        wallet_id: string;
+                    } & Partial<Pick<Create.Request, 'first_name' | 'last_name' | 'email' | 'phone' | 'birth_date' | 'nationality' | 'gender' | 'cardholder_relationship' | 'address' | 'gov_id_type' | 'gov_id_number' | 'gov_id_country' | 'gov_id_issuance_date' | 'gov_id_expiration_date' | 'tax_identification_number'>>;
+                    type Response = {
+                        success?: boolean;
+                        data?: Cardholder;
+                        message?: string;
+                    };
+                }
+                export namespace Eligibility {
+                    type Verdict = 
+                    /** An ACTIVE cardholder is linked — create the card right away. */
+                    'READY'
+                    /** A draft is linked — complete `will_require`, submit, then create the card. */
+                     | 'DRAFT'
+                    /** No cardholder yet, but the member clears the creation gates. */
+                     | 'CAN_CREATE'
+                    /** A verification review is in flight; wait. */
+                     | 'PENDING'
+                    /** No approved verification or no KYC applicant — the member must verify. */
+                     | 'NEEDS_VERIFICATION'
+                    /**
+                     * A verification came back with a FINAL rejection — only support can
+                     * reset it. Never render an actionable "verify now" for this state.
+                     */
+                     | 'REJECTED'
+                    /** Not an active member of this wallet. */
+                     | 'NOT_MEMBER';
+                    type Request = {
+                        wallet_id: string;
+                        issuing_program_id: string;
+                        /** user_data uuids of the members to evaluate, max 100 per request. */
+                        user_data_ids: string[];
+                    };
+                    type Item = {
+                        user_data_id: string;
+                        verdict: Verdict;
+                        /** The linked cardholder for READY/DRAFT verdicts, null otherwise. */
+                        cardholder_id: string | null;
+                        /** Fields to collect by hand (submit `missing` vocabulary). */
+                        will_require: string[];
+                    };
+                    type Response = {
+                        success?: boolean;
+                        data?: Item[];
+                    };
+                }
+                export namespace Delete {
+                    type Request = {
+                        cardholder_id: string;
+                    } & NonNullable<CardholderRoot['delete']['parameters']['query']>;
+                    type Response = CardholderRoot['delete']['responses']['200']['content']['application/json'];
+                }
+                export namespace Submit {
+                    type Request = {
+                        cardholder_id: string;
+                    } & CardholderSubmitRoot['post']['parameters']['query'];
+                    type Response = WithCardholder<CardholderSubmitRoot['post']['responses']['200']['content']['application/json']>;
+                }
+                export namespace Documents {
+                    type DocumentType = keyof CardholderDocumentsUploadRoot['post']['requestBody']['content']['multipart/form-data'];
+                    namespace Upload {
+                        type Request = {
+                            wallet_id: string;
+                        } & {
+                            [K in DocumentType]?: File | Blob;
+                        };
+                        type Response = CardholderDocumentsUploadRoot['post']['responses']['201']['content']['application/json'];
+                        type Document = NonNullable<NonNullable<Response['data']>['documents']>[number];
+                    }
+                    namespace Discard {
+                        type Request = {
+                            document_id: string;
+                            wallet_id: string;
+                        };
+                    }
+                    namespace Attach {
+                        export type Request = {
+                            cardholder_id: string;
+                            wallet_id: string;
+                        } & CardholderAttachDocumentsRoot['post']['requestBody']['content']['application/json'];
+                        type RawResponse = CardholderAttachDocumentsRoot['post']['responses']['200']['content']['application/json'];
+                        export type Response = Omit<RawResponse, 'data'> & {
+                            data?: Cardholder;
+                        };
+                        export {};
+                    }
+                }
+                export {};
+            }
             export {};
         }
     }

package/package.json

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