docs: sync from backend cbc32dc — template delivery rails

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.