@payware/mcp-server 1.2.0 → 1.3.0

package/src/payment-institution/transactions/get-transaction-history.js

@@ -1,6 +1,7 @@
 import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { apiErrorResult } from '../../shared/api-errors.js';
 
 /**
  * Get transaction history via payware API (completed/expired transactions)
@@ -44,16 +45,7 @@ export async function getPITransactionHistory({
       timestamp: new Date().toISOString()
     };
   } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status,
-        code: error.response?.data?.code,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
+    return apiErrorResult(error);
   }
 }
 

package/src/payment-institution/transactions/get-transaction-status.js

@@ -1,6 +1,7 @@
 import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { apiErrorResult } from '../../shared/api-errors.js';
 
 /**
  * Get transaction status via payware API (active transactions)
@@ -44,16 +45,7 @@ export async function getPITransactionStatus({
       timestamp: new Date().toISOString()
     };
   } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status,
-        code: error.response?.data?.code,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
+    return apiErrorResult(error);
   }
 }
 
@@ -62,13 +54,14 @@ export async function getPITransactionStatus({
  */
 export const getPITransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
-  description: `Get the current status of an active payware transaction as a payment institution.
+  description: `Get the current status of an active payware transaction as a financial institution.
 
 **Use Cases:**
 - Check transaction status and details
 - Monitor transaction progress
 - Get participant information (payee/payer accounts, BICs)
 - Check remaining time to live
+- Fetch what to display to the payer for a product-originated transaction
 
 **Response includes:**
 - Transaction ID and type
