feat(pos-app): migrate transactions API to unified Pay API

Migrate from old Merchant API (`/merchants/{id}/payments` with separate
`MERCHANT_PORTAL_API_KEY`) to unified Pay API (`/v1/merchants/payments`
with shared `getApiHeaders()`). Update response types from flat
snake_case to nested camelCase DTOs. Replace CAIP-19 token parsing with
server-provided display values. Remove `utils/tokens.ts` and merchant
API env vars.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ignaciosantise

dapps/pos-app/.env.example

@@ -5,5 +5,3 @@ EXPO_PUBLIC_API_URL=""
 EXPO_PUBLIC_GATEWAY_URL=""
 EXPO_PUBLIC_DEFAULT_MERCHANT_ID=""
 EXPO_PUBLIC_DEFAULT_CUSTOMER_API_KEY=""
-EXPO_PUBLIC_MERCHANT_API_URL=""
-EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY=""

dapps/pos-app/AGENTS.md

@@ -79,6 +79,7 @@ The app uses **Zustand** for state management with two main stores:
    - Biometric authentication settings
    - Printer connection status
    - Transaction filter preference (for Activity screen)
+   - Date range filter preference (for Activity screen)
 
 2. **`useLogsStore`** (`store/useLogsStore.ts`)
    - Debug logs for troubleshooting
@@ -220,20 +221,19 @@ All Payment API requests include:
 
 ### Transactions Service (`services/transactions.ts`)
 
-> **Note:** The Merchants API currently has its own auth layer separate from the Payment API. Both share the same base URL (`EXPO_PUBLIC_API_URL`), but merchant endpoints authenticate via `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY` (sent as `x-api-key` header) rather than the partner API key used by payment endpoints. This will be unified in the future.
-
 **`getTransactions(options)`**
 
 - Fetches merchant transaction history
-- Endpoint: `GET /merchants/{merchant_id}/payments`
-- Uses the shared base URL (`EXPO_PUBLIC_API_URL`) but authenticates with `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY`
-- Supports filtering by status, date range, pagination
-- Returns array of `PaymentRecord` objects
+- Endpoint: `GET /v1/merchants/payments`
+- Uses `getApiHeaders()` for authentication (same as payment endpoints)
+- Supports filtering by status, date range (`startTs`/`endTs`), pagination (`cursor`/`limit`)
+- Returns `TransactionsResponse` with nested camelCase DTOs (`PaymentRecord`, `AmountWithDisplay`, `BuyerInfo`, `TransactionInfo`, `SettlementInfo`)
 
 ### Server-Side Proxy (`api/transactions.ts`)
 
 - Vercel serverless function that proxies transaction requests (web only)
-- Client only sends `x-merchant-id` header; API key is handled server-side via `EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY`
+- Uses shared `extractCredentials()` and `getApiHeaders()` from `api/_utils.ts`
+- Client sends `x-api-key` and `x-merchant-id` headers; proxy forwards with full auth headers
 - Avoids CORS issues by making requests server-side
 
 ### useTransactions Hook (`services/hooks.ts`)
@@ -242,7 +242,8 @@ All Payment API requests include:
 import { useTransactions } from "@/services/hooks";
 
 const { data, isLoading, isError, refetch } = useTransactions({
-  filter: "all", // "all" | "completed" | "pending" | "failed"
+  filter: "all", // "all" | "pending" | "completed" | "failed" | "expired" | "cancelled"
+  dateRangeFilter: "today", // "all_time" | "today" | "7_days" | "this_week" | "this_month"
   enabled: true,
 });
 ```
@@ -264,8 +265,6 @@ EXPO_PUBLIC_API_URL=""                 # Payment API base URL
 EXPO_PUBLIC_GATEWAY_URL=""             # WalletConnect gateway URL
 EXPO_PUBLIC_DEFAULT_MERCHANT_ID=""     # Default merchant ID (optional)
 EXPO_PUBLIC_DEFAULT_CUSTOMER_API_KEY="" # Default customer API key (optional)
-EXPO_PUBLIC_MERCHANT_API_URL=""        # Merchant Portal API base URL
-EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY="" # Merchant Portal API key (for Activity screen)
 ```
 
 Copy `.env.example` to `.env` and fill in values.

