squarefi-bff-api-module 1.36.103 → 1.36.105

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

@@ -2896,6 +2896,19 @@ export interface paths {
                         "application/json": components["schemas"]["ApiErrorResponse"];
                     };
                 };
+                /** @description `CARDHOLDER_REFUSED` — no card can be issued on this cardholder; anything charged was returned. Either the card
+                 *     issuer refused the person, or the cardholder does not qualify: no email, not submitted, short of the program's
+                 *     KYC requirements, or their identity review came back rejected; `message` says which. A review still in
+                 *     progress is not a refusal: it answers `400 INVALID_REQUEST`.
+                 *      */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiErrorResponse"];
+                    };
+                };
                 /** @description Internal Server Error */
                 500: {
                     headers: {

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

@@ -3500,7 +3500,11 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description `CARDHOLDER_REFUSED` — the card issuer refused the cardholder; anything charged was returned */
+                /** @description `CARDHOLDER_REFUSED` — no card can be issued on this cardholder; anything charged was returned. Either the card
+                 *     issuer refused the person, or the cardholder does not qualify: no email, not submitted, short of the program's
+                 *     KYC requirements, or their identity review came back rejected; `message` says which. A review still in
+                 *     progress is not a refusal: it answers `400 INVALID_REQUEST`.
+                 *      */
                 422: {
                     headers: {
                         [name: string]: unknown;
@@ -17276,7 +17280,7 @@ export interface paths {
         put?: never;
         /**
          * Email the owners their identity check links again
-         * @description A business entity whose base form was sent (step 8/8 of the KYC forms). Asks the identity provider to email the owners the link to their identity check once more. The provider writes every person linked to the company who has an email with it and has not passed the check — one addressee at a time is not offered: the owners whose item has `invite_by_email: true` and an email, and the person filling the form (their applicant carries the email of their account; they can still pass the check from the app through `POST …/verification/session`). An owner who has passed, or whose check is with the provider, is not written; a company among the owners (`type: company`) never is. The first mailing goes on its own right after the form is sent — this route repeats it, at most once in 10 minutes per business, the first mailing counted: `GET …/overview` shows `verification.invites.sent_at` and `next_at`, and `verification.owners[].invited_at` per owner. Nobody left to email (`400 KYC_NO_OWNER_TO_INVITE`): hand the link over through `…/owners/{owner_id}/link` or `/session`. Takes no body. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to. One mailing per entity at a time, and none while the set-up after the sent form is running (`409 OPERATION_IN_PROGRESS`).
+         * @description A business entity whose base form was sent (step 8/8 of the KYC forms). Asks the identity provider to email the owners the link to their identity check once more. The provider writes every person linked to the company who has an email with it and has not passed the check — one addressee at a time is not offered: the owners whose item has `invite_by_email: true` (their email is required by the form, an owner saved before that may still have none), and the person filling the form (their applicant carries the email of their account; they can still pass the check from the app through `POST …/verification/session`). An owner who has passed, or whose check is with the provider, is not written; a company among the owners (`type: company`) never is. The first mailing goes on its own right after the form is sent — this route repeats it, at most once in 10 minutes per business, the first mailing counted: `GET …/overview` shows `verification.invites.sent_at` and `next_at`, and `verification.owners[].invited_at` per owner. Nobody left to email (`400 KYC_NO_OWNER_TO_INVITE`): hand the link over through `…/owners/{owner_id}/link` or `/session`. Takes no body. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to. One mailing per entity at a time, and none while the set-up after the sent form is running (`409 OPERATION_IN_PROGRESS`).
          */
         post: {
             parameters: {
@@ -17324,7 +17328,7 @@ export interface paths {
                         };
                     };
                 };
-                /** @description `KYC_NO_OWNER_TO_INVITE` — nobody is left to email: every owner with an email at the identity provider has passed the check, or none has an email there (hand the link over: `…/owners/{owner_id}/link` or `/session`); `VALIDATION_ERROR` — `entity_id` is not a uuid; `KYC_FORMS_NOT_ENABLED`; `VERIFICATION_PROVIDER_UNAVAILABLE` — the identity provider refused or did not answer, try later; `VERIFICATION_PROVIDER_NOT_CONFIGURED`. */
+                /** @description `KYC_NO_OWNER_TO_INVITE` — nobody is left to email: every owner with an email at the identity provider has passed the check, or none has an email there — an owner whose item has no `invite_by_email: true` has none at the provider, whatever email the form holds (hand the link over: `…/owners/{owner_id}/link` or `/session`); `VALIDATION_ERROR` — `entity_id` is not a uuid; `KYC_FORMS_NOT_ENABLED`; `VERIFICATION_PROVIDER_UNAVAILABLE` — the identity provider refused or did not answer, try later; `VERIFICATION_PROVIDER_NOT_CONFIGURED`. */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -17365,7 +17369,7 @@ export interface paths {
         put?: never;
         /**
          * The identity check link of a beneficial owner, to hand over yourself
-         * @description A business entity whose base form was sent (step 8/8 of the KYC forms). CORE makes sure the owner has an applicant with the identity provider — created from what the form declared about them, so the provider compares it with the document — and answers a link to the provider's own check page for it, for the filler to pass on by their own channel. After the form is sent the identity provider itself emails the link to the owners whose item has `invite_by_email: true` and an email (and to the filler), and `POST …/verification/owners/invite` has it email them again, at most once in 10 minutes; this route is for an owner without an email, or to pass the link on by your own channel. Valid 7 days; every call makes a new link for the same applicant, the previous one keeps working until it expires. The outcome arrives through the provider's webhook: `GET …/overview` shows it under `verification.owners[]`. Takes no body. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to.
+         * @description A business entity whose base form was sent (step 8/8 of the KYC forms). CORE makes sure the owner has an applicant with the identity provider — created from what the form declared about them, so the provider compares it with the document — and answers a link to the provider's own check page for it, for the filler to pass on by their own channel. After the form is sent the identity provider itself emails the link to the owners whose item has `invite_by_email: true` (and to the filler), and `POST …/verification/owners/invite` has it email them again, at most once in 10 minutes; this route is for an owner whose item has no `invite_by_email: true`, or to pass the link on by your own channel. Valid 7 days; every call makes a new link for the same applicant, the previous one keeps working until it expires. The outcome arrives through the provider's webhook: `GET …/overview` shows it under `verification.owners[]`. Takes no body. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to.
          */
         post: {
             parameters: {
@@ -17510,7 +17514,7 @@ export interface paths {
         put?: never;
         /**
          * Upload a beneficial owner's identity document for them
-         * @description Multipart: `file` (JPEG or PNG up to 20 MB, told by the bytes — the provider takes photos only, a PDF is refused), `side` (`front` or `back`; a passport has only a front side, so `back` needs a `type` other than `passport`), optional `type` (`passport` by default) and `country` (alpha-2 from the country directory — `DE`, not `DEU` or `Germany`; the owner's citizenship by default). The file is filed as the owner's `gov_id_front` / `gov_id_back` document (`source: client`, not verified) and handed to the identity provider as the owner's document; the owner still passes the face check by the link or the widget. The owner's applicant is created when missing. A file of another format is refused with `DOCUMENT_REJECTED`. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to.
+         * @description Multipart: `file` (JPEG or PNG up to 20 MB, told by the bytes — the provider takes photos only, a PDF is refused), `side` (`front` or `back`; a passport has only a front side, so `back` needs a `type` other than `passport`), optional `type` (`passport` by default) and `country` (alpha-2 from the country directory — `DE`, not `DEU` or `Germany`; the owner's citizenship by default). The file is filed as the owner's `gov_id_front` / `gov_id_back` document (`source: client`, not verified) and handed to the identity provider as the owner's document; the owner still passes the face check by the link or the widget. The owner's applicant is created when missing. A file of another format is refused with `DOCUMENT_REJECTED`. An owner without a citizenship needs `country`: without it the upload answers `400 VALIDATION_ERROR` with `details.fields.country`, and nothing reaches the provider. Access: the owner of the business entity, or an owner / admin of a wallet it is linked to.
          */
         post: {
             parameters: {
@@ -17544,7 +17548,7 @@ export interface paths {
                          */
                         type?: "PASSPORT" | "ID_CARD" | "RESIDENCE_PERMIT" | "DRIVERS" | "passport" | "id_card" | "residence_permit" | "driving_license";
                         /**
-                         * @description Alpha-2 of the issuing country, a code the country directory knows; the owner's citizenship when omitted.
+                         * @description Alpha-2 of the issuing country, a code the country directory knows; the owner's citizenship when omitted. Required when the owner has no citizenship.
                          * @example DE
                          */
                         country?: string;
@@ -17573,7 +17577,7 @@ export interface paths {
                         };
                     };
                 };
-                /** @description The errors of `KycFormsOwnerErrors`; `VALIDATION_ERROR` — a `side` or `type` outside the list, `side: back` of a passport (the default type), or a `country` that is not a known alpha-2 code; `DOCUMENT_REJECTED` — a file that is not JPEG or PNG (a PDF included), empty, or over 20 MB; `INVALID_REQUEST` — no `file` part (or more than one), or an unreadable multipart body. */
+                /** @description The errors of `KycFormsOwnerErrors`; `VALIDATION_ERROR` — a `side` or `type` outside the list, `side: back` of a passport (the default type), a `country` that is not a known alpha-2 code, or no `country` for an owner without a citizenship (`details.fields.country`); `DOCUMENT_REJECTED` — a file that is not JPEG or PNG (a PDF included), empty, or over 20 MB; `INVALID_REQUEST` — no `file` part (or more than one), or an unreadable multipart body. */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -20920,7 +20924,7 @@ export interface components {
             saved: boolean;
         };
         /**
-         * @description One item of a `list` field (`beneficial_owners`): an object keyed by the `item.fields[].key` of the field, each value shaped by that item field's `type` (an item field never takes files). `id` is set on a row already saved in the KYC entity (for an owner, the `owner_id` of the owner routes); send it back to keep the row, leave it out for a new one. A saved row is the entity's: the client never removes it — a list (or a draft's list, an empty or `null` one included) without an `id` the form gave is refused with `VALIDATION_ERROR` on the list key, «A saved beneficial owner cannot be removed; contact support»; compliance removes one. Nor does its `owner_type` change, nor is a saved value of it cleared (sent empty: `VALIDATION_ERROR` on the item field, «A saved value cannot be cleared; correct it or contact support»; left out of the item: kept). On a `returned` form the client corrects the other values of the item fields the form asks; outside a return a changed saved value is refused (`VALIDATION_ERROR`, «A saved value cannot be changed; contact support»). Messages come in the language of the form. Do not offer to delete an item with an `id`, nor to change its type. An item with `owner_type: business` requires `corporate_name`, `corporate_country` and `corporate_registration_number` (the form marks them `required` on the item fields): without them the identity provider cannot set the company up, so the submission is refused with `VALIDATION_ERROR` on the item field.
+         * @description One item of a `list` field (`beneficial_owners`): an object keyed by the `item.fields[].key` of the field, each value shaped by that item field's `type` (an item field never takes files). `id` is set on a row already saved in the KYC entity (for an owner, the `owner_id` of the owner routes); send it back to keep the row, leave it out for a new one. A saved row is the entity's: the client never removes it — a list (or a draft's list, an empty or `null` one included) without an `id` the form gave is refused with `VALIDATION_ERROR` on the list key, «A saved beneficial owner cannot be removed; contact support»; compliance removes one. Nor does its `owner_type` change, nor is a saved value of it cleared (sent empty: `VALIDATION_ERROR` on the item field, «A saved value cannot be cleared; correct it or contact support»; left out of the item: kept). On a `returned` form the client corrects the other values of the item fields the form asks; outside a return a changed saved value is refused (`VALIDATION_ERROR`, «A saved value cannot be changed; contact support»). Messages come in the language of the form. Do not offer to delete an item with an `id`, nor to change its type. An item with `owner_type: business` requires `corporate_name`, `corporate_country` and `corporate_registration_number` (the form marks them `required` on the item fields): without them the identity provider cannot set the company up, so the submission is refused with `VALIDATION_ERROR` on the item field. An item with `owner_type: individual` other than the filler's own requires `email` (the form marks it `required` on the item fields, whatever `invite_by_email` and the tenant's profiles say): a submission without it, a saved owner of a returned form included, is refused with `VALIDATION_ERROR` on `beneficial_owners[i].email` (required); the draft takes it empty. The filler's own item (`is_applicant: true`) has no `email` field — the email of their account is used. The email is kept either way; `invite_by_email: true` is what has the identity provider email the owner their link to it.
          * @example {
          *       "id": "2d7c1b9e-4f30-4a8c-9e21-7b6a5c4d3e2f",
          *       "owner_type": "individual",
@@ -21245,9 +21249,22 @@ export interface components {
                         state: components["schemas"]["KycFormsVerificationState"];
                         /**
                          * Format: date-time
-                         * @description When the identity provider last emailed this owner their link — after the form was sent and on each `POST …/verification/owners/invite`, to the persons whose item has `invite_by_email: true` and an email; the filler's row too (through the email of their account); null = never (the owner gets the link by hand: `…/owners/{owner_id}/link` or `/session`); always null for a company.
+                         * @description When the identity provider last emailed this owner their link — after the form was sent and on each `POST …/verification/owners/invite`, to the persons whose item has `invite_by_email: true` (the email is required by the form); the filler's row too (through the email of their account); null = never (the owner gets the link by hand: `…/owners/{owner_id}/link` or `/session`); always null for a company.
                          */
                         invited_at: string | null;
+                        /** @description The files of the owner's identity document on record: uploaded through `…/owners/{owner_id}/document`, or read from the provider after the owner passed. One item per side however many times it was uploaded. It says a file is there, not that the provider accepted it: `state` tells that, and the item stays after a refusal. Neither the file nor the kind of document (a passport or an ID card) is given. Empty for a company and for the filler's own row. */
+                        documents: {
+                            /**
+                             * @description The side, as `type` in the answer of the upload.
+                             * @enum {string}
+                             */
+                            key: "gov_id_front" | "gov_id_back";
+                            /**
+                             * @description The name of the field, in the language of the request.
+                             * @example Identity document photo
+                             */
+                            label: string;
+                        }[];
                     }[];
                     /** @description The mailing of the owners' links of a business with a base form; null for a personal entity. */
                     invites: {
@@ -21532,7 +21549,7 @@ export interface components {
                 "application/json": components["schemas"]["ErrorResponse"];
             };
         };
-        /** @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 saved beneficial owner (an item with an `id`) left out of the list — an empty or `null` list included — comes back under `beneficial_owners`, a saved value of it changed outside a `returned` form, or sent empty, under `beneficial_owners[i].<field>`, and nothing is saved; 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`; a `multi_enum` field with an option that excludes the others (`options[].exclusive`) chosen together with another one comes back under the field, on the draft too), or a message only for a malformed body (`schema_version` missing or longer than 64, `values` not an object) and a path id that is not a uuid; `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_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 */
+        /** @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`; an individual beneficial owner other than the filler without an `email` comes back under `beneficial_owners[i].email` on a submission (the draft takes it empty); a saved beneficial owner (an item with an `id`) left out of the list — an empty or `null` list included — comes back under `beneficial_owners`, a saved value of it changed outside a `returned` form, or sent empty, under `beneficial_owners[i].<field>`, and nothing is saved; 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`; a `multi_enum` field with an option that excludes the others (`options[].exclusive`) chosen together with another one comes back under the field, on the draft too), or a message only for a malformed body (`schema_version` missing or longer than 64, `values` not an object) and a path id that is not a uuid; `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_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 */
         KycFormsFieldErrors: {
             headers: {
                 [name: string]: unknown;

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

@@ -1381,8 +1381,10 @@ export declare namespace API {
                     /**
                      * An ACTIVE cardholder is linked (`cardholder_id`), but it does not hold what the
                      * program's ISSUANCE bar asks for — typically one written before that bar existed.
-                     * Creating a card now is refused with `400`; `will_require` names the same fields
-                     * that 400 would. Nothing is submitted again: `PATCH` the fields, and for the
+                     * Creating a card now is refused with `422 CARDHOLDER_REFUSED`, whose `message` lists
+                     * the same missing fields as `will_require`. The refusal holds for the cardholder as
+                     * it is: once completed, the same cardholder can get the card. Nothing is submitted
+                     * again: `PATCH` the fields, and for the
                      * document photos call `POST /cardholders` with the member's `user_data_id` — it
                      * answers `409` with this `cardholder_id` after completing the row from the
                      * member's KYC dossier. When the member has not passed that verification, run it first.

package/package.json

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