@@ -77,6 +70,40 @@ export const getPITransactionStatusTool = {
 - Reason lines and creation timestamp
 - Remaining time to live
 - Current transaction state
+- \`product\` - payer-facing presentation, for product-originated transactions only (see below)
+
+🛍️ **The nested \`product\` object.** Since 2026-07-22 the presentation fields are grouped under
+\`product\` rather than sitting flat on the response - the old top-level \`imageUrl\` is gone.
+Discriminate a product-originated transaction by the **presence of the object**, not by probing
+individual fields. It carries: \`productId\`, \`type\`, \`name\`, \`shortDescription\`, \`longDescription\`,
+\`imageUrl\`, \`imageDigest\`, \`imageContentType\`, \`imageBytes\`, \`termsUrl\`, \`termsText\`,
+\`regularPrice\`, \`shippable\`, \`quickPay\`, \`shopName\`. Absent properties are omitted.
+
+Four rules a payer-facing app must follow:
+
+1. **Verify \`imageDigest\` before rendering.** It is the SHA-256 payware pinned for the image at
+   \`imageUrl\`. Fetch the image, check its bytes against this digest, and fall back to a neutral
+   placeholder on mismatch. Rendering an unverified image to a payer is how a compromised merchant
+   image host puts arbitrary content on a payment confirmation screen. \`imageContentType\` and
+   \`imageBytes\` are what payware observed on fetch - use them to reject a surprise.
+2. **\`amount\` and \`currency\` at the top level are authoritative** - they are what the payer pays.
+   The \`product\` object does not repeat them. \`regularPrice\` is the pre-discount list price and is
+   present **only when it is higher than \`amount\`**, i.e. when there is a genuine saving to show; it
+   is omitted otherwise, precisely so no misleading comparison can be displayed.
+3. **\`quickPay\` is advisory.** When true, the app may skip the product detail screen and go straight
+   to payment confirmation - but only if it still shows the payee name, amount and currency, and
+   still gives the payer access to the terms in full before they authorise.
+4. **A missing field is usually a plan boundary, not an error.** \`imageUrl\` and \`termsUrl\` are
+   Standard and above; \`termsText\` and the descriptions are universal.
+
+For a \`pr\`/\`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
+plan gating); for the resulting \`pw\` transaction they are the snapshot frozen at creation, so what
+you get always reflects what the payer could have been shown at scan time.
+
+💰 **Amounts follow the currency.** \`amount\`, \`fee\`, \`payerAmount\` and \`payeeAmount\` are decimal
+strings at the smallest unit their own currency can be paid in - not always two decimals. \`fee\` is
+**the value to echo back unchanged at finalize**; \`feeFixed\` and \`feeRate\` are informational, and
+recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
 
 **Note:** This endpoint only returns active transactions. Use \`payware_pi_get_transaction_history\` for completed/expired transactions.`,
   inputSchema: {

package/src/payment-institution/transactions/process-pi-transaction.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { apiErrorResult } from '../../shared/api-errors.js';
 
 /**
  * Process a transaction as a payment institution via payware API
@@ -102,16 +103,7 @@ export async function processPITransaction({
       timestamp: new Date().toISOString()
     };
   } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status,
-        code: error.response?.data?.code,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
+    return apiErrorResult(error);
   }
 }
 

package/src/payment-institution/transactions/simulate-pi-callback.js

@@ -30,10 +30,19 @@ export function generateMockPICallback(transactionId, callbackType = 'TRANSACTIO
     paymentMethod = null,
     status = 'CONFIRMED',
     statusMessage = null,
-    passbackParams = null
+    passbackParams = null,
+    // The fee breakdown. Present on BOTH payloads whenever the transaction has a fee configuration -
+    // FINALIZED gained them on 2026-08-21, having previously carried the total without the two
+    // numbers that produced it. Both are INFORMATIONAL: recomputing the fee from them and submitting
+    // that at finalize is rejected with ERR_FEE_MISMATCH. Echo `fee` back unchanged instead.
+    feeFixed = '0.1000',
+    feeRate = '0.0150',
+    // Pass fee: null to model the anomaly the server reports by OMITTING the property - a
+    // transaction with no recorded fee. Deliberately distinguishable from a genuine '0.00'.
+    fee: feeOverride = undefined
   } = options;
 
-  // Calculate fee like Java implementation: |payerAmount - amount| or |payeeAmount - amount|
+  // Calculate fee like the server: |payerAmount - amount| or |payeeAmount - amount|.
   const transactionAmount = parseFloat(amount);
   let fee = '0.60'; // Default fee
   if (payerAmount !== null) {
@@ -41,15 +50,27 @@ export function generateMockPICallback(transactionId, callbackType = 'TRANSACTIO
   } else if (payeeAmount !== null) {
     fee = Math.abs(parseFloat(payeeAmount) - transactionAmount).toFixed(2);
   }
+  if (feeOverride !== undefined) {
+    fee = feeOverride;
+  }
+
+  // The server's payloads are @JsonInclude(NON_NULL): a property with no value is ABSENT from the
+  // JSON rather than sent as null. Emitting "passbackParams": null here taught integrators to expect
+  // a shape the server never sends.
+  const feeFields = {
+    ...(fee !== null && fee !== undefined && { fee }),
+    ...(feeFixed !== null && feeFixed !== undefined && { feeFixed }),
+    ...(feeRate !== null && feeRate !== undefined && { feeRate })
+  };
 
   // Build payload based on callback type (matching Java implementation exactly)
   if (callbackType === 'TRANSACTION_PROCESSED') {
     return {
       callbackType,
       transactionId,
-      passbackParams,
+      ...(passbackParams !== null && passbackParams !== undefined && { passbackParams }),
       amount,
-      fee,
+      ...feeFields,
       currency,
       payeeBIC,
       payeeAccount,
@@ -65,19 +86,24 @@ export function generateMockPICallback(transactionId, callbackType = 'TRANSACTIO
       ...(paymentMethod && { paymentMethod })
     };
   } else {
-    // TRANSACTION_FINALIZED
+    // TRANSACTION_FINALIZED.
+    //
+    // transactionType and initiatedBy are deliberately NOT here: the server's finalized builder
+    // never sets them, so @JsonInclude(NON_NULL) drops them. An institution that needs either for a
+    // finalized transaction reads it from GET /transactions-history/{transactionId}.
     return {
       callbackType,
       transactionId,
-      passbackParams,
+      ...(passbackParams !== null && passbackParams !== undefined && { passbackParams }),
       amount,
-      fee,
+      ...feeFields,
       currency,
       status,
       ...(statusMessage && { statusMessage }),
       ...(paymentMethod && { paymentMethod }),
       created: Date.now() - 300000, // Created 5 minutes ago (milliseconds)
-      finalized: Date.now()
+      // Absent on EXPIRED: the expiry sweep transitions status in bulk and sets no finalized moment.
+      ...(status !== 'EXPIRED' && { finalized: Date.now() })
     };
   }
 }
@@ -152,6 +178,16 @@ export const simulatePICallbackTool = {
         description: "Fee amount charged by payment institution (e.g., '0.60')",
         default: "0.60"
       },
+      feeFixed: {
+        type: "string",
+        description: "Fixed fee component of the applicable fee configuration. Informational, for reconciliation - do not recompute the fee from it. Present on both callback types since 2026-08-21. Pass null to model a transaction with no fee configuration, where it is omitted.",
+        default: "0.1000"
+      },
+      feeRate: {
+        type: "string",
+        description: "Variable rate of the applicable fee configuration, e.g. '0.0150' = 1.5%. Informational, same as feeFixed.",
+        default: "0.0150"
+      },
       payeeBIC: {
         type: "string",
         description: "Payee's BIC code",
@@ -222,7 +258,9 @@ export const simulatePICallbackTool = {
       callbackUrl,
       amount = '57.00',
       currency = 'EUR',
-      fee = '0.60',
+      fee,
+      feeFixed = '0.1000',
+      feeRate = '0.0150',
       payeeBIC = 'SBBICID1',
       payeeAccount = 'M-1W-1account2',
       payeeFriendlyName = 'payware',
@@ -246,6 +284,8 @@ export const simulatePICallbackTool = {
       amount,
       currency,
       fee,
+      feeFixed,
+      feeRate,
       payeeBIC,
       payeeAccount,
       payeeFriendlyName,

package/src/payment-institution/transactions/soundbite-transaction.js

@@ -3,6 +3,7 @@ import FormData from 'form-data';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { readFileSync } from 'fs';
+import { apiErrorResult } from '../../shared/api-errors.js';
 
 /**
  * Get transaction information using Soundbite file via payware API
@@ -63,16 +64,7 @@ export async function getSoundbiteTransaction({
       timestamp: new Date().toISOString()
     };
   } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status,
-        code: error.response?.data?.code,
-        details: error.response?.data
-      },
-      timestamp: new Date().toISOString()
-    };
+    return apiErrorResult(error);
   }
 }
 

package/src/shared/api-errors.js

@@ -0,0 +1,188 @@
+/**
+ * One place that turns an axios failure from the payware API into something an assistant can act on.
+ *
+ * Every module here used to do the same thing inline:
+ *
+ *     throw new Error(`Failed to get products: ${error.response?.data?.message || error.message}`);
+ *
+ * which keeps the server's sentence and throws away the two things that decide what to do next: the
+ * HTTP status and the response headers. That is survivable for a 400 - the message names the bad
+ * field - and it is not survivable for the statuses that are reachable on EVERY endpoint from
+ * machinery no individual handler knows about:
+ *
+ *   - **429** is refused by `PartnerApiRateLimitFilter` before any handler runs, and carries a
+ *     `Retry-After` header. Flattened to a string, "Rate limit exceeded. Please slow down your
+ *     requests." reads like advice rather than like a number of seconds to wait, and the header -
+ *     the only part that says how long - is gone.
+ *   - **403** on an ISV call is nearly always the acting merchant's plan, not the ISV's own
+ *     permissions. Without that hint the obvious next move is to re-check credentials that were
+ *     never the problem.
+ *   - **409** and **503** both mean "the request was not applied", i.e. retryable, and a bare
+ *     message makes them indistinguishable from a 400, which is not.
+ *
+ * So this returns an Error whose message states the status, the payware error code, what it means,
+ * and whether retrying is correct.
+ */
+
+/** Statuses reachable on any endpoint, with what a caller should actually do about each. */
+const UNIVERSAL_STATUS_GUIDANCE = {
+  401: {
+    label: 'Unauthenticated',
+    guidance:
+      'The JWT was missing, malformed, expired, or signed with a key that does not match the ' +
+      'partnerId. Check that the private key in keys/ belongs to the environment being called - a ' +
+      'sandbox key against production authenticates as nobody. Not retryable as-is.'
+  },
+  403: {
+    label: 'Forbidden',
+    guidance:
+      'Authenticated, but not permitted. On an ISV on-behalf call this is usually the MERCHANT\'s ' +
+      'plan rather than the ISV\'s own permissions - the operating plan is the merchant\'s, and ' +
+      'Basic merchants are outside the transaction, product, shop and report surfaces. Other ' +
+      'causes: the shop is not in the ISV\'s assigned scope (ERR_SHOP_NOT_IN_SCOPE), the report is ' +
+      'not available to this plan or partner type (ERR_REPORT_NOT_AVAILABLE), or a KYC gate. Not ' +
+      'retryable without changing the plan, the scope, or the resource.'
+  },
+  409: {
+    label: 'Conflict',
+    guidance:
+      'The request was well formed and conflicts with the current state - most often ' +
+      'ERR_ALREADY_PROCESSED, which is the answer to submitting the same transaction twice. Treat ' +
+      'it as "already done" rather than as a failure: re-read the transaction before retrying, or ' +
+      'the retry will conflict again.'
+  },
+  429: {
+    label: 'Rate limited',
+    guidance:
+      'The per-partner rate limit was exceeded and the request was NOT processed - nothing was ' +
+      'created, updated or charged, so the identical request is safe to retry. Wait for the ' +
+      'Retry-After value below before retrying, and add jitter if more than one worker is running, ' +
+      'so that the retries do not re-synchronise into a second burst.'
+  },
+  503: {
+    label: 'Service unavailable',
+    guidance:
+      'A dependency payware needs was unavailable - typically no fee configuration for the ' +
+      'transaction currency (ERR_FEE_CONFIGURATION_UNAVAILABLE) or no exchange rate ' +
+      '(ERR_MISSING_EXCHANGE_RATE). The caller did nothing wrong and the request was not applied, ' +
+      'so retrying later is correct. If it persists, it is a payware-side configuration gap - ' +
+      'report it rather than retrying indefinitely.'
+  }
+};
+
+/**
+ * Whether retrying the identical request is safe and meaningful.
+ *
+ * Deliberately narrow. 429 and 503 are the two statuses that state the request was not applied;
+ * everything else either succeeded, conflicts, or needs the request changed first.
+ */
+export function isRetryable(status) {
+  return status === 429 || status === 503;
+}
+
+/**
+ * Seconds to wait before retrying, read from the response's Retry-After header.
+ *
+ * Returns null when the header is absent or is an HTTP-date rather than a delta-seconds value.
+ * payware sends delta-seconds, but a proxy in front of it may not, and guessing a date's meaning is
+ * worse than saying nothing.
+ */
+export function retryAfterSeconds(error) {
+  const raw = error?.response?.headers?.['retry-after'] ?? error?.response?.headers?.['Retry-After'];
+  if (raw === undefined || raw === null) return null;
+  const seconds = Number.parseInt(String(raw).trim(), 10);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+
+/**
+ * Build the Error to throw for a failed payware API call.
+ *
+ * @param {Error} error      the axios error
+ * @param {string} operation what was being attempted, e.g. 'get products' - phrased to follow "Failed to "
+ * @returns {Error} an Error carrying `status`, `errorCode`, `retryable` and `retryAfterSeconds`
+ *                  alongside a message that explains the status
+ */
+export function describeApiError(error, operation) {
+  const status = error?.response?.status;
+  const data = error?.response?.data;
+  const errorCode = data?.errorCode || data?.code;
+  const serverMessage = data?.message || error?.message;
+  const correlationId = data?.correlationId;
+
+  const parts = [`Failed to ${operation}`];
+  const known = UNIVERSAL_STATUS_GUIDANCE[status];
+  if (status) {
+    parts.push(`: HTTP ${status}${known ? ` (${known.label})` : ''}`);
+  } else {
+    parts.push(':');
+  }
+  if (errorCode) parts.push(` [${errorCode}]`);
+  if (serverMessage) parts.push(` ${serverMessage}`);
+
+  const detail = [];
+  if (known) detail.push(known.guidance);
+
+  const retryAfter = retryAfterSeconds(error);
+  if (retryAfter !== null) {
+    detail.push(`Retry-After: ${retryAfter} seconds.`);
+  } else if (status === 429) {
+    // The filter always sets it, so its absence means something sat between us and payware.
+    detail.push('No Retry-After header was returned; back off at least 60 seconds.');
+  }
+
+  // The single most useful thing to quote when reporting a problem to payware support, and it is
+  // dropped entirely by a message-only error.
+  if (correlationId) detail.push(`correlationId: ${correlationId} - quote this to payware support.`);
+
+  const message = parts.join('') + (detail.length ? `\n\n${detail.join('\n')}` : '');
+
+  const wrapped = new Error(message);
+  wrapped.status = status;
+  wrapped.errorCode = errorCode;
+  wrapped.correlationId = correlationId;
+  wrapped.retryable = isRetryable(status);
+  wrapped.retryAfterSeconds = retryAfter;
+  wrapped.cause = error;
+  return wrapped;
+}
+
+/**
+ * The `{ success: false, error: {...} }` shape the transaction and POI modules return instead of
+ * throwing, built from one place.
+ *
+ * **The bug this exists to stop repeating.** Those modules each built the shape inline and read the
+ * payware error code as `error.response?.data?.code`. payware does not send a `code` property. Its
+ * error body is `{ errorCode, message, correlationId }` - `ApiError.errorCode`, with no
+ * `@JsonProperty` renaming it - so `.code` was `undefined` on every payware error in every one of
+ * those modules. Nothing failed loudly: the message still came through, so the shape looked healthy
+ * while the machine-readable half of it was always empty. Anything branching on the code silently
+ * took the else branch forever - `create-transaction.js` had exactly that, a hash-mismatch help text
+ * gated on `data.code === 'ERR_INVALID_CONTENT_HASH'` that could never fire.
+ *
+ * `code` is still populated below, as an alias of `errorCode`, so that any caller still reading the
+ * old property keeps working - it just now has a value.
+ */
+export function apiErrorResult(error) {
+  const status = error?.response?.status;
+  const data = error?.response?.data;
+  const errorCode = data?.errorCode || data?.code;
+  const retryAfter = retryAfterSeconds(error);
+  const known = UNIVERSAL_STATUS_GUIDANCE[status];
+
+  return {
+    success: false,
+    error: {
+      message: data?.message || error?.message,
+      status,
+      errorCode,
+      // Alias, kept populated for backward compatibility - see the note above.
+      code: errorCode,
+      correlationId: data?.correlationId,
+      retryable: isRetryable(status),
+      ...(retryAfter !== null && { retryAfterSeconds: retryAfter }),
+      ...(known && { guidance: known.guidance }),
+      details: data
+    },
+    timestamp: new Date().toISOString()
+  };
+}

package/src/shared/auth-headers.js

@@ -0,0 +1,62 @@
+import { createJWTToken } from '../core/auth/jwt-token.js';
+import { createJWTForPartner } from '../core/auth/jwt-factory.js';
+
+/**
+ * Build the Authorization headers for a payware API call, for any partner role.
+ *
+ * Merchants and financial institutions sign with their own key. An ISV signs with its own key too,
+ * but adds the merchant it is acting for in the `aud` claim and that merchant's OAuth2 token in
+ * `sub` - which is what makes the call an on-behalf call rather than an ISV-for-itself call.
+ *
+ * **Note on duplication.** Four near-identical private copies of this function already exist, in
+ * `shared/products/products-api.js`, `shared/data/data-api.js`, `shared/deep-links/api.js` and
+ * `shared/logs/logs-api.js`. This is the shared one, used by everything added since. The four were
+ * deliberately left alone rather than swept into it: they are on live, working paths, they differ in
+ * small ways that look accidental but have not been proven so (deep-links defaults `requestBody` to
+ * `''` where the others pass `undefined`, and for a GET those are not always the same thing to a
+ * hash calculation), and consolidating them is a refactor of authentication with no test suite
+ * behind it. Do it as its own change, with the `''`-vs-`undefined` question answered first, not as a
+ * side effect of adding a tool.
+ *
+ * @param {string} partnerType   'merchant' | 'payment_institution' | 'isv'
+ * @param {Object} authParams    partnerId + privateKey, or isvPartnerId + privateKey +
+ *                               merchantPartnerId + oauth2Token; plus requestBody for writes
+ * @returns {Promise<Object>} headers including Authorization, Content-Type and Api-Version
+ */
+export async function createAuthHeaders(partnerType, authParams) {
+  const baseHeaders = {
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  let tokenData;
+
+  switch (partnerType) {
+    case 'merchant':
+    case 'payment_institution':
+      tokenData = createJWTToken(
+        authParams.partnerId,
+        authParams.privateKey,
+        authParams.requestBody
+      );
+      break;
+
+    case 'isv':
+      tokenData = await createJWTForPartner({
+        partnerId: authParams.isvPartnerId,
+        privateKey: authParams.privateKey,
+        merchantId: authParams.merchantPartnerId,
+        oauth2Token: authParams.oauth2Token,
+        requestBody: authParams.requestBody
+      });
+      break;
+
+    default:
+      throw new Error(`Unknown partner type: ${partnerType}`);
+  }
+
+  return {
+    ...baseHeaders,
+    'Authorization': `Bearer ${tokenData.token}`
+  };
+}

package/src/shared/data/data-api.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { describeApiError } from '../api-errors.js';
 
 /**
  * Available report types from the Data API documentation
@@ -147,7 +148,7 @@ export async function generateReport({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to generate report: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'generate report');
   }
 }
 
@@ -181,7 +182,7 @@ export async function getReportStatus({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get report status: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get report status');
   }
 }
 
@@ -222,7 +223,7 @@ export async function exportReport({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to export report: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'export report');
   }
 }
 
@@ -256,7 +257,7 @@ export async function getExportStatus({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get export status: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get export status');
   }
 }
 
@@ -295,7 +296,7 @@ export async function downloadExport({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to download export: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'download export');
   }
 }
 
@@ -331,7 +332,7 @@ export async function cancelReport({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to cancel report: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'cancel report');
   }
 }
 
@@ -367,7 +368,7 @@ export async function cancelExport({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to cancel export: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'cancel export');
   }
 }
 
@@ -396,7 +397,7 @@ export async function listReports({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to list reports: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'list reports');
   }
 }
 
@@ -430,7 +431,7 @@ export async function getReportRequests({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get report requests: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get report requests');
   }
 }
 
@@ -464,6 +465,6 @@ export async function getExportList({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get export list: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get export list');
   }
 }

package/src/shared/deep-links/api.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getProductionUrl } from '../../config/env.js';
+import { describeApiError } from '../api-errors.js';
 
 /**
  * Create authentication headers based on partner type
@@ -84,7 +85,7 @@ export async function getTransactionDeepLink({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get transaction deep link: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get transaction deep link');
   }
 }
 
@@ -127,7 +128,7 @@ export async function getProductDeepLink({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to get product deep link: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'get product deep link');
   }
 }
 
@@ -166,7 +167,7 @@ export async function deleteTransactionDeepLink({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to delete transaction deep link: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'delete transaction deep link');
   }
 }
 
@@ -209,6 +210,6 @@ export async function deleteProductDeepLink({
       }
     };
   } catch (error) {
-    throw new Error(`Failed to delete product deep link: ${error.response?.data?.message || error.message}`);
+    throw describeApiError(error, 'delete product deep link');
   }
 }