dapps/pos-app/api/transactions.ts

@@ -1,8 +1,5 @@
 import type { VercelRequest, VercelResponse } from "@vercel/node";
-
-const API_BASE_URL = process.env.EXPO_PUBLIC_API_URL;
-// TODO: Once Merchants API unifies auth with Payment API, forward client credentials instead
-const MERCHANT_PORTAL_API_KEY = process.env.EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY;
+import { extractCredentials, getApiBaseUrl, getApiHeaders } from "./_utils";
 
 /**
  * Vercel Serverless Function to proxy transaction list requests
@@ -17,30 +14,16 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
   }
 
   try {
-    // Extract merchant ID from request headers
-    const merchantId = req.headers["x-merchant-id"] as string;
-
-    if (!merchantId) {
-      return res.status(400).json({
-        message: "Missing required header: x-merchant-id",
-      });
-    }
-
-    if (!API_BASE_URL) {
-      return res.status(500).json({
-        message: "API_BASE_URL is not configured",
-      });
-    }
+    const credentials = extractCredentials(req, res);
+    if (!credentials) return;
 
-    if (!MERCHANT_PORTAL_API_KEY) {
-      return res.status(500).json({
-        message: "MERCHANT_PORTAL_API_KEY is not configured",
-      });
-    }
+    const apiBaseUrl = getApiBaseUrl(res);
+    if (!apiBaseUrl) return;
 
-    // Build query string from request query params
+    // Forward query params as-is (already camelCase from client)
     const params = new URLSearchParams();
-    const { status, sort_by, sort_dir, limit, cursor } = req.query;
+    const { status, sortBy, sortDir, limit, cursor, startTs, endTs } =
+      req.query;
 
     // Handle status (can be array for multiple status filters)
     if (status) {
@@ -50,29 +33,32 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
         params.append("status", status);
       }
     }
-    if (sort_by && typeof sort_by === "string") {
-      params.append("sort_by", sort_by);
+    if (sortBy && typeof sortBy === "string") {
+      params.append("sortBy", sortBy);
     }
-    if (sort_dir && typeof sort_dir === "string") {
-      params.append("sort_dir", sort_dir);
+    if (sortDir && typeof sortDir === "string") {
+      params.append("sortDir", sortDir);
     }
     if (limit && typeof limit === "string") {
       params.append("limit", limit);
     }
     if (cursor && typeof cursor === "string") {
       params.append("cursor", cursor);
     }
+    if (startTs && typeof startTs === "string") {
+      params.append("startTs", startTs);
+    }
+    if (endTs && typeof endTs === "string") {
+      params.append("endTs", endTs);
+    }
 
     const queryString = params.toString();
-    const normalizedBaseUrl = API_BASE_URL.replace(/\/+$/, "");
-    const endpoint = `/merchants/${encodeURIComponent(merchantId)}/payments${queryString ? `?${queryString}` : ""}`;
+    const normalizedBaseUrl = apiBaseUrl.replace(/\/+$/, "");
+    const endpoint = `/v1/merchants/payments${queryString ? `?${queryString}` : ""}`;
 
     const response = await fetch(`${normalizedBaseUrl}${endpoint}`, {
       method: "GET",
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": MERCHANT_PORTAL_API_KEY,
-      },
+      headers: getApiHeaders(credentials.apiKey, credentials.merchantId),
     });
 
     const data = await response.json();

dapps/pos-app/app/activity.tsx

@@ -156,10 +156,7 @@ export default function ActivityScreen() {
     [handleTransactionPress],
   );
 
-  const keyExtractor = useCallback(
-    (item: PaymentRecord) => item.payment_id,
-    [],
-  );
+  const keyExtractor = useCallback((item: PaymentRecord) => item.paymentId, []);
 
   const renderEmptyComponent = useCallback(() => {
     if (isLoading) {

dapps/pos-app/app/payment-success.tsx

@@ -212,10 +212,7 @@ export default function PaymentSuccessScreen() {
             onPress={handleNewPayment}
           >
             <ThemedText
-              style={[
-                styles.buttonText,
-                { color: DarkTheme["text-primary"] },
-              ]}
+              style={[styles.buttonText, { color: DarkTheme["text-primary"] }]}
             >
               New payment
             </ThemedText>

dapps/pos-app/components/transaction-card.tsx

@@ -33,15 +33,18 @@ function TransactionCardBase({
     >
       <View style={styles.leftContent}>
         <ThemedText fontSize={16} lineHeight={20} color="text-primary">
-          {formatFiatAmount(payment.fiat_amount, payment.fiat_currency)}
+          {formatFiatAmount(
+            payment.fiatAmount?.value,
+            payment.fiatAmount?.unit,
+          )}
         </ThemedText>
         <ThemedText
           fontSize={14}
           lineHeight={18}
           color="text-secondary"
           style={styles.date}
         >
-          {formatShortDate(payment.created_at)}
+          {formatShortDate(payment.createdAt)}
         </ThemedText>
       </View>
       <StatusBadge status={payment.status} />

dapps/pos-app/components/transaction-detail-modal.tsx

@@ -2,7 +2,6 @@ import { BorderRadius, Spacing } from "@/constants/spacing";
 import { useTheme } from "@/hooks/use-theme-color";
 import { formatFiatAmount } from "@/utils/currency";
 import { formatDateTime } from "@/utils/misc";
-import { formatCryptoReceived, getTokenSymbol } from "@/utils/tokens";
 import { PaymentRecord } from "@/utils/types";
 import { memo, useEffect } from "react";
 import {
@@ -46,23 +45,6 @@ function truncateHash(hash?: string): string {
   return `${hash.slice(0, 4)}...${hash.slice(-4)}`;
 }
 
-/**
- * Get the token icon based on CAIP-19 identifier
- * Returns the icon source or null if not USDC/USDT
- */
-function getTokenIcon(tokenCaip19?: string): number | null {
-  const symbol = getTokenSymbol(tokenCaip19);
-  if (!symbol) return null;
-
-  if (symbol === "USDC") {
-    return require("@/assets/images/tokens/usdc.png");
-  }
-  if (symbol === "USDT") {
-    return require("@/assets/images/tokens/usdt.png");
-  }
-  return null;
-}
-
 interface DetailRowProps {
   label: string;
   value?: string;
@@ -142,14 +124,15 @@ function TransactionDetailModalBase({
   if (!payment) return null;
 
   const handleCopyPaymentId = async () => {
-    if (!payment?.payment_id) return;
-    await Clipboard.setStringAsync(payment.payment_id);
+    if (!payment?.paymentId) return;
+    await Clipboard.setStringAsync(payment.paymentId);
     showSuccessToast("Payment ID copied to clipboard");
   };
 
+  const txHash = payment.transaction?.hash;
   const handleCopyHash = async () => {
-    if (!payment?.tx_hash) return;
-    await Clipboard.setStringAsync(payment.tx_hash);
+    if (!txHash) return;
+    await Clipboard.setStringAsync(txHash);
     showSuccessToast("Transaction hash copied to clipboard");
   };
 
@@ -190,7 +173,7 @@ function TransactionDetailModalBase({
               <View style={styles.details}>
                 <DetailRow
                   label="Date"
-                  value={formatDateTime(payment.created_at)}
+                  value={formatDateTime(payment.createdAt)}
                 />
 
                 <DetailRow label="Status">
@@ -200,45 +183,43 @@ function TransactionDetailModalBase({
                 <DetailRow
                   label="Amount"
                   value={formatFiatAmount(
-                    payment.fiat_amount,
-                    payment.fiat_currency,
+                    payment.fiatAmount?.value,
+                    payment.fiatAmount?.unit,
                   )}
                 />
 
-                {payment.token_amount && payment.token_caip19 && (
+                {payment.tokenAmount?.value && (
                   <DetailRow label="Crypto received">
                     <View style={styles.cryptoValue}>
                       <ThemedText
                         fontSize={16}
                         lineHeight={18}
                         color="text-primary"
                       >
-                        {formatCryptoReceived(
-                          payment.token_caip19,
-                          payment.token_amount,
-                        ) ?? payment.token_amount}
+                        {payment.tokenAmount.display?.formatted ??
+                          payment.tokenAmount.value}
                       </ThemedText>
-                      {(() => {
-                        const icon = getTokenIcon(payment.token_caip19);
-                        return icon ? (
-                          <Image style={styles.tokenIcon} source={icon} />
-                        ) : null;
-                      })()}
+                      {payment.tokenAmount.display?.iconUrl && (
+                        <Image
+                          style={styles.tokenIcon}
+                          source={{ uri: payment.tokenAmount.display.iconUrl }}
+                        />
+                      )}
                     </View>
                   </DetailRow>
                 )}
 
                 <DetailRow
                   label="Payment ID"
-                  value={payment.payment_id}
+                  value={payment.paymentId}
                   onPress={handleCopyPaymentId}
                   underline
                 />
 
-                {payment.tx_hash && (
+                {txHash && (
                   <DetailRow
                     label="Hash ID"
-                    value={truncateHash(payment.tx_hash)}
+                    value={truncateHash(txHash)}
                     onPress={handleCopyHash}
                     underline
                   />

dapps/pos-app/services/hooks.ts

@@ -238,7 +238,7 @@ export function useTransactions(options: UseTransactionsOptions = {}) {
       });
     },
     initialPageParam: undefined as string | undefined,
-    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
     enabled,
     staleTime: 5 * 60 * 1000, // 5 minutes
     gcTime: 30 * 60 * 1000, // 30 minutes (formerly cacheTime)

dapps/pos-app/services/transactions.ts

@@ -1,9 +1,5 @@
-import { useSettingsStore } from "@/store/useSettingsStore";
 import { TransactionsResponse } from "@/utils/types";
-// TODO: Once Merchants API unifies auth with Payment API, switch to getApiHeaders()
-import { apiClient } from "./client";
-
-const MERCHANT_PORTAL_API_KEY = process.env.EXPO_PUBLIC_MERCHANT_PORTAL_API_KEY;
+import { apiClient, getApiHeaders } from "./client";
 
 export interface GetTransactionsOptions {
   status?: string | string[];
@@ -23,15 +19,7 @@ export interface GetTransactionsOptions {
 export async function getTransactions(
   options: GetTransactionsOptions = {},
 ): Promise<TransactionsResponse> {
-  const merchantId = useSettingsStore.getState().merchantId;
-
-  if (!merchantId) {
-    throw new Error("Merchant ID is not configured");
-  }
-
-  if (!MERCHANT_PORTAL_API_KEY) {
-    throw new Error("Merchant Portal API key is not configured");
-  }
+  const headers = await getApiHeaders();
 
   // Build query string from options
   const params = new URLSearchParams();
@@ -45,11 +33,11 @@ export async function getTransactions(
   }
 
   if (options.sortBy) {
-    params.append("sort_by", options.sortBy);
+    params.append("sortBy", options.sortBy);
   }
 
   if (options.sortDir) {
-    params.append("sort_dir", options.sortDir);
+    params.append("sortDir", options.sortDir);
   }
 
   if (options.limit) {
@@ -69,11 +57,9 @@ export async function getTransactions(
   }
 
   const queryString = params.toString();
-  const endpoint = `/merchants/${merchantId}/payments${queryString ? `?${queryString}` : ""}`;
+  const endpoint = `/v1/merchants/payments${queryString ? `?${queryString}` : ""}`;
 
   return apiClient.get<TransactionsResponse>(endpoint, {
-    headers: {
-      "x-api-key": MERCHANT_PORTAL_API_KEY,
-    },
+    headers,
   });
 }