squarefi-bff-api-module 1.36.96 → 1.36.98

package/dist/api/frontend.d.ts

@@ -73,7 +73,7 @@ export declare const frontend: {
     kycRails: {
         getAll: ({ wallet_id }: API.Frontend.KycRails.List.Request) => Promise<API.Frontend.KycRails.List.Response>;
         getById: ({ wallet_id, rail_id }: API.Frontend.KycRails.Get.Request) => Promise<API.Frontend.KycRails.Get.Response>;
-        submit: ({ wallet_id, rail_id, }: API.Frontend.KycRails.Submit.Request) => Promise<API.Frontend.KycRails.Submit.Response>;
+        submit: ({ wallet_id, rail_id, accepted_terms, }: API.Frontend.KycRails.Submit.Request) => Promise<API.Frontend.KycRails.Submit.Response>;
         confirmTerms: ({ wallet_id, rail_id, }: API.Frontend.KycRails.ConfirmTerms.Request) => Promise<API.Frontend.KycRails.ConfirmTerms.Response>;
     };
     kycForms: {

package/dist/api/frontend.js

@@ -151,7 +151,9 @@ export const frontend = {
     kycRails: {
         getAll: ({ wallet_id }) => apiClientV1Frontend.getRequest(`/frontend/wallets/${wallet_id}/kyc-rails`),
         getById: ({ wallet_id, rail_id }) => apiClientV1Frontend.getRequest(`/frontend/wallets/${wallet_id}/kyc-rails/${rail_id}`),
-        submit: ({ wallet_id, rail_id, }) => apiClientV1Frontend.postRequest(`/frontend/wallets/${wallet_id}/kyc-rails/${rail_id}`),
+        // No `data` without `accepted_terms`, so both clients keep the old request (the fetch one sends no body). On a
+        // rail with terms an empty list is a refusal, not an absence (SFI-2865).
+        submit: ({ wallet_id, rail_id, accepted_terms, }) => apiClientV1Frontend.postRequest(`/frontend/wallets/${wallet_id}/kyc-rails/${rail_id}`, accepted_terms == null ? undefined : { data: { accepted_terms } }),
         confirmTerms: ({ wallet_id, rail_id, }) => apiClientV1Frontend.postRequest(`/frontend/wallets/${wallet_id}/kyc-rails/${rail_id}/terms-and-conditions`),
     },
     // KYC forms (CORE). Personal entity creation is idempotent, a business entity is new on every call. A form is
@@ -194,6 +196,7 @@ export const frontend = {
                 params,
                 paramsSerializer: KYC_FORMS_ARRAY_PARAMS,
             }),
+            // `accepted_terms`: all document ids of `form.terms` (`[]` if none); missing ones come back in `details.terms`.
             submit: ({ entity_id, rails, programs, wallet_id, locale, ...data }) => apiClientV1Frontend.postRequest(`/frontend/kyc/entities/${entity_id}/forms/submit`, { data, params: { rails, programs, wallet_id, locale }, paramsSerializer: KYC_FORMS_ARRAY_PARAMS }),
         },
         verification: {

package/dist/api/kyc.d.ts

@@ -17,7 +17,10 @@ export declare const kyc: {
         init: ({ kyc_entity_id, ...params }: API.KYC.Entity.Init.Request) => Promise<API.KYC.Entity.Init.Response>;
         resume: ({ kyc_entity_id, verification_ref, }: API.KYC.Entity.Resume.Request) => Promise<API.KYC.Entity.Resume.Response>;
     };
-    /** @deprecated BFF rails are replaced by CORE `/frontend/wallets/{wallet_id}/kyc-rails` (SFI-2614). Use `frontend.kycRails`. */
+    /**
+     * @deprecated BFF rails are replaced by CORE `/frontend/wallets/{wallet_id}/kyc-rails` (SFI-2614). Use `frontend.kycRails`:
+     * only its `submit` takes the rail's terms ticked before the submission (`accepted_terms`, SFI-2865).
+     */
     rails: {
         info: {
             getAll: ({ wallet_id }: API.KYC.Rails.RailInfo.List.Request) => Promise<API.KYC.Rails.RailInfo.List.Response>;

package/dist/api/kyc.js

@@ -17,7 +17,10 @@ export const kyc = {
         init: ({ kyc_entity_id, ...params }) => apiClientV2.postRequest(`/kyc/entities/${kyc_entity_id}/init`, { params }),
         resume: ({ kyc_entity_id, verification_ref, }) => apiClientV2.postRequest(`/kyc/entities/${kyc_entity_id}/resume/${verification_ref}`),
     },
-    /** @deprecated BFF rails are replaced by CORE `/frontend/wallets/{wallet_id}/kyc-rails` (SFI-2614). Use `frontend.kycRails`. */
+    /**
+     * @deprecated BFF rails are replaced by CORE `/frontend/wallets/{wallet_id}/kyc-rails` (SFI-2614). Use `frontend.kycRails`:
+     * only its `submit` takes the rail's terms ticked before the submission (`accepted_terms`, SFI-2865).
+     */
     rails: {
         info: {
             getAll: ({ wallet_id }) => apiClientV2.getRequest(`/kyc/${wallet_id}/rails`),

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

@@ -2523,6 +2523,12 @@ export interface paths {
          *     fresh cardholder is NOT the way to retry. While a review is running, another submit is
          *     refused with `409`.
          *
+         *     **Final rejection**: a rejection no corrected dossier answers — a forged document,
+         *     fraud, an attempt to bypass the liveness check, or a regulatory bar (age, region, a
+         *     duplicate applicant) — is final. The submit is refused with
+         *     `409 CARDHOLDER_REJECTION_FINAL`, and `error.details.reject_reason` carries the
+         *     vendor's reason; no card can be issued for this identity.
+         *
          *     **Authentication**: x-api-key header required
          *
          */
@@ -2582,7 +2588,7 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorResponse"];
                     };
                 };
-                /** @description Cardholder is live at the vendor, or its review is still running. On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
+                /** @description Cardholder is live at the vendor, or its review is still running (`CARDHOLDER_NOT_DRAFT`). Its rejection is final and cannot be answered by a resubmit (`CARDHOLDER_REJECTION_FINAL`, `error.details.reject_reason`). On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
                 409: {
                     headers: {
                         [name: string]: unknown;

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

@@ -6058,7 +6058,10 @@ export interface paths {
          *       and poll. Only programs whose vendor reviews the person before issuance ever return
          *       this; vendors that issue inline go straight to `READY`.
          *     - `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.
+         *       app is not possible (support resets it), so never render a "verify now" action. Also
+         *       a linked cardholder (`cardholder_id`, `reject_reason`) whose VENDOR rejection is final
+         *       — a forged document, fraud, a liveness bypass, a regulatory bar: its submit answers
+         *       `409 CARDHOLDER_REJECTION_FINAL`, so never render "fix and resubmit" for it.
          *     - `NOT_MEMBER` — the uuid is not an active member of this wallet.
          *
          *     **On a tenant of the KYC forms flow** (SFI-2544) the verdict comes from the member's personal
@@ -6139,8 +6142,9 @@ export interface paths {
                                  */
                                 required_level?: "minimal" | "basic" | "declared" | "full" | null;
                                 /** @description What the vendor disliked, on a NEEDS_RESUBMIT verdict — show it before
-                                 *     asking for a correction. Null when the vendor named no reason, or the
-                                 *     verdict is not a rejection.
+                                 *     asking for a correction — or on a REJECTED one with a linked
+                                 *     cardholder, why the rejection is final. Null when the vendor named no
+                                 *     reason, or the verdict is not a rejection.
                                  *      */
                                 reject_reason?: string | null;
                             }[];
@@ -6215,6 +6219,12 @@ export interface paths {
          *     the person already has: the same document cannot be registered twice at the vendor, so
          *     a fresh cardholder is NOT the way to retry.
          *
+         *     **Final rejection**: a rejection no corrected dossier answers — a forged document,
+         *     fraud, an attempt to bypass the liveness check, or a regulatory bar (age, region, a
+         *     duplicate applicant) — is final. The submit is refused with
+         *     `409 CARDHOLDER_REJECTION_FINAL`, and `error.details.reject_reason` carries the
+         *     vendor's reason; no card can be issued for this identity.
+         *
          *     **Idempotency**: while a review is running, or once the cardholder is live, another
          *     submit returns `409 CARDHOLDER_NOT_DRAFT` rather than spending a second review.
          *
@@ -6275,7 +6285,7 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Cardholder is live at the vendor, or its review is still running. On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
+                /** @description Cardholder is live at the vendor, or its review is still running (`CARDHOLDER_NOT_DRAFT`). Its rejection is final and cannot be answered by a resubmit (`CARDHOLDER_REJECTION_FINAL`, `error.details.reject_reason`). On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -11418,7 +11428,8 @@ export interface paths {
          *
          *     The same report (type, format and params) asked again while the first one is
          *     still being generated returns that first report with 200 instead of starting
-         *     another. Up to 3 reports of a wallet are generated at once.
+         *     another. The order of `card_ids` counts: the same cards in another order are
+         *     another report. Up to 3 reports of a wallet are generated at once.
          *
          */
         post: {
@@ -15881,7 +15892,15 @@ export interface paths {
          * @description Puts the wallet on the rail, the way compliance does from the panel: a rail whose vendor CORE onboards
          *     itself is submitted here, any other goes through the KYC-admin service. A manual rail waits for
          *     compliance (`WAITING_ON_REVIEW`); a universal rail is approved on the spot. An application the vendor
-         *     sent back (`HOLD`, `SOFT_REJECT`) is resubmitted. No body.
+         *     sent back (`HOLD`, `SOFT_REJECT`) is resubmitted.
+         *
+         *     Terms: show the rail's `terms_and_conditions` before the submission and send the ids the client ticked as
+         *     `accepted_terms`. Every active document of the rail must be among them, or nothing is submitted
+         *     (`400 TERMS_NOT_ACCEPTED`). The acceptance is recorded on the application at the time of the submission
+         *     (`wallet_rail.terms_confirmed`, the documents in `wallet_rail.terms_and_conditions`), and a vendor that takes
+         *     an acceptance date is sent the same time; an account the vendor already holds may keep the date it recorded
+         *     first. Without `accepted_terms` (or without a body, or `null`) the submission goes as before and the terms are
+         *     accepted later with `POST …/terms-and-conditions`.
          *
          *     On the KYC forms flow CORE makes this submission itself for a rail the client sent a rail or multi
          *     form for, once the form is accepted and the entity is `APPROVED`, when the form was sent by a wallet `admin` or `owner` and the wallet has no application
@@ -15908,7 +15927,16 @@ export interface paths {
                 };
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Ids of the rail's `terms_and_conditions` the client accepted with this submission. On a rail with
+                         *     terms an empty list is a refusal (`400 TERMS_NOT_ACCEPTED`), not an absence of the field.
+                         *      */
+                        accepted_terms?: string[] | null;
+                    };
+                };
+            };
             responses: {
                 /** @description The rail after the submission */
                 200: {
@@ -15919,14 +15947,16 @@ export interface paths {
                         "application/json": components["schemas"]["WalletKycRailResponse"];
                     };
                 };
-                /** @description `VALIDATION_ERROR` — `rail_id` is not a UUID (a message only); `RAIL_NOT_AVAILABLE` — the rail has no
-                 *     onboarding implementation, or is a universal rail other than the tenant's default on a tenant without
-                 *     KYC; `RAIL_SUBMIT_UNAVAILABLE` — the rail takes no submissions; `RAIL_TYPE_MISMATCH` — the rail is of
+                /** @description `VALIDATION_ERROR` — `rail_id` is not a UUID (a message only), or `accepted_terms` is not an array of uuids
+                 *     (`details.issues`);
+                 *     `RAIL_NOT_AVAILABLE` — the rail has no onboarding implementation, or is a universal rail other than the
+                 *     tenant's default on a tenant without KYC; `RAIL_SUBMIT_UNAVAILABLE` — the rail takes no submissions; `RAIL_TYPE_MISMATCH` — the rail is of
                  *     the other entity type; `RAIL_SUBMISSION_REJECTED` — the onboarding behind the rail refused the
                  *     submission (the vendor's reason is logged, never returned); `RAIL_REQUIREMENTS_INCOMPLETE` — on a
                  *     tenant of the KYC forms flow, the KYC entity misses saved values of required fields of the rail's form
                  *     (a draft does not count): `details.fields` lists their keys, open
-                 *     `GET /frontend/kyc/entities/{entity_id}/forms?rails={rail_id}` and fill them
+                 *     `GET /frontend/kyc/entities/{entity_id}/forms?rails={rail_id}` and fill them; `TERMS_NOT_ACCEPTED` —
+                 *     `accepted_terms` misses an active terms document of the rail, nothing was submitted
                  *      */
                 400: {
                     headers: {
@@ -16421,7 +16451,7 @@ export interface paths {
         };
         /**
          * The form of an entity for a set of purposes
-         * @description Built on every call from the tenant's requirement profiles and the entity. Without `rails` and `programs` it is the base form. With one rail it is that rail's form: the base profile, the tenant's rail profile and the vendor's minimum merged: a field required by any of them is required, `review` wins over `auto`, and a field is shown when any of them shows it (one asking it without a condition — the vendor's minimum always — shows it always); profiles whose conditions read each other in a circle answer `409 KYC_FORM_CONDITIONS_CYCLE`. Sections are the groups to draw, `visible_when` the show logic, `required_by` the purposes a field is required for, the locks (`saved`, `from_document`, `pending`, `status`) what the client cannot change, `schema_version` what to echo back. Fields that come from the identity document (names, date of birth, citizenship, the document number and dates) are left out until the document is verified; the document itself is asked: its type `gov_id_type` (`PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS` — the codes `…/owners/{owner_id}/document` takes as `type` too), issuing country `gov_id_country` and photos `gov_id_front` and `gov_id_back` (shown unless a passport) — saved, and no longer asked, once it is verified; `state: complete` on a rail form means nothing is left to ask and the client goes straight to the rail's terms. With one program and `wallet_id` it is the form before a card: the level the program's vendor demands (`minimal`: name, email, phone; `basic`: plus date of birth, citizenship, gender, identity document type and number, residential address; `declared` / `full`: plus the identity document and the face, verified after the form) merged with the tenant's binding for the program, without the base form; what the personal entity already holds is locked `saved`, so `state: complete` means the card can be asked for at once. Several rails and programs at once is the multi form: the base form, every rail and every program merged, each field once with `required_by` naming the purposes. Access: the owner of the entity, or an owner / admin of a wallet it is linked to.
+         * @description Built on every call from the tenant's requirement profiles and the entity. Without `rails` and `programs` it is the base form. With one rail it is that rail's form: the base profile, the tenant's rail profile and the vendor's minimum merged: a field required by any of them is required, `review` wins over `auto`, and a field is shown when any of them shows it (one asking it without a condition — the vendor's minimum always — shows it always); profiles whose conditions read each other in a circle answer `409 KYC_FORM_CONDITIONS_CYCLE`. Sections are the groups to draw, `visible_when` the show logic, `required_by` the purposes a field is required for, the locks (`saved`, `from_document`, `pending`, `status`) what the client cannot change, `schema_version` what to echo back. Fields that come from the identity document (names, date of birth, citizenship, the document number and dates) are left out until the document is verified; the document itself is asked: its type `gov_id_type` (`PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS` — the codes `…/owners/{owner_id}/document` takes as `type` too), issuing country `gov_id_country` and photos `gov_id_front` and `gov_id_back` (shown unless a passport) — saved, and no longer asked, once it is verified; `state: complete` on a rail form means no field is left to ask. The terms of the form's rails — a rail it names and the rail of each of its card programs — come with the form in `terms`, to be accepted with the submission (`accepted_terms`). With one program and `wallet_id` it is the form before a card: the level the program's vendor demands (`minimal`: name, email, phone; `basic`: plus date of birth, citizenship, gender, identity document type and number, residential address; `declared` / `full`: plus the identity document and the face, verified after the form) merged with the tenant's binding for the program, without the base form; what the personal entity already holds is locked `saved`, so `state: complete` means the card can be asked for at once. Several rails and programs at once is the multi form: the base form, every rail and every program merged, each field once with `required_by` naming the purposes. Access: the owner of the entity, or an owner / admin of a wallet it is linked to.
          */
         get: {
             parameters: {
@@ -16497,7 +16527,7 @@ export interface paths {
         get?: never;
         /**
          * Save the draft of a form
-         * @description The form is the one `rails` and `programs` name, as for `GET …/forms`. Replaces the draft as a whole with the given values of open fields. Types are checked, rules and requiredness are not — except that owner shares over 100% in total and a value whose condition reads an empty required source are refused here too. Nothing is written to the KYC entity. The first draft of a business form moves the application to `PENDING`. The entity's owner, or an owner or admin of a linked wallet.
+         * @description The form is the one `rails` and `programs` name, as for `GET …/forms`. Replaces the draft as a whole with the given values of open fields. Types are checked, rules and requiredness are not — except that owner shares over 100% in total and a value whose condition reads an empty required source are refused here too. Nothing is written to the KYC entity. The terms of the form's rails (`form.terms` of `GET …/forms`) are accepted with the submission only: a draft takes no `accepted_terms` (a key of that name is ignored, nothing about the terms is stored) and its answer carries no `terms`. The first draft of a business form moves the application to `PENDING`. The entity's owner, or an owner or admin of a linked wallet.
          */
         put: {
             parameters: {
@@ -16548,7 +16578,7 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now, reload it (`GET …/forms`) and send again; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
+                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now (its fields or the terms documents of its rails changed), reload it (`GET …/forms`) and send again; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -16762,7 +16792,7 @@ export interface paths {
         put?: never;
         /**
          * Send a form
-         * @description The form is the one `rails` and `programs` name. The full check of every open field (all errors in one `VALIDATION_ERROR`), then a submission: `awaiting_verification` when the identity document and face are still needed, `applied` when every profile of the form writes the answers into the KYC entity at once, `in_review` when compliance decides (any profile of the form in review mode). Answers `200` with the form in its new state. One submission of a form at a time. A form over rails or programs that brings nothing new — no value and no file, every required field already saved in the entity (not just waiting in another submission under review) — is `applied` at once whatever the review mode: there is nothing for compliance to decide. A rail form does not change the application status. A card form is `auto` unless a profile of it says otherwise and never changes the application status. A multi form moves the application like the base form it includes; once applied, every rail and program of the set is satisfied from the shared data. Once a rail, card or multi form is accepted (`applied`, or `approved` by compliance) and the wallet's KYC is `APPROVED` — whichever comes second — when the form was sent by an owner or admin of the wallet (the role those routes ask for), CORE submits the wallet itself: to each rail of the form the wallet has no application on yet — only for a form of the wallet's own KYC entity, a member's form never puts the wallet on a rail — (as `POST /frontend/wallets/{wallet_id}/kyc-rails/{rail_id}` would; it then shows in `GET …/kyc-rails`), and to each program the member has no cardholder in yet (as `POST /frontend/issuing/cardholders` with `user_data_id` and its submit would). The latest form sent for a rail or program decides: returned, rejected or still in review, nothing is submitted. A submission CORE could not make — refused by the rail or the vendor, a program at its limit, a form sent by a member without that role — is left for the client to make with those routes, as before. The entity's owner, or an owner or admin of a linked wallet.
+         * @description The form is the one `rails` and `programs` name. The full check of every open field (all errors in one `VALIDATION_ERROR`) and of the terms — a form with terms documents (`form.terms`) is sent only with every one of their ids in `accepted_terms` (`400 KYC_TERMS_NOT_ACCEPTED` otherwise, nothing written) — then a submission: `awaiting_verification` when the identity document and face are still needed, `applied` when every profile of the form writes the answers into the KYC entity at once, `in_review` when compliance decides (any profile of the form in review mode). Answers `200` with the form in its new state. One submission of a form at a time. A form over rails or programs that brings nothing new — no value and no file, every required field already saved in the entity (not just waiting in another submission under review) — is `applied` at once whatever the review mode: there is nothing for compliance to decide. A rail form does not change the application status. A card form is `auto` unless a profile of it says otherwise and never changes the application status. A multi form moves the application like the base form it includes; once applied, every rail and program of the set is satisfied from the shared data. Once a rail, card or multi form is accepted (`applied`, or `approved` by compliance) and the wallet's KYC is `APPROVED` — whichever comes second — when the form was sent by an owner or admin of the wallet (the role those routes ask for), CORE submits the wallet itself: to each rail of the form the wallet has no application on yet — only for a form of the wallet's own KYC entity, a member's form never puts the wallet on a rail — (as `POST /frontend/wallets/{wallet_id}/kyc-rails/{rail_id}` would; it then shows in `GET …/kyc-rails`), and to each program the member has no cardholder in yet (as `POST /frontend/issuing/cardholders` with `user_data_id` and its submit would). The latest form sent for a rail or program decides: returned, rejected or still in review, nothing is submitted. A rail opened so, or opened before with its terms unconfirmed — a rail of the form, or the rail of one of its programs — gets its terms confirmed (`terms_confirmed: true`) at the time the form was sent, when the form accepted every terms document the application holds; terms changed since the form was sent are left for the client to confirm with `POST …/kyc-rails/{rail_id}/terms-and-conditions`. A submission CORE could not make — refused by the rail or the vendor, a program at its limit, a form sent by a member without that role — is left for the client to make with those routes, as before. The entity's owner, or an owner or admin of a linked wallet.
          */
         post: {
             parameters: {
@@ -16788,7 +16818,7 @@ export interface paths {
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["KycFormsAnswersRequest"];
+                    "application/json": components["schemas"]["KycFormsSubmitRequest"];
                 };
             };
             responses: {
@@ -16801,7 +16831,7 @@ export interface paths {
                         "application/json": components["schemas"]["KycFormsFormResponse"];
                     };
                 };
-                400: components["responses"]["KycFormsFieldErrors"];
+                400: components["responses"]["KycFormsSubmitErrors"];
                 401: components["responses"]["UnauthorizedError"];
                 403: components["responses"]["KycFormsAccessDenied"];
                 /** @description `NOT_FOUND` — the entity does not exist or belongs to another tenant, or a rail / program of the query does not exist for the tenant */
@@ -16813,7 +16843,7 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now, reload it (`GET …/forms`) and send again; `OPERATION_IN_PROGRESS` — a submission of this form is already running; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
+                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now (its fields or the terms documents of its rails changed), reload it (`GET …/forms`) and send again; `OPERATION_IN_PROGRESS` — a submission of this form is already running; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -19303,7 +19333,7 @@ export interface components {
              */
             type: "individual" | "business" | "universal";
             /**
-             * @description KYC verification status. A refusal is one of three values: `DECLINED`, `REJECT` or `SOFT_REJECT`. Only `APPROVED` (full access) and `HOLD` (read-only) open the wallet. `OFFBOARDED` — final: the work with this company or person is over; `EXPIRED` — the verification lapsed and the client passes it again.
+             * @description KYC verification status. A refusal is one of three values: `DECLINED`, `REJECT` or `SOFT_REJECT`. Only `APPROVED` (full access) and `HOLD` (read-only) open the wallet. `OFFBOARDED` — final: the work with this company or person is over; `EXPIRED` — no activity on the application for over three months; a check passed on it brings it back.
              * @enum {string}
              */
             status: "APPROVED" | "DECLINED" | "PENDING" | "PROCESSING" | "HOLD" | "NEEDS_ATTENTION" | "DOUBLE" | "SOFT_REJECT" | "REJECT" | "UNVERIFIED" | "WAITING_ON_UBOS" | "WAITING_ON_REVIEW" | "EXPIRED" | "OFFBOARDED";
@@ -19315,6 +19345,11 @@ export interface components {
         };
         /** @description A terms-and-conditions document of a KYC rail. */
         WalletKycRailTerms: {
+            /**
+             * Format: uuid
+             * @description Send it in `accepted_terms` of `POST /frontend/wallets/{wallet_id}/kyc-rails/{rail_id}` once the client ticked the document.
+             */
+            id: string;
             title: string;
             description: string | null;
             link: string | null;
@@ -20135,7 +20170,7 @@ export interface components {
             source: "DEBIT_CARD";
             from: components["schemas"]["ReportPeriodFrom"];
             to: components["schemas"]["ReportPeriodTo"];
-            /** @description Cards of the wallet (the id the card endpoints take), in the order their rows follow one another. A card of another wallet → 404 REPORT_SUBJECT_NOT_FOUND. */
+            /** @description Cards of the wallet (the id the card endpoints take), in the order their rows follow one another; the order is kept as asked and a repeated id is dropped (the first stays). The same cards in another order are another report. A card of another wallet → 404 REPORT_SUBJECT_NOT_FOUND. */
             card_ids: string[];
         };
         /** @description Transaction statement → Account cards — the transactions of a sub-account (card program) of the wallet. Formats CSV, XLSX. Period up to 100 days. */
@@ -20199,7 +20234,7 @@ export interface components {
             status?: "PENDING" | "GENERATING" | "READY" | "FAILED";
             params?: components["schemas"]["WalletReportParams"];
             /**
-             * @description TIMEOUT — the attempt was still generating 30 minutes after it was queued; it is failed on the wallet's next report request.
+             * @description GENERATION_ERROR — the run failed, or the report has nothing to show (e.g. Account details of an account with no deposit details); TIMEOUT — the attempt was still generating 30 minutes after it was queued; it is failed on the wallet's next report request.
              * @enum {string|null}
              */
             failure_code?: "GENERATION_ERROR" | "QUEUE_ERROR" | "TIMEOUT" | null;
@@ -20325,21 +20360,27 @@ export interface components {
             success: boolean;
             data: components["schemas"]["WalletKycRail"];
         };
-        /** @description The error envelope of a rail submission: `ErrorResponse`, with `details` only on `RAIL_REQUIREMENTS_INCOMPLETE`. */
+        /** @description The error envelope of a rail submission: `ErrorResponse`, with `details` only on `RAIL_REQUIREMENTS_INCOMPLETE` (`fields`) and on a `VALIDATION_ERROR` of `accepted_terms` (`issues`). */
         WalletKycRailSubmitErrorResponse: components["schemas"]["ErrorResponse"] & {
             error?: {
-                /** @description `RAIL_REQUIREMENTS_INCOMPLETE` only (absent on every other code): `fields` lists the keys of the required fields of the rail's form with nothing saved in the KYC entity yet, in form order — the `key` of the fields `GET /frontend/kyc/entities/{entity_id}/forms?rails={rail_id}` answers (`address.city`, `document.proof_of_address`, `beneficial_owners`, …). Open that form and highlight them; a draft or a submission still in review does not count until it is applied. */
+                /** @description Absent on every other code. `RAIL_REQUIREMENTS_INCOMPLETE`: `fields` lists the keys of the required fields of the rail's form with nothing saved in the KYC entity yet, in form order — the `key` of the fields `GET /frontend/kyc/entities/{entity_id}/forms?rails={rail_id}` answers (`address.city`, `document.proof_of_address`, `beneficial_owners`, …). Open that form and highlight them; a draft or a submission still in review does not count until it is applied. `VALIDATION_ERROR` of `accepted_terms`: `issues` names each problem (`field`, e.g. `accepted_terms.0`, and `message`); a bad `rail_id` carries a message only. */
                 details?: {
                     /** @example [
                      *       "expected_monthly_volume",
                      *       "document.proof_of_address"
                      *     ] */
-                    fields: string[];
+                    fields?: string[];
+                    issues?: {
+                        /** @example accepted_terms.0 */
+                        field?: string;
+                        /** @example accepted_terms must hold terms ids (UUID) */
+                        message?: string;
+                    }[];
                 } | null;
             };
         };
         /**
-         * @description Raw application status of the KYC entity (`kyc_entity.status`) — the same value the wallet shows as `kyc_info.status` (`WalletKycInfo`); a rail application (`wallet_rail.status`) has its own status of the same set. Build screens by the overview `stage`, not by this value: a status can be added without a release. `PROCESSING` is not set by the forms flow — a vendor sync of the old flow leaves it on an entity — and the overview answers `stage: unknown` for it, as for any status it does not know. `EXPIRED` (a lapsed verification; nothing sets it yet) and `OFFBOARDED` (compliance ended the relationship; final) are set in CORE, never by the identity provider, and no form or provider event moves them — but one: an `EXPIRED` application whose applicant passes the identity check again goes on to its owners (`WAITING_ON_UBOS`) or to compliance (`WAITING_ON_REVIEW`).
+         * @description Raw application status of the KYC entity (`kyc_entity.status`) — the same value the wallet shows as `kyc_info.status` (`WalletKycInfo`); a rail application (`wallet_rail.status`) has its own status of the same set. Build screens by the overview `stage`, not by this value: a status can be added without a release. `PROCESSING` is not set by the forms flow — a vendor sync of the old flow leaves it on an entity — and the overview answers `stage: unknown` for it, as for any status it does not know. `EXPIRED` (no activity on the application for over three months) and `OFFBOARDED` (compliance ended the relationship; final) are set in CORE, never by the identity provider. No form moves either, and no provider event moves `OFFBOARDED`. An `EXPIRED` application comes back once its verification is heard from again — a person's when their identity check passes, a business's on any check outcome of the filler or an owner while the filler's own check stands passed — and goes on to its owners (`WAITING_ON_UBOS`) or to compliance (`WAITING_ON_REVIEW`), never approved by itself.
          * @enum {string}
          */
         KycFormsEntityStatus: "UNVERIFIED" | "PENDING" | "PROCESSING" | "WAITING_ON_REVIEW" | "WAITING_ON_UBOS" | "NEEDS_ATTENTION" | "HOLD" | "APPROVED" | "SOFT_REJECT" | "REJECT" | "DECLINED" | "DOUBLE" | "EXPIRED" | "OFFBOARDED";
@@ -20594,6 +20635,23 @@ export interface components {
                 add_label: string;
             };
         };
+        /** @description The terms of one rail of the form: a rail the form names, or the rail of one of its card programs — one group per rail, the programs that go through it listed with it. Draw one checkbox per group that accepts all of its `items`; send their ids in `accepted_terms` of `POST …/forms/submit`. */
+        KycFormsTerms: {
+            /** Format: uuid */
+            rail_id: string;
+            /** @description The card programs of the form that go through this rail; empty when only the rail itself is named. */
+            program_ids: string[];
+            /** @description The rail's active terms documents in display order; empty when the rail has none — nothing to accept. */
+            items: {
+                /** Format: uuid */
+                id: string;
+                /** @example Cardholder Agreement */
+                title: string;
+                description: string | null;
+                /** @example https://example.com/terms.pdf */
+                link: string | null;
+            }[];
+        };
         KycFormsForm: {
             /**
              * @description What the form is for: the base form, a rail, a card program (`card`), or one form over several rails and programs (`multi`).
@@ -20617,7 +20675,7 @@ export interface components {
              */
             locale: string;
             /**
-             * @description Hash of the form composition (keys, requiredness, conditions, list item fields; not the texts); echo it back in the draft and the submission. It can change between the load and the send: `409 FORM_OUTDATED`.
+             * @description Hash of the form composition (keys, requiredness, conditions, list item fields, the ids of the terms documents in `terms`; not the texts); echo it back in the draft and the submission. It can change between the load and the send: `409 FORM_OUTDATED`.
              * @example b3f1c2a9
              */
             schema_version: string;
@@ -20646,6 +20704,31 @@ export interface components {
                 description: string | null;
                 fields: components["schemas"]["KycFormsField"][];
             }[];
+            /**
+             * @description The terms the client accepts with the form, one group per rail of the form: the rails named first, then the rail of each card program. Empty for the base form; a program without a rail adds none. The documents are those in force now: a change after the load answers the submission `409 FORM_OUTDATED`.
+             * @example [
+             *       {
+             *         "rail_id": "a38b9a0c-5d1e-4f2a-8b3c-4d5e6f708192",
+             *         "program_ids": [
+             *           "d94ef320-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
+             *         ],
+             *         "items": [
+             *           {
+             *             "id": "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5",
+             *             "title": "Cardholder Agreement",
+             *             "description": null,
+             *             "link": "https://example.com/terms.pdf"
+             *           }
+             *         ]
+             *       },
+             *       {
+             *         "rail_id": "c1d7fac1-2b3c-4d5e-9f60-718293a4b5c6",
+             *         "program_ids": [],
+             *         "items": []
+             *       }
+             *     ]
+             */
+            terms: components["schemas"]["KycFormsTerms"][];
         };
         KycFormsFormResponse: {
             /** @example true */
@@ -20691,6 +20774,16 @@ export interface components {
                 [key: string]: components["schemas"]["KycFormsAnswerValue"];
             };
         };
+        KycFormsSubmitRequest: components["schemas"]["KycFormsAnswersRequest"] & {
+            /**
+             * @description The ids of every terms document of the form (`form.terms[].items[].id`) — the client ticked the checkbox of each group. Required in full when the form has any: one left out answers `400 KYC_TERMS_NOT_ACCEPTED`, an id that is not a uuid or not of this form `400 VALIDATION_ERROR`. A form without terms documents is sent without it. The terms are checked after the fields: while a field is wrong, only the `VALIDATION_ERROR` comes back.
+             * @default []
+             * @example [
+             *       "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5"
+             *     ]
+             */
+            accepted_terms: string[];
+        };
         KycFormsDraftSaved: {
             /** @example true */
             success: boolean;
@@ -20757,7 +20850,7 @@ export interface components {
                 entity_type: "individual" | "business";
                 status: components["schemas"]["KycFormsEntityStatus"];
                 /**
-                 * @description Build the screen by this, not by `status`. `not_required` — the tenant asks nothing of this client type (`base_form` is null); `not_started` — the base form was not started; `incomplete` — a draft exists; `action_required` — the client's move: pass the identity check (`next_step: verification`), or, for a business, get the owners through theirs (`next_step: owners`); `in_review` — the identity provider or compliance is looking; `resubmit` — returned by compliance, the form is open again with `submission.comment`; `on_hold` — frozen by compliance; `verified` — approved; `expired` — the verification lapsed: the applicant passes the identity check again (`next_step: verification`), then compliance looks again; `rejected` — refused, the form is read-only; `offboarded` — compliance ended the relationship, final; `unknown` — a status this contract does not know. The stage of each `status`: `APPROVED` → `verified`; `REJECT`, `DECLINED`, `DOUBLE` → `rejected`; `OFFBOARDED` → `offboarded`; `EXPIRED` → `expired`; `HOLD` → `on_hold`; `WAITING_ON_REVIEW` → `in_review`; `NEEDS_ATTENTION` → `resubmit`; `WAITING_ON_UBOS` → `action_required` while an owner other than the filler's row has a check to start, finish or redo (`next_step: owners`), else `in_review`; `UNVERIFIED`, `PENDING`, `SOFT_REJECT` → by the base form and the identity check: `not_required` (no base form), `not_started`, `incomplete` (a draft), `action_required` (the check is the move), `in_review` (sent, with compliance or the provider), `resubmit` (the latest submission was returned) — the forms flow never sets `SOFT_REJECT`, one left by the old flow shows the screen of its form like `PENDING`; `PROCESSING` → `unknown` (the forms flow never sets it, an old-flow vendor sync may leave it).
+                 * @description Build the screen by this, not by `status`. `not_required` — the tenant asks nothing of this client type (`base_form` is null); `not_started` — the base form was not started; `incomplete` — a draft exists; `action_required` — the client's move: pass the identity check (`next_step: verification`), or, for a business, get the owners through theirs (`next_step: owners`); `in_review` — the identity provider or compliance is looking; `resubmit` — returned by compliance, the form is open again with `submission.comment`; `on_hold` — frozen by compliance; `verified` — approved; `expired` — no activity on the application for over three months: a passed identity check brings it back (`next_step: verification`), then compliance looks again; `rejected` — refused, the form is read-only; `offboarded` — compliance ended the relationship, final; `unknown` — a status this contract does not know. The stage of each `status`: `APPROVED` → `verified`; `REJECT`, `DECLINED`, `DOUBLE` → `rejected`; `OFFBOARDED` → `offboarded`; `EXPIRED` → `expired`; `HOLD` → `on_hold`; `WAITING_ON_REVIEW` → `in_review`; `NEEDS_ATTENTION` → `resubmit`; `WAITING_ON_UBOS` → `action_required` while an owner other than the filler's row has a check to start, finish or redo (`next_step: owners`), else `in_review`; `UNVERIFIED`, `PENDING`, `SOFT_REJECT` → by the base form and the identity check: `not_required` (no base form), `not_started`, `incomplete` (a draft), `action_required` (the check is the move), `in_review` (sent, with compliance or the provider), `resubmit` (the latest submission was returned) — the forms flow never sets `SOFT_REJECT`, one left by the old flow shows the screen of its form like `PENDING`; `PROCESSING` → `unknown` (the forms flow never sets it, an old-flow vendor sync may leave it).
                  * @enum {string}
                  */
                 stage: "not_required" | "not_started" | "incomplete" | "action_required" | "in_review" | "resubmit" | "on_hold" | "verified" | "expired" | "rejected" | "offboarded" | "unknown";
@@ -20998,11 +21091,18 @@ export interface components {
                 }[];
             };
         };
-        /** @description The structured payload of an error that carries one (absent otherwise — an invalid uuid or a malformed body is a message only). `VALIDATION_ERROR`: `fields` is a map from the field key to its messages (a list item field is `beneficial_owners[0].role`, the list as a whole `beneficial_owners`). `FORM_FIELD_NOT_ALLOWED`, `KYC_FORM_CONDITIONS_CYCLE`: `fields` is a list of keys. */
+        /** @description The structured payload of an error that carries one (absent otherwise — an invalid uuid or a malformed body is a message only). `VALIDATION_ERROR`: `fields` is a map from the field key to its messages (a list item field is `beneficial_owners[0].role`, the list as a whole `beneficial_owners`). `FORM_FIELD_NOT_ALLOWED`, `KYC_FORM_CONDITIONS_CYCLE`: `fields` is a list of keys. `KYC_TERMS_NOT_ACCEPTED`: `terms` — and no `fields`. */
         KycFormsErrorDetails: {
-            fields: {
+            fields?: {
                 [key: string]: string[];
             } | string[];
+            /**
+             * @description The ids of the terms documents of the form left out of `accepted_terms`.
+             * @example [
+             *       "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5"
+             *     ]
+             */
+            terms?: string[];
         };
         /** @description The error envelope of the KYC forms: `ErrorResponse` with the `details` of the field errors spelled out. */
         KycFormsErrorResponse: components["schemas"]["ErrorResponse"] & {
@@ -21098,6 +21198,15 @@ export interface components {
                 "application/json": components["schemas"]["KycFormsErrorResponse"];
             };
         };
+        /** @description `VALIDATION_ERROR` — field errors in `details.fields[key] = [message]` (on a business form the owner list the KYC tables refuse, and owner shares adding up to more than 100%, come back under `beneficial_owners`; a value sent for a field whose condition reads a source left empty or wrong comes back as the error of the source, e.g. `beneficial_owners[0].role`), or a message only for a malformed body (`schema_version` missing or longer than 64, `values` not an object, `accepted_terms` not a list of at most 200 uuids), an id in `accepted_terms` that is not a terms document of this form, and a path id that is not a uuid; `KYC_TERMS_NOT_ACCEPTED` — `accepted_terms` leaves out a terms document of the form, `details.terms` lists the ids left out, nothing is written; `FORM_FIELD_NOT_ALLOWED` — a key the form does not accept (unknown, locked, hidden, a file field), `details.fields = [key]`, the whole request refused; `FORM_TARGET_UNSUPPORTED` — a card program named on a business entity; `INVALID_REQUEST` — `wallet_id` missing for a form over card programs; `KYC_FORM_WALLET_NOT_LINKED` — `wallet_id` of a form over rails is not a wallet of this entity; `KYC_BASE_BINDING_MISSING` — the tenant has no base form for this client type; `KYC_FORMS_NOT_ENABLED` — the tenant is not on the forms flow */
+        KycFormsSubmitErrors: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["KycFormsErrorResponse"];
+            };
+        };
         /** @description `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle (`details.fields` lists the keys); nothing the client can fix, report it to support */
         KycFormsConditionsCycle: {
             headers: {

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

@@ -6930,6 +6930,11 @@ export interface paths {
          *     the same document cannot be registered twice at the vendor, so a fresh cardholder is
          *     NOT the way to retry. While a review is running, another submit is refused with `409`.
          *
+         *     A rejection no corrected dossier answers — a forged document, fraud, an attempt to
+         *     bypass the liveness check, or a regulatory bar (age, region, a duplicate applicant) —
+         *     is final: the submit is refused with `409 CARDHOLDER_REJECTION_FINAL`, and
+         *     `error.details.reject_reason` carries the vendor's reason.
+         *
          */
         post: {
             parameters: {
@@ -6971,7 +6976,7 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Cardholder is live at the vendor, or its review is still running. On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
+                /** @description Cardholder is live at the vendor, or its review is still running (`CARDHOLDER_NOT_DRAFT`). Its rejection is final and cannot be answered by a resubmit (`CARDHOLDER_REJECTION_FINAL`, `error.details.reject_reason`). On a program that issues under the wallet's company: `WALLET_BUSINESS_NOT_ONBOARDED` (the wallet's business has not been registered with the card issuer) or `WALLET_BUSINESS_NOT_APPROVED` (its review is not approved yet). */
                 409: {
                     headers: {
                         [name: string]: unknown;

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

@@ -873,7 +873,7 @@ export declare namespace API {
                 type Response = RailRoot['get']['responses'][200]['content']['application/json'];
             }
             export namespace Submit {
-                type Request = RailRoot['post']['parameters']['path'];
+                type Request = RailRoot['post']['parameters']['path'] & NonNullable<NonNullable<RailRoot['post']['requestBody']>['content']['application/json']>;
                 type Response = RailRoot['post']['responses'][200]['content']['application/json'];
                 type ErrorDetails = NonNullable<NonNullable<componentsV1Frontend['schemas']['WalletKycRailSubmitErrorResponse']['error']>['details']>;
             }
@@ -919,6 +919,8 @@ export declare namespace API {
             export type Form = Schemas['KycFormsForm'];
             export type FormScope = Form['scope'];
             export type FormSection = Form['sections'][number];
+            export type Terms = Schemas['KycFormsTerms'];
+            export type TermsItem = Terms['items'][number];
             export type FormState = Schemas['KycFormsFormState'];
             export type Field = Schemas['KycFormsField'];
             export type FieldType = Field['type'];

package/package.json

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