btrz-api-client 8.33.0 → 8.34.0

package/src/endpoints/btrzpay/datalogic.js

@@ -5,104 +5,139 @@ const {
 /**
  * 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]
  * @returns {{ payments: Object, referenceNumber: Object, authCode: Object }}
  */
-function datalogicFactory({client}) {
+function datalogicFactory({client, internalAuthTokenProvider}) {
+  function authProvider(opts) {
+    return opts !== undefined && opts !== null ? opts : internalAuthTokenProvider;
+  }
+
   const 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({token, jwtToken, headers, query, internalAuthTokenProvider}) {
+    all({token, jwtToken, headers, query, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: "/datalogic/payments",
         params: query,
-        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider: authProvider(optsAuth), 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({token, jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider}) {
+    update({token, jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: `/datalogic/payments/${referenceNumber}`,
         method: "post",
         params: query,
         data,
-        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider: authProvider(optsAuth), 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({token, jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider}) {
+    reverse({token, jwtToken, headers, query, referenceNumber, data, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: `/datalogic/reverse/${referenceNumber}`,
         method: "post",
         params: query,
         data,
-        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     }
   };
 
   const 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({token, jwtToken, headers, internalAuthTokenProvider}) {
+    get({token, jwtToken, headers, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: "/datalogic/reference-number",
-        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     }
   };
 
   const 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({token, jwtToken, headers, internalAuthTokenProvider}) {
+    get({token, jwtToken, headers, internalAuthTokenProvider: optsAuth}) {
       return client({
         url: "/datalogic/auth-code",
-        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider, headers})
+        headers: authorizationHeaders({token, jwtToken, internalAuthTokenProvider: authProvider(optsAuth), headers})
       });
     }
   };

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;