btrz-api-client 8.33.0 → 8.35.0

package/lib/endpoints/btrzpay/datalogic.js

@@ -6,11 +6,30 @@ var _require = require("./../endpoints_helpers.js"),
 /**
  * Query params for GET /datalogic/payments (btrz-api-payments). See get-payments-handler getSpec().
  * @typedef {Object} DatalogicPaymentsListQuery
- * @property {string} [referenceNumber] - The payment reference number
+ * @property {string} referenceNumber - Payment reference number (required)
  */
 
 /**
- * Factory for Datalogic API (btrz-api-payments).
+ * Request body for POST /datalogic/payments/:referenceNumber. PostDatalogicPaymentsPayload.
+ * @typedef {Object} PostDatalogicPaymentsPayload
+ * @property {string} folio - FEMSA transaction id
+ * @property {number} id_terminal - Terminal/group ID
+ * @property {string} local_date - Local date (e.g. "02/08/2022 20:33:43")
+ * @property {string} amount - Debt amount
+ * @property {number} trx_no - Transaction number
+ */
+
+/**
+ * Request body for POST /datalogic/reverse/:referenceNumber. PostDatalogicReversePayload.
+ * @typedef {Object} PostDatalogicReversePayload
+ * @property {string} folio - FEMSA transaction id
+ * @property {number} id_terminal - Terminal/group ID
+ * @property {string} local_date - Local date (e.g. "02/08/2022 20:33:43")
+ * @property {number} trx_no - Transaction number
+ */
+
+/**
+ * Factory for Datalogic 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]
@@ -19,41 +38,51 @@ var _require = require("./../endpoints_helpers.js"),
 
 
 function datalogicFactory(_ref) {
-  var client = _ref.client;
+  var client = _ref.client,
+      internalAuthTokenProvider = _ref.internalAuthTokenProvider;
+
+  function authProvider(opts) {
+    return opts !== undefined && opts !== null ? opts : internalAuthTokenProvider;
+  }
 
   var payments = {
     /**
-     * GET /datalogic/payments - list Datalogic payments.
+     * GET /datalogic/payments - list Datalogic payments by reference number.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {DatalogicPaymentsListQuery} [opts.query] - Query params (referenceNumber)
+     * @param {DatalogicPaymentsListQuery} opts.query - referenceNumber (required)
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - Internal auth provider
+     * @returns {Promise<import("axios").AxiosResponse<{ payments: Array }>>}
+     *   GetDatalogicPaymentsResponse. Rejects 400, 401, 500.
      */
     all: function all(_ref2) {
       var token = _ref2.token,
           jwtToken = _ref2.jwtToken,
           headers = _ref2.headers,
           query = _ref2.query,
-          internalAuthTokenProvider = _ref2.internalAuthTokenProvider;
+          optsAuth = _ref2.internalAuthTokenProvider;
 
       return client({
         url: "/datalogic/payments",
         params: query,
-        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     },
 
     /**
-     * POST /datalogic/payments/:referenceNumber - update Datalogic payment. API does not accept query params.
+     * POST /datalogic/payments/:referenceNumber - pay by reference (20 digits).
+     * Body: datalogicInfo or flat PostDatalogicPaymentsPayload.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.referenceNumber - Reference number
-     * @param {Object} [opts.data] - Request body
+     * @param {string} opts.referenceNumber - Reference number (20 digits)
+     * @param {PostDatalogicPaymentsPayload|{ datalogicInfo: PostDatalogicPaymentsPayload }} opts.data - Body
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - Internal auth provider
+     * @returns {Promise<import("axios").AxiosResponse<{ payment: Object }>>}
+     *   PostDatalogicPaymentsResponse. Rejects 400, 401, 500.
      */
     update: function update(_ref3) {
       var token = _ref3.token,
@@ -62,26 +91,29 @@ function datalogicFactory(_ref) {
           query = _ref3.query,
           referenceNumber = _ref3.referenceNumber,
           data = _ref3.data,
-          internalAuthTokenProvider = _ref3.internalAuthTokenProvider;
+          optsAuth = _ref3.internalAuthTokenProvider;
 
       return client({
         url: "/datalogic/payments/" + referenceNumber,
         method: "post",
         params: query,
         data: data,
-        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     },
 
     /**
-     * POST /datalogic/reverse/:referenceNumber - reverse Datalogic payment. API does not accept query params.
+     * POST /datalogic/reverse/:referenceNumber - reverse by reference (20 digits).
+     * Body: datalogicReverseInfo or flat PostDatalogicReversePayload.
      * @param {Object} opts
      * @param {string} [opts.token] - API key
      * @param {string} [opts.jwtToken] - JWT or internal auth symbol
-     * @param {string} opts.referenceNumber - Reference number
-     * @param {Object} [opts.data] - Request body
+     * @param {string} opts.referenceNumber - Reference number (20 digits)
+     * @param {PostDatalogicReversePayload|{ datalogicReverseInfo: PostDatalogicReversePayload }} opts.data - Body
      * @param {Object} [opts.headers] - Optional headers
-     * @returns {Promise<import("axios").AxiosResponse>}
+     * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - Internal auth provider
+     * @returns {Promise<import("axios").AxiosResponse<{ payment: Object }>>}
+     *   PostDatalogicPaymentsResponse. Rejects 400, 401, 500.
      */
     reverse: function reverse(_ref4) {
       var token = _ref4.token,
@@ -90,58 +122,62 @@ function datalogicFactory(_ref) {
           query = _ref4.query,
           referenceNumber = _ref4.referenceNumber,
           data = _ref4.data,
-          internalAuthTokenProvider = _ref4.internalAuthTokenProvider;
+          optsAuth = _ref4.internalAuthTokenProvider;
 
       return client({
         url: "/datalogic/reverse/" + referenceNumber,
         method: "post",
         params: query,
         data: data,
-        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     }
   };
 
   var referenceNumber = {
     /**
-     * GET /datalogic/reference-number - get reference number. API does not accept query params.
+     * GET /datalogic/reference-number - get new Datalogic reference number.
      * @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>}
+     * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - Internal auth provider
+     * @returns {Promise<import("axios").AxiosResponse<{ referenceNumber: string }>>}
+     *   GetDatalogicReferenceNumberResponse. Rejects 401, 404, 500.
      */
     get: function get(_ref5) {
       var token = _ref5.token,
           jwtToken = _ref5.jwtToken,
           headers = _ref5.headers,
-          internalAuthTokenProvider = _ref5.internalAuthTokenProvider;
+          optsAuth = _ref5.internalAuthTokenProvider;
 
       return client({
         url: "/datalogic/reference-number",
-        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     }
   };
 
   var authCode = {
     /**
-     * GET /datalogic/auth-code - get auth code. API does not accept query params.
+     * GET /datalogic/auth-code - get new Datalogic authorization code.
      * @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>}
+     * @param {{ getToken: function(): string }} [opts.internalAuthTokenProvider] - Internal auth provider
+     * @returns {Promise<import("axios").AxiosResponse<{ authCode: string }>>}
+     *   GetDatalogicAuthCodeResponse. Rejects 401, 404, 500.
      */
     get: function get(_ref6) {
       var token = _ref6.token,
           jwtToken = _ref6.jwtToken,
           headers = _ref6.headers,
-          internalAuthTokenProvider = _ref6.internalAuthTokenProvider;
+          optsAuth = _ref6.internalAuthTokenProvider;
 
       return client({
         url: "/datalogic/auth-code",
-        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     }
   };

package/lib/endpoints/btrzpay/oxxo.js

@@ -6,11 +6,31 @@ var _require = require("./../endpoints_helpers.js"),
 /**
  * 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]
@@ -20,64 +40,71 @@ var _require = require("./../endpoints_helpers.js"),
 
 function oxxoFactory(_ref) {
   var client = _ref.client,
-      _internalAuthTokenProvider = _ref.internalAuthTokenProvider;
+      internalAuthTokenProvider = _ref.internalAuthTokenProvider;
+
+  function authProvider(opts) {
+    return opts !== undefined && opts !== null ? opts : internalAuthTokenProvider;
+  }
 
   var 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: function get(_ref2) {
       var jwtToken = _ref2.jwtToken,
           headers = _ref2.headers,
-          internalAuthTokenProvider = _ref2.internalAuthTokenProvider;
+          optsAuth = _ref2.internalAuthTokenProvider;
 
       return client({
         url: "/oxxo/token",
-        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     }
   };
 
   var 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: function all(_ref3) {
       var jwtToken = _ref3.jwtToken,
           headers = _ref3.headers,
           oxxoToken = _ref3.oxxoToken,
           query = _ref3.query,
-          internalAuthTokenProvider = _ref3.internalAuthTokenProvider;
+          optsAuth = _ref3.internalAuthTokenProvider;
 
       return client({
         url: "/oxxo/" + oxxoToken + "/payments",
         params: query,
-        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: 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: function update(_ref4) {
       var jwtToken = _ref4.jwtToken,
@@ -86,37 +113,36 @@ function oxxoFactory(_ref) {
           query = _ref4.query,
           referenceNumber = _ref4.referenceNumber,
           data = _ref4.data,
-          internalAuthTokenProvider = _ref4.internalAuthTokenProvider;
+          optsAuth = _ref4.internalAuthTokenProvider;
 
       return client({
         url: "/oxxo/" + oxxoToken + "/payments/" + referenceNumber,
         method: "post",
         params: query,
         data: data,
-        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: 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: function reverse(_ref5) {
-      var authToken = _ref5.token,
-          jwtToken = _ref5.jwtToken,
+      var jwtToken = _ref5.jwtToken,
           headers = _ref5.headers,
           query = _ref5.query,
           referenceNumber = _ref5.referenceNumber,
           data = _ref5.data,
-          internalAuthTokenProvider = _ref5.internalAuthTokenProvider,
+          optsAuth = _ref5.internalAuthTokenProvider,
           oxxoToken = _ref5.oxxoToken;
 
       return client({
@@ -124,7 +150,7 @@ function oxxoFactory(_ref) {
         method: "post",
         params: query,
         data: data,
-        headers: authorizationHeaders({ token: authToken, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers })
+        headers: authorizationHeaders({ jwtToken: jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers: headers })
       });
     }
   };

package/lib/endpoints/btrzpay/prismaTerminals.js

@@ -4,10 +4,11 @@ var _require = require("../endpoints_helpers.js"),
     authorizationHeaders = _require.authorizationHeaders;
 
 /**
- * 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
  */
 
 /**
@@ -49,12 +50,13 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -77,11 +79,12 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -128,12 +131,13 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -156,11 +160,12 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -236,11 +241,12 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -262,11 +268,12 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -287,12 +294,13 @@ function prismaTerminalsFactory(_ref) {
     },
 
     /**
-     * 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>}
      */
@@ -320,11 +328,12 @@ function prismaTerminalsFactory(_ref) {
 
   var 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/lib/endpoints/btrzpay/referenced-payments.js

@@ -23,14 +23,14 @@ function referencedPaymentsFactory(_ref) {
       internalAuthTokenProvider = _ref.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(_ref2) {
     var token = _ref2.token,

package/lib/endpoints/btrzpay/square.js

@@ -4,7 +4,7 @@ var _require = require("./../endpoints_helpers.js"),
     authorizationHeaders = _require.authorizationHeaders;
 
 /**
- * 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]
@@ -17,14 +17,14 @@ function squareWebhooksFactory(_ref) {
       internalAuthTokenProvider = _ref.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(_ref2) {
     var token = _ref2.token,
@@ -58,12 +58,12 @@ function squareTerminalsFactory(_ref3) {
       internalAuthTokenProvider = _ref3.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(_ref4) {
     var token = _ref4.token,

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

@@ -6,7 +6,15 @@ var _require = require("./../endpoints_helpers.js"),
 /**
  * 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
  */
 
 /**
@@ -23,13 +31,13 @@ function stripeTerminalsFactory(_ref) {
       internalAuthTokenProvider = _ref.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(_ref2) {
     var token = _ref2.token,
@@ -47,29 +55,26 @@ function stripeTerminalsFactory(_ref) {
   }
 
   /**
-   * 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(_ref3) {
     var token = _ref3.token,
         jwtToken = _ref3.jwtToken,
         id = _ref3.id,
         stripePayment = _ref3.stripePayment,
-        _ref3$query = _ref3.query,
-        query = _ref3$query === undefined ? {} : _ref3$query,
         headers = _ref3.headers;
 
     return client({
       url: "/stripe-terminals/" + id + "/simulate",
       method: "post",
       headers: authorizationHeaders({ token: token, jwtToken: jwtToken, internalAuthTokenProvider: internalAuthTokenProvider, headers: headers }),
-      params: query,
       data: { stripePayment: stripePayment }
     });
   }