btrz-api-client 8.33.0 → 8.35.0

package/src/endpoints/btrzpay/oxxo.js

@@ -5,91 +5,118 @@ const {
 /**
  * Query params for GET /oxxo/:token/payments (btrz-api-payments). See get-payments-handler getSpec().
  * @typedef {Object} OxxoPaymentsListQuery
- * @property {string} [referenceNumber] - Payment reference number
+ * @property {string} referenceNumber - Payment reference number (required)
  */
 
 /**
- * Factory for OXXO API (btrz-api-payments).
+ * Request body for POST /oxxo/:token/payments/:referenceNumber. PostOxxoPaymentsPayload.
+ * @typedef {Object} PostOxxoPaymentsPayload
+ * @property {string} ticket - Oxxo sale ticket id
+ * @property {number} amount - Amount to pay in cents
+ * @property {string} folio - FEMSA transaction id
+ * @property {string} store - Store id
+ * @property {string} account - Account id (ObjectId)
+ */
+
+/**
+ * Request body for POST /oxxo/:token/reverse/:referenceNumber. PostOxxoReversePayload.
+ * @typedef {Object} PostOxxoReversePayload
+ * @property {string} ticket - Oxxo sale ticket id
+ * @property {number} amount - Amount in cents
+ * @property {string} folio - FEMSA transaction id
+ * @property {string} store - Store id
+ * @property {string} account - Account id (ObjectId)
+ */
+
+/**
+ * Factory for OXXO API (btrz-api-payments). Endpoints are hideInDocumentation; client for internal use.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
  * @returns {{ token: Object, payments: Object }}
  */
-function oxxoFactory({client, internalAuthTokenProvider: _internalAuthTokenProvider}) {
+function oxxoFactory({client, internalAuthTokenProvider}) {
+  function authProvider(opts) {
+    return opts !== undefined && opts !== null ? opts : internalAuthTokenProvider;
+  }
+
   const token = {
     /**
-     * GET /oxxo/token - get OXXO token. API does not accept query params.
+     * GET /oxxo/token - get new Oxxo token. No query params.
      * @param {Object} opts
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
      * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider]
      * @param {Object} [opts.headers] - Optional request headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ token: string }>>}
+     *   GetOxxoTokenResponse. Rejects with 401, 500.
      */
-    get({jwtToken, headers, internalAuthTokenProvider}) {
+    get({jwtToken, headers, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: "/oxxo/token",
-        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     }
   };
 
   const payments = {
     /**
-     * GET /oxxo/:oxxoToken/payments - list OXXO payments.
+     * GET /oxxo/:token/payments - list Oxxo payments by token and reference number.
      * @param {Object} opts
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.oxxoToken - OXXO token
-     * @param {OxxoPaymentsListQuery} [opts.query] - Query params (referenceNumber)
+     * @param {string} opts.oxxoToken - Oxxo token
+     * @param {OxxoPaymentsListQuery} opts.query - referenceNumber (required)
      * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider]
      * @param {Object} [opts.headers] - Optional request headers
-     * @returns {Promise<import("axios").AxiosResponse>} GetOxxoPaymentsResponse; 400 ERROR_GETTING_PAYMENT_METHODS
+     * @returns {Promise<import("axios").AxiosResponse<{ payments: Array }>>}
+     *   GetOxxoPaymentsResponse. Rejects with 400 (ERROR_GETTING_PAYMENT_METHODS, OXXO_PAY_NOT_ENABLED), 401, 500.
      */
-    all({jwtToken, headers, oxxoToken, query, internalAuthTokenProvider}) {
+    all({jwtToken, headers, oxxoToken, query, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: `/oxxo/${oxxoToken}/payments`,
         params: query,
-        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     },
     /**
-     * POST /oxxo/:oxxoToken/payments/:referenceNumber - update OXXO payment. API does not accept query params.
+     * POST /oxxo/:token/payments/:referenceNumber - pay Oxxo payment (referenceNumber: UUID v4 or 20 digits).
      * @param {Object} opts
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.oxxoToken - OXXO token
+     * @param {string} opts.oxxoToken - Oxxo token
      * @param {string} opts.referenceNumber - Payment reference number
-     * @param {Object} opts.data - Request body (PostOxxoPaymentsPayload)
+     * @param {PostOxxoPaymentsPayload|{ oxxoInfo: PostOxxoPaymentsPayload }} opts.data - Request body
      * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider]
      * @param {Object} [opts.headers] - Optional request headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ payment: Object }>>}
+     *   Rejects with 400 (INVALID_REFERENCE_NUMBER_FORMAT, INVALID_ACCOUNT, OXXO_PAY_NOT_ENABLED), 401, 500.
      */
-    update({jwtToken, headers, oxxoToken, query, referenceNumber, data, internalAuthTokenProvider}) {
+    update({jwtToken, headers, oxxoToken, query, referenceNumber, data, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: `/oxxo/${oxxoToken}/payments/${referenceNumber}`,
         method: "post",
         params: query,
         data,
-        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     },
     /**
-     * POST /oxxo/:oxxoToken/reverse/:referenceNumber - reverse OXXO payment. API does not accept query params.
+     * POST /oxxo/:token/reverse/:referenceNumber - reverse Oxxo payment (referenceNumber: UUID v4 or 20 digits).
      * @param {Object} opts
-     * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.oxxoToken - OXXO token
+     * @param {string} opts.oxxoToken - Oxxo token
      * @param {string} opts.referenceNumber - Payment reference number
-     * @param {Object} [opts.data] - Request body (PostOxxoReversePayload)
+     * @param {PostOxxoReversePayload|{ oxxoInfo: PostOxxoReversePayload }} [opts.data] - Request body
      * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider]
      * @param {Object} [opts.headers] - Optional request headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ payment: Object }>>}
+     *   Rejects with 400 (INVALID_REFERENCE_NUMBER_FORMAT, INVALID_ACCOUNT, OXXO_PAY_NOT_ENABLED), 401, 500.
      */
-    reverse({token: authToken, jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider, oxxoToken}) {
+    reverse({jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider: optsAuth, oxxoToken}) {
       return client({
         url: `/oxxo/${oxxoToken}/reverse/${referenceNumber}`,
         method: "post",
         params: query,
         data,
-        headers: authorizationHeaders({token: authToken, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     }
   };

package/src/endpoints/btrzpay/prismaTerminals.js

@@ -3,10 +3,11 @@ const {
 } = require("../endpoints_helpers.js");
 
 /**
- * Query params for GET payment/reversal/refund and PUT refund (btrz-api-payments). See get-by-id-* and put-refunds getSpec().
+ * Query params for Prisma terminals endpoints (btrz-api-payments).
  * @typedef {Object} PrismaTerminalsQuery
  * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
  * @property {boolean} [validateRefund] - (PUT refunds only) If true, fetch current state from Prisma before applying
+ * @property {boolean} [validatePayment] - (PUT payments only) If true, validate payment against the provider
  */
 
 /**
@@ -35,12 +36,13 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * POST /prisma-terminals/payments/:id/reversals - create reversal. API does not accept query params.
+     * POST /prisma-terminals/payments/:id/reversals - create reversal.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Payment id
+     * @param {string} opts.id - Payment id (prismaPaymentId)
      * @param {Object} opts.prismaReversal - Prisma reversal payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -54,11 +56,12 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * DELETE /prisma-terminals/reversals/:id - delete reversal. API does not accept query params.
+     * DELETE /prisma-terminals/reversals/:id - delete reversal.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Reversal id
+     * @param {string} opts.id - Reversal id (prismaPaymentId)
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -90,12 +93,13 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * POST /prisma-terminals/payments/:id/refunds - create refund. API does not accept query params.
+     * POST /prisma-terminals/payments/:id/refunds - create refund.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Payment id
+     * @param {string} opts.id - Payment id (prismaPaymentId)
      * @param {Object} opts.prismaRefund - Prisma refund payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -109,11 +113,12 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * DELETE /prisma-terminals/refunds/:id - delete refund. API does not accept query params.
+     * DELETE /prisma-terminals/refunds/:id - delete refund.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Refund id
+     * @param {string} opts.id - Refund id (prismaPaymentId)
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -165,11 +170,12 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * POST /prisma-terminals/payments - create payment. API does not accept query params.
+     * POST /prisma-terminals/payments - create payment.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
      * @param {Object} opts.prismaPayment - Prisma payment payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -183,11 +189,12 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * DELETE /prisma-terminals/payments/:id - delete payment. API does not accept query params.
+     * DELETE /prisma-terminals/payments/:id - delete payment.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Payment id
+     * @param {string} opts.id - Payment id (prismaPaymentId)
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -200,12 +207,13 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * PUT /prisma-terminals/payments/:id - update payment. API does not accept query params.
+     * PUT /prisma-terminals/payments/:id - update payment (hidden in API docs).
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Payment id
+     * @param {string} opts.id - Payment id (prismaPaymentId)
      * @param {Object} opts.prismaPayment - Prisma payment payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId, validatePayment)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */
@@ -224,11 +232,12 @@ function prismaTerminalsFactory({client, internalAuthTokenProvider}) {
 
   const settlements = {
     /**
-     * POST /prisma-terminals/settlements - create settlement. API does not accept query params.
+     * POST /prisma-terminals/settlements - create settlement.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
      * @param {Object} opts.settlement - Settlement payload
+     * @param {PrismaTerminalsQuery} [opts.query] - Query params (providerId)
      * @param {Object} [opts.headers] - Optional headers
      * @returns {Promise<import("axios").AxiosResponse>}
      */

package/src/endpoints/btrzpay/referenced-payments.js

@@ -15,14 +15,14 @@ const {authorizationHeaders} = require("./../endpoints_helpers.js");
  */
 function referencedPaymentsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /referenced-payments/:transactionId/:referenceNumber/status - get status. API does not accept query params.
+   * GET /referenced-payments/:transactionId/:referenceNumber/status - get referenced payment status. Requires backoffice auth. Response body: { paymentResult: { status, result } | null }.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.transactionId - Transaction id
-   * @param {string} opts.referenceNumber - Reference number
+   * @param {string} opts.transactionId - Transaction ID
+   * @param {string} opts.referenceNumber - Reference number of the payment
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ paymentResult: { status: "error"|"pending"|"success"|"review", result: object } | null }>>}
    */
   function getStatus({token, jwtToken, transactionId, referenceNumber, headers}) {
     return client.get(`/referenced-payments/${transactionId}/${referenceNumber}/status`, {

package/src/endpoints/btrzpay/square.js

@@ -3,7 +3,7 @@ const {
 } = require("./../endpoints_helpers.js");
 
 /**
- * Factory for Square webhooks API (btrz-api-payments).
+ * Factory for Square webhooks API (btrz-api-payments). Used to forward or simulate Square webhook requests to the Payments API.
  * @param {Object} deps
  * @param {import("axios").AxiosInstance} deps.client
  * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
@@ -11,14 +11,14 @@ const {
  */
 function squareWebhooksFactory({client, internalAuthTokenProvider}) {
   /**
-   * POST /square-webhooks/:providerId - create Square webhook. API does not accept query params.
+   * POST /square-webhooks/:providerId - send Square webhook payload to the Payments API. API verifies x-square-signature when present. Body must include type and data (Square webhook format).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.providerId - Provider id
-   * @param {Object} opts.data - Request body
-   * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @param {string} opts.providerId - Provider ID (square_terminal payment method owner)
+   * @param {Object} opts.data - Request body (Square webhook payload: type, data required; optional merchant_id, event_id, created_at)
+   * @param {Object} [opts.headers] - Optional headers (e.g. x-square-signature for verification)
+   * @returns {Promise<import("axios").AxiosResponse<{ status: "OK" }>>}
    */
   function create({token, jwtToken, data, providerId, headers}) {
     return client({
@@ -43,12 +43,12 @@ function squareWebhooksFactory({client, internalAuthTokenProvider}) {
  */
 function squareTerminalsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /square-terminals - get Square terminals. API does not accept query params.
+   * GET /square-terminals - list Square terminals for the account. Requires JWT (BETTEREZ_APP or MOBILE_SCANNER). Response body: { terminals } with terminal objects (id, name, code, deviceId, productType, locationId, status, pairBy, createdAt, statusChangedAt).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ terminals: Array<{ id: string, name: string, code: string, deviceId?: string, productType?: string, locationId: string, status?: string, pairBy?: string, createdAt?: string, statusChangedAt?: string }> }>>}
    */
   function get({token, jwtToken, headers}) {
     return client.get("/square-terminals", {

package/src/endpoints/btrzpay/stripe-terminals.js

@@ -5,7 +5,15 @@ const {
 /**
  * Query params for GET /stripe-terminals (btrz-api-payments). See get-handler getSpec().
  * @typedef {Object} StripeTerminalsListQuery
- * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers; when omitted, authenticated account ID is used
+ */
+
+/**
+ * Response for GET /stripe-terminals. Paginated list of Stripe readers.
+ * @typedef {Object} GetStripeTerminalsResponse
+ * @property {Object[]} stripeTerminals - Stripe Terminal reader objects (id, label, serial_number, status, etc.)
+ * @property {string} next - Next page link; empty if no next page
+ * @property {string} previous - Previous page link; empty if no previous page
  */
 
 /**
@@ -17,13 +25,13 @@ const {
  */
 function stripeTerminalsFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /stripe-terminals - list Stripe terminals.
+   * GET /stripe-terminals - list Stripe Terminal readers for the account (paginated).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {StripeTerminalsListQuery} [opts.query] - Query params (providerId)
+   * @param {StripeTerminalsListQuery} [opts.query] - Optional providerId
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<GetStripeTerminalsResponse>>} Rejects with 400 (STRIPE_SECRET_KEY_INVALID), 401, 404 (PAYMENT_METHOD_NOT_FOUND), 500.
    */
   function all({token, jwtToken, headers, query = {}}) {
     return client.get("/stripe-terminals", {
@@ -35,21 +43,20 @@ function stripeTerminalsFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /stripe-terminals/:id/simulate - simulate Stripe payment. API does not accept query params.
+   * POST /stripe-terminals/:terminalId/simulate - simulate a payment on a Stripe Terminal reader. API does not accept query params.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
    * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.id - Terminal id
-   * @param {Object} opts.stripePayment - Stripe payment payload
+   * @param {string} opts.id - Terminal ID (Stripe reader id, e.g. tmr_xxx)
+   * @param {{ ccNumber: string }} opts.stripePayment - Payment to simulate; ccNumber required
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ stripeTerminalPayment: Object }>>} Rejects with 400 (WRONG_DATA), 401, 404 (PAYMENT_METHOD_NOT_FOUND, TRANSACTION_NOT_FOUND), 409 (errorCode/errorMessage), 500.
    */
-  function simulate({token, jwtToken, id, stripePayment, query = {}, headers}) {
+  function simulate({token, jwtToken, id, stripePayment, headers}) {
     return client({
       url: `/stripe-terminals/${id}/simulate`,
       method: "post",
       headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers}),
-      params: query,
       data: {stripePayment}
     });
   }

package/src/endpoints/btrzpay/stripe3ds.js

@@ -0,0 +1,40 @@
+/* eslint-disable max-len */
+const {authorizationHeaders} = require("../endpoints_helpers.js");
+
+/**
+ * Request body for POST /stripe-payment-intent (btrz-api-payments). PaymentIntentPostData.
+ * @typedef {Object} PaymentIntentPostData
+ * @property {string} providerName - Provider name (e.g. "stripe") used to resolve the payment method with Stripe 3DS
+ * @property {Object} data - Payment data: card details, amount, currency, transactionId, customer info, etc.
+ */
+
+/**
+ * Factory for Stripe 3DS API (btrz-api-payments): create Stripe Payment Intent for 3DS flows.
+ * @param {Object} deps
+ * @param {import("axios").AxiosInstance} deps.client
+ * @param {{ getToken: function(): string }} [deps.internalAuthTokenProvider]
+ * @returns {{ createPaymentIntent: function }}
+ */
+function stripe3dsFactory({client, internalAuthTokenProvider}) {
+  /**
+   * POST /stripe-payment-intent - creates a Stripe Payment Intent for 3DS; returns requires_action and payment_intent_client_secret.
+   * @param {Object} opts
+   * @param {string} [opts.token] - API key
+   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} opts.providerName - Provider name (e.g. "stripe")
+   * @param {Object} opts.data - Payment data (card, amount, currency, transactionId, etc.)
+   * @param {Object} [opts.headers] - Optional request headers
+   * @returns {Promise<import("axios").AxiosResponse<{ requires_action: boolean, payment_intent_client_secret: string }>>} PaymentIntentResponse. Rejects with 400 (WRONG_DATA, PAYMENT_INTENT_MISSING_PAYMENT_DATA, PAYMENT_INTENT_MISSING_PROVIDER, PROVIDER_NOT_FOUND, MISSING_PAYMENT_METHOD_PARAMS, PAYMENT_METHOD_NOT_FOUND, STRIPE_MISSING_PRIVATE_KEY, MISSING_PAYMENT_DATA), 401, 500.
+   */
+  function createPaymentIntent({token, jwtToken, providerName, data, headers}) {
+    return client.post("/stripe-payment-intent", {providerName, data}, {
+      headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+    });
+  }
+
+  return {
+    createPaymentIntent
+  };
+}
+
+module.exports = stripe3dsFactory;

package/src/endpoints/btrzpay/terminalPayments.js

@@ -5,10 +5,10 @@ const {
 /**
  * Query params for GET /terminal-payments/mit/:id (btrz-api-payments). See get-mit-by-id-handler getSpec().
  * @typedef {Object} TerminalPaymentsMitGetQuery
- * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers
- * @property {string} [branchId] - Branch id where payment started (required for GET)
- * @property {string} [companyId] - Company id where payment started (required for GET)
- * @property {string} [date] - Date when payment started; format dd/mm/yyyy (required for GET)
+ * @property {string} [providerId] - Account provider (operator) ID; used by agencies/sellers; when omitted, authenticated account is used
+ * @property {string} branchId - Branch id where payment started (required). Example: 00676
+ * @property {string} companyId - Company id where payment started (required). Example: Z890
+ * @property {string} date - Date when payment started; format dd/mm/yyyy (required)
  */
 
 /**
@@ -27,15 +27,15 @@ const {
 function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
   const mit = {
     /**
-     * PUT /terminal-payments/mit/:id - update MIT terminal payment.
+     * PUT /terminal-payments/mit/:terminalPaymentId - complete MIT terminal payment with result from terminal.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Terminal payment id
-     * @param {Object} opts.terminalPayment - Terminal payment payload
-     * @param {TerminalPaymentsMitPutQuery} [opts.query] - Query params (providerId)
+     * @param {string} opts.id - Terminal payment ID (UUID)
+     * @param {{ result?: Object, paymentRequest: Object, orderId: string }} opts.terminalPayment - Terminal payment data (result, paymentRequest, orderId)
+     * @param {TerminalPaymentsMitPutQuery} [opts.query] - Optional providerId
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ terminalPayment: Object }>>} Rejects with 400 (WRONG_DATA, INVALID_TERMINALPAYMENT_ID, INVALID_RESULT_OBJECT, MIT_*), 401, 404 (TERMINALPAYMENT_NOT_FOUND, MIT_PAYMENT_NOT_FOUND), 409 (CANT_UPDATE_ORDER), 500.
      */
     update({token, jwtToken, id, terminalPayment, query = {}, headers}) {
       return client({
@@ -47,14 +47,14 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
       });
     },
     /**
-     * GET /terminal-payments/mit/:id - get MIT terminal payment.
+     * GET /terminal-payments/mit/:terminalPaymentId - get MIT terminal payment result from MIT servers.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.id - Terminal payment id
-     * @param {TerminalPaymentsMitGetQuery} [opts.query] - Query params (providerId, branchId, companyId, date)
+     * @param {string} opts.id - Terminal payment ID (UUID)
+     * @param {TerminalPaymentsMitGetQuery} opts.query - branchId, companyId, date (required); optional providerId
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @returns {Promise<import("axios").AxiosResponse<{ terminalPayment: Object }>>} Rejects with 400 (WRONG_DATA, INVALID_TERMINALPAYMENT_ID, INVALID_DATE, MIT_*), 401, 404 (TERMINALPAYMENT_NOT_FOUND, MIT_PAYMENT_NOT_FOUND), 500.
      */
     get({token, jwtToken, id, query = {}, headers}) {
       return client.get(`/terminal-payments/mit/${id}`, {
@@ -66,14 +66,14 @@ function terminalPaymentsFactory({client, internalAuthTokenProvider}) {
 
   const webhooks = {
     /**
-     * POST /terminal-payments/webhooks/getnet/:providerId - Getnet webhook. API does not accept query params.
+     * POST /terminal-payments/webhooks/getnet/:providerId - Getnet Terminal webhook (inbound). API does not accept query params.
      * @param {Object} opts
-     * @param {Object} opts.data - Request body
-     * @param {string} opts.providerId - Provider id
+     * @param {Object} opts.data - Getnet webhook payload (e.g. TrxResult, TrxReference, userId)
+     * @param {string} opts.providerId - Provider (account) ID for getnet_terminal payment method
      * @param {Object} [opts.headers] - Optional headers
-     * @param {string} [opts.token] - API key
-     * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @param {string} [opts.token] - API key (optional when no userId in payload)
+     * @param {string} [opts.jwtToken] - JWT or internal auth (required when userId is in payload)
+     * @returns {Promise<import("axios").AxiosResponse<{ status: string }>>} Rejects with 400 (INVALID_WEBHOOK_PAYLOAD), 401 (when userId present but not authenticated), 404 (PAYMENT_NOT_FOUND_FOR_WEBHOOK_EVENT, PAYMENT_METHOD_NOT_FOUND, USER_NOT_FOUND), 409 (CANT_UPDATE_ORDER), 500.
      */
     getnet({data, providerId, headers = {}, token, jwtToken}) {
       const _headers = token && jwtToken ?

package/src/endpoints/inventory/banks.js

@@ -11,12 +11,15 @@ const {
  */
 function banksFactory({client, internalAuthTokenProvider}) {
   /**
-   * GET /banks - list banks. API does not accept query params.
+   * GET /banks — List banks for the account. Paginated; optional page query param (1-based).
    * @param {Object} opts
-   * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
+   * @param {string} [opts.token] - API key (X-API-KEY)
+   * @param {string} [opts.jwtToken] - JWT or internal auth (Authorization: Bearer)
+   * @param {Object} [opts.query] - Query params: page (1-based page number)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ banks: Object[], count: number, next: string, previous: string }>>}
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function all({
     token,
@@ -31,13 +34,17 @@ function banksFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * GET /banks/:bankId - get bank by id. API does not accept query params.
+   * GET /banks/:bankId — Get a single bank by ID (24 hex characters).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.bankId - Bank id
+   * @param {string} [opts.jwtToken] - JWT or internal auth
+   * @param {string} opts.bankId - Bank id (24 hex characters)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ bank: Object }>>}
+   * @throws 400 INVALID_BANK_ID
+   * @throws 401 Unauthorized
+   * @throws 404 BANK_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function get({bankId, token, headers, jwtToken}) {
     return client.get(`/banks/${bankId}`, {
@@ -46,13 +53,16 @@ function banksFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * POST /banks - create bank. API does not accept query params.
+   * POST /banks — Create a bank. Body: BankPostData (name, accountNumbers required; optional depositAlgorithmCode).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {Object} opts.bank - Bank payload
+   * @param {string} [opts.jwtToken] - JWT or internal auth
+   * @param {Object} opts.bank - Bank payload (name, accountNumbers; each accountNumber: number, currency, alias)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ bank: Object }>>}
+   * @throws 400 WRONG_DATA, STATION_INVALID_COST_CENTER
+   * @throws 401 Unauthorized
+   * @throws 500 Internal server error
    */
   function create({jwtToken, token, bank, headers}) {
     return client({
@@ -66,13 +76,17 @@ function banksFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * DELETE /banks/:bankId - remove bank. API does not accept query params.
+   * DELETE /banks/:bankId — Delete a bank by ID.
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.bankId - Bank id
+   * @param {string} [opts.jwtToken] - JWT or internal auth
+   * @param {string} opts.bankId - Bank id (24 hex characters)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ bankId: string }>>}
+   * @throws 400 BANK_ID
+   * @throws 401 Unauthorized
+   * @throws 404 BANK_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function remove({jwtToken, bankId, token, headers}) {
     return client({
@@ -83,14 +97,18 @@ function banksFactory({client, internalAuthTokenProvider}) {
   }
 
   /**
-   * PUT /banks/:bankId - update bank. API does not accept query params.
+   * PUT /banks/:bankId — Update a bank by ID. Body: BankPostData (name, accountNumbers required).
    * @param {Object} opts
    * @param {string} [opts.token] - API key
-   * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-   * @param {string} opts.bankId - Bank id
-   * @param {Object} opts.bank - Bank payload
+   * @param {string} [opts.jwtToken] - JWT or internal auth
+   * @param {string} opts.bankId - Bank id (24 hex characters)
+   * @param {Object} opts.bank - Bank payload (name, accountNumbers; each accountNumber: number, currency, alias)
    * @param {Object} [opts.headers] - Optional headers
-   * @returns {Promise<import("axios").AxiosResponse>}
+   * @returns {Promise<import("axios").AxiosResponse<{ bank: Object }>>}
+   * @throws 400 WRONG_DATA, STATION_INVALID_COST_CENTER
+   * @throws 401 Unauthorized
+   * @throws 404 BANK_NOT_FOUND
+   * @throws 500 Internal server error
    */
   function update({jwtToken, token, bankId, bank, headers}) {
     return client({