[juanisierra]

Summary

Brings back the optional EXPO_PUBLIC_MERCHANT_DEV_API_URL (removed in #646). When set, /merchants/* routes use it; everything else keeps using EXPO_PUBLIC_API_URL. When unset (or empty), both fall back to EXPO_PUBLIC_API_URL, so production behaves exactly as today.

Route	Base URL
POST /merchant/payment, GET /merchant/payment/{id}/status, POST /payments/{id}/cancel	EXPO_PUBLIC_API_URL
GET /merchants/payments (payment list), POST /merchants/payments/{id}/receipt	EXPO_PUBLIC_MERCHANT_DEV_API_URL → falls back to EXPO_PUBLIC_API_URL

Why

#646 dropped the override as part of the email-receipt work ("Single API base URL"), but staging doesn't serve both route groups from one host yet. Since then the preview Payments list has returned 401 invalid_api_key (Maestro doesn't open Payments, so CI didn't catch it).

Confirmed with the Pay backend team: payments live in core (api.pay.walletconnect.org) while /merchants/* is served by the staging merchant service (staging.api.pay.walletconnect.org), which syncs against core prod. Aligning the staging gateway is being raised with core; until then the POS needs two base URLs on staging.

Verified end to end with staging merchant mrch_stg_L4Z43pPrSuyJfQwpqOpxg: create (201) and status (200) on api.pay.walletconnect.org/v1, the new payment listed first on staging.api.pay.walletconnect.org/v1/merchants/payments (200), then cancelled (200).

Changes

• Web proxies: getMerchantApiBaseUrl() in api/_utils.ts, used by /api/transactions and /api/send-receipt.
• Native: merchantApiClient in services/client.ts, used by getTransactions and sendReceipt.
• Sentry trace propagation includes the merchant URL when set.
• .env.example and AGENTS.md document the variable.

Config after merging

Vercel Preview (pos-demo):

EXPO_PUBLIC_API_URL=https://api.pay.walletconnect.org/v1
EXPO_PUBLIC_MERCHANT_DEV_API_URL=https://staging.api.pay.walletconnect.org/v1
EXPO_PUBLIC_DEFAULT_MERCHANT_ID=mrch_stg_L4Z43pPrSuyJfQwpqOpxg
EXPO_PUBLIC_DEFAULT_CUSTOMER_API_KEY=<its key>

Vercel Production / POS_ENV_FILE: leave EXPO_PUBLIC_MERCHANT_DEV_API_URL unset. POS_ENV_FILE_INTERNAL (TestFlight/Firebase internal): same values as Preview if internal builds should use the staging merchant.

Once staging serves both route groups from one host, this variable can be removed again (in a PR verified against staging).

Tests

• New __tests__/api/base-urls.test.ts: merchant URL used when set, fallback when unset, 500 when neither is configured (fails without this change).
• Transaction and receipt service tests updated to merchantApiClient.
• npm test: 39 suites / 355 tests passing; lint and type checks clean for changed files.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CmgutsXzUS2j26BNUevhrE

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
pos-demo	Ready	Preview	Oct 23, 2026 11:53am UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
react-native-appkit	Ignored	Preview	Oct 23, 2026 11:53am UTC
react-native-walletkit	Ignored	Preview	Oct 23, 2026 11:53am UTC

[claude]

Claude finished @juanisierra's task in 3m 0s —— View job

---

Code Review

• Gather context
• Read changed files
• Run breaking changes subagent — no breaking changes
• Run data classification subagent — no data classification issues
• Compile findings

---

Found 1 issue(s)

Issue 1: Misleading error message in getMerchantApiBaseUrl

ID: utils-merchant-error-msg-a3f1
File: dapps/pos-app/api/_utils.ts:50
Severity: LOW
Category: code_quality

Context:

• Pattern: getMerchantApiBaseUrl returns a 500 with "API_BASE_URL is not configured" when both EXPO_PUBLIC_MERCHANT_DEV_API_URL and EXPO_PUBLIC_API_URL are unset
• Risk: The error message is identical to getApiBaseUrl's 500 message, making it impossible to tell from logs which function triggered it and which env vars are missing
• Impact: Ops/debugging confusion when the merchant URL path fails silently on a misconfigured deployment — the operator would look for EXPO_PUBLIC_API_URL alone when the fix might also require EXPO_PUBLIC_MERCHANT_DEV_API_URL
• Trigger: Deploy with both env vars unset while the merchant feature is in use

Recommendation:

// api/_utils.ts:49-51
res.status(500).json({
  message: "API_BASE_URL is not configured (set EXPO_PUBLIC_API_URL or EXPO_PUBLIC_MERCHANT_DEV_API_URL)",
});

Fix this →