docs: sync from backend cbc32dc — template delivery rails

03 - API Reference/Marketplace API.md

@@ -5,7 +5,7 @@ tags: [api, marketplace, reference]
 
 # Marketplace API
 
-> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))
+> **Last updated:** 2026-05-31 — request-template delivery mode and payment rail validation updated.
 
 All marketplace endpoints live under `/api/marketplace/*`. The router is composed of several files mounted from `app.ts`:
 
@@ -345,13 +345,23 @@ A [[RequestTemplate]] is a re-usable "shop product" a seller can publish. Buyers
   quantity?: number;                   // 1-10000
   budget?: { min?: number; max?: number; currency: "USD" | "EUR" | "IRR" | "USDT" | "USDC" };
   urgency?: "low" | "medium" | "high" | "urgent";
-  deliveryInfo?: { deliveryType: "physical" | "online"; email?: string };
+  deliveryInfo?: {
+    deliveryType: "physical" | "online"; // seller-selected; buyer cannot override at checkout
+    notes?: string;
+    email?: string;                      // optional legacy field; empty string is accepted
+  };
+  paymentConfig?: {
+    useShopDefault: boolean;             // false = template override, true = shop defaults
+    allowedChains: number[];             // at least one positive chain id when paymentConfig is sent
+    allowedTokens: string[];             // at least one non-empty token symbol when paymentConfig is sent
+  };
   maxUsage?: number | null;            // 0/null = unlimited
   expiresAt?: string | null;           // ISO date
   images?: string[];                   // URLs from [[File API]]
 }
 ```
 **Response 201:** `{ data: { template } }` with a generated `shareableLink`.
+**Validation:** If `paymentConfig` is present, both `allowedChains` and `allowedTokens` must be non-empty. The UI now defaults new templates to explicit template rails, so a seller must choose at least one chain and one token before publishing.
 
 ### GET /api/marketplace/request-templates
 
@@ -399,7 +409,7 @@ A [[RequestTemplate]] is a re-usable "shop product" a seller can publish. Buyers
 
 ### POST /api/marketplace/request-templates/batch-convert
 
-**Description:** Convert several templates at once (cart checkout).
+**Description:** Convert several templates at once (cart checkout). The seller's template delivery mode is preserved; buyer-supplied checkout details are only overlaid where that mode requires them.
 **Auth required:** Bearer JWT (buyer)
 **Request body:**
 ```ts
@@ -410,8 +420,25 @@ A [[RequestTemplate]] is a re-usable "shop product" a seller can publish. Buyers
     sellerId: string;        // MongoId
   }>;
   status?: "pending" | "pending_payment" | "active";
+  paymentConfirmed?: boolean;
+  paymentData?: Record<string, unknown>;
+  deliveryInfo?: {
+    email?: string;          // copied to generated online requests
+    billing?: {
+      name?: string;
+      phoneNumber?: string;
+      address?: string;
+      city?: string;
+      state?: string;
+      country?: string;
+      zipCode?: string;
+      addressType?: string;
+      fullAddress?: string;  // copied to generated physical requests
+    };
+  };
 }
 ```
+**Delivery mapping:** `online` templates use `deliveryInfo.email`; `physical` templates use `deliveryInfo.billing` to fill `deliveryInfo.address` and `deliveryInfo.deliveryAddress` on the generated [[PurchaseRequest]].
 
 ### POST /api/marketplace/request-templates/complete-payment
 

03 - API Reference/Payment API.md

@@ -5,7 +5,7 @@ tags: [api, payment, reference, request-network, escrow]
 
 # Payment API
 
-> **Last updated:** 2026-05-31 — Postgres integration promotion, oracle quote persistence, AMN scanner rail-switch fix, capped webhook confirmation persistence, and partial gasless permit endpoints.
+> **Last updated:** 2026-05-31 — Postgres integration promotion, oracle quote persistence, AMN scanner rail-switch fix, capped webhook confirmation persistence, seller/template payment rail options, and partial gasless permit endpoints.
 
 The payment surface is split across provider-neutral payment routers, Request Network checkout/webhook routes, derived-destination custody routes, and admin safety routes:
 
@@ -23,7 +23,7 @@ The payment surface is split across provider-neutral payment routers, Request Ne
 Core model: [[Payment]]. Coordination logic to avoid race conditions when multiple sources update the same payment is in `paymentCoordinator.ts`.
 
 > [!warning] Persistence status
-> Payment APIs still create/read/update Mongo `Payment` documents on backend `2.6.82`. The Postgres branch adds schemas, repos, migrations, and optional quote persistence, but it is not a full payment-domain cutover. `/api/payment/request-network/intents` can write `payment_quotes` only when `ORACLE_QUOTING_ENABLED=true`; the payment record itself remains Mongo-backed unless future service wiring changes that boundary.
+> Payment APIs still create/read/update Mongo `Payment` documents on backend `2.6.83`. The Postgres branch adds schemas, repos, migrations, and optional quote persistence, but it is not a full payment-domain cutover. `/api/payment/request-network/intents` can write `payment_quotes` only when `ORACLE_QUOTING_ENABLED=true`; the payment record itself remains Mongo-backed unless future service wiring changes that boundary.
 
 ## Configuration / health
 
@@ -175,6 +175,30 @@ Core model: [[Payment]]. Coordination logic to avoid race conditions when multip
 ```
 **Response 200:** `{ success: true, data: { paymentId, paymentUrl, providerPaymentId, raw, ... } }`
 
+### GET /api/payment/request-network/options
+
+**Description:** Resolves the chain/token rails a buyer may use for a seller or template checkout. Precedence is template override (`RequestTemplate.paymentConfig.useShopDefault === false`), then store defaults (`ShopSettings.paymentConfig`), then the global supported default.
+**Auth required:** Bearer JWT
+**Query params:** `sellerId?`, `templateId?`
+**Response 200:**
+```ts
+{
+  success: true;
+  data: {
+    allowedChains: number[];
+    allowedTokens: string[];
+    source: "item" | "store" | "default";
+    chains: Array<{
+      chainId: number;
+      name: string;
+      shortName: string;
+      tokens: Array<{ symbol: string; address: string; decimals: number }>;
+    }>;
+  };
+}
+```
+**Frontend use:** Template checkout calls this with both `sellerId` and the real `templateId` before creating payment intents, then defaults to BSC/USDT when allowed or the first returned rail otherwise.
+
 ### POST /api/payment/request-network/intents
 
 **Description:** Richer buyer intent endpoint used by the provider-selection checkout. It can dispatch either to `request.network` or `amn.scanner`, validates the seller's allowed chain/token choices, and re-points an existing pending intent when the buyer changes rail. When `ORACLE_QUOTING_ENABLED=true`, the backend ignores client-supplied `amount`, loads the seller offer price, computes a depeg-protected quote, and uses the computed settlement amount for the provider intent.