@agenzo/merchant-cli 0.8.17 → 0.9.1

package/dist/index.js

@@ -1197,6 +1197,22 @@ var ridePayOrderSchema = {
       default: false,
       description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call ride via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side. Ignored for monthly_settlement and on the payment-token-id direct-charge path."
     },
+    authenticate: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless. Ignored on the EVO preauth path and for UnionPay/Visa."
+    },
+    "return-url": {
+      type: "string",
+      required: false,
+      description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL."
+    },
+    "authorized-charge-no": {
+      type: "string",
+      required: false,
+      description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token). Relaxes the exactly-one-credential rule (continuation, not a fresh charge)."
+    },
     "idempotency-key": {
       type: "string",
       required: true,
@@ -1662,6 +1678,22 @@ var hotelPayOrderSchema = {
       default: false,
       description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side. Ignored for monthly_settlement and on the payment-token-id direct-charge path."
     },
+    authenticate: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless. Ignored on the EVO preauth path and for UnionPay/Visa."
+    },
+    "return-url": {
+      type: "string",
+      required: false,
+      description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL."
+    },
+    "authorized-charge-no": {
+      type: "string",
+      required: false,
+      description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token), then triggers upstream payOrder on success (pay_per_call only)."
+    },
     "idempotency-key": {
       type: "string",
       required: true,
@@ -2231,6 +2263,97 @@ var unifiedOrdersGetSchema = {
     INTERNAL_ERROR: "The order's provider detail lookup is temporarily unavailable. Retry once after a short delay."
   }
 };
+var ordersPayBatchSchema = {
+  cli: CLI_NAME,
+  noun: ORDERS_NOUN,
+  verb: "pay-batch",
+  description: "Settle a batch of orders (may mix ride/hotel/flight \u2014 hho_/ffo_/rio_) in ONE aggregate payment via a single payment credential. Physical landing point of the logical write tool orders__aggregate__pay-batch, invoked by the trip-aggregate pay-orders write verb through UniversalGateway (executed only after the single confirmation gate; never exposed to the LLM). Amounts are NOT passed here \u2014 the platform sums each order's locked authoritative price. Provide the aggregate total via one rail: --payment-token-id (\u8F68A: network-token minted for the aggregate total, external_transaction_id bound to this payment_group \u2014 one UnionPay/Visa passkey) OR --payment-method-id (\u8F68B: EVO bound card \u2014 one 3DS challenge); both may be omitted (monthly_settlement / platform default card). On EVO cardholder authentication the response is AUTHENTICATION_REQUIRED with a three_ds_url + merchant_trans_id; finish it out-of-band, then an idempotent replay settles. On success the batch becomes settled / partially_settled (upstream-confirmation-failed orders are refunded). Supports --watch to poll until a terminal batch status.",
+  flags: {
+    "order-ids": {
+      type: "string",
+      required: true,
+      description: `Ordered order ids to settle together \u2014 comma-separated (hho_1,ffo_2,rio_3) or a JSON array (["hho_1","ffo_2"]). May mix hho_/ffo_/rio_ domains. Amounts come from each order's locked authoritative price (NOT passed here).`
+    },
+    "payment-token-id": {
+      type: "string",
+      required: false,
+      description: "[\u8F68A] Network-token id (UnionPay/Visa) minted for the aggregate total with external_transaction_id bound to this payment_group (direct-charge main path). Mutually exclusive with --payment-method-id; both may be omitted for monthly_settlement / platform default."
+    },
+    "payment-method-id": {
+      type: "string",
+      required: false,
+      description: "[\u8F68B] EVO bound-card id to settle the aggregate total via one 3DS challenge (explicit/fallback rail). Mutually exclusive with --payment-token-id."
+    },
+    "evo-explicit": {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "[\u8F68B \u786C\u95E8\u69DB] Explicit opt-in to settle via the EVO bound-card rail. Set true ONLY when the user explicitly chose EVO; forwarded to the body as evo_explicit=true. Omit on the payment-token-id direct-charge path."
+    },
+    "payment-group-id": {
+      type: "string",
+      required: false,
+      description: "Optional caller-pre-generated payment group id; omit to let the platform generate one. The whole batch is associated with this group for cross-provider reconciliation."
+    },
+    member: MEMBER_FLAG_SCHEMA,
+    "idempotency-key": {
+      type: "string",
+      required: true,
+      description: "Unique key forwarded verbatim as the Idempotency-Key header; never auto-generated. The SAME key + the SAME ordered order_ids replays as the same batch (dedup re-check, no double charge); any change to order_ids yields a new batch.",
+      constraints: "1-128 chars [A-Za-z0-9_-]"
+    },
+    watch: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Poll until a terminal batch status (settled / partially_settled / failed) or timeout, emitting one NDJSON line per poll. Non-terminal states (authorizing/capturing, AUTHENTICATION_REQUIRED) keep polling \u2014 after the user finishes 3DS out-of-band, the next idempotent replay settles."
+    },
+    // watch 默认值与 pay-batch.ts 的 DEFAULT_PAY_BATCH_WATCH_* 常量一致；此处内联字面量
+    // 以避免 verb-schema.ts ↔ pay-batch.ts 循环依赖（pay-batch.ts 反向依赖本模块的 schema）。
+    "watch-interval": {
+      type: "int",
+      required: false,
+      default: 5,
+      description: "Seconds between polls when --watch is set"
+    },
+    "watch-timeout": {
+      type: "int",
+      required: false,
+      default: 300,
+      description: "Max seconds to poll before giving up"
+    }
+  },
+  response: {
+    payment_group_id: { type: "string", description: "The payment group this batch settled under (echoes --payment-group-id when supplied, else server-generated)." },
+    status: { type: "string", description: "settled | partially_settled | failed | AUTHENTICATION_REQUIRED (3DS challenge body)." },
+    currency: { type: "string", description: "ISO 4217 currency of the aggregate settlement (all orders share one currency)." },
+    total_amount: { type: "float", description: "Aggregate total in DECIMAL units = sum of each order's authoritative price (computed by the platform, NOT sent by the caller)." },
+    orders: {
+      type: "array",
+      description: "Per-order final result after upstream confirmation.",
+      items: {
+        order_id: { type: "string", description: "hho_/ffo_/rio_ order id." },
+        status: { type: "string", description: "confirmed | refunded | failed." },
+        amount: { type: "float", description: "That order's authoritative amount." },
+        refunded_amount: { type: "float", description: "Amount refunded when upstream confirmation failed for this order." }
+      }
+    },
+    three_ds_url: { type: "string", description: "[AUTHENTICATION_REQUIRED only] EVO 3DS challenge URL \u2014 complete out-of-band, then replay to settle." },
+    merchant_trans_id: { type: "string", description: "[AUTHENTICATION_REQUIRED only] merchant trans id of the batch preauth." },
+    amount: { type: "float", description: "[AUTHENTICATION_REQUIRED only] challenge amount = aggregate total." }
+  },
+  example: {
+    command: "agenzo-merchant-cli orders pay-batch --order-ids hho_01K...,ffo_01K...,rio_01K... --payment-token-id ntk_01J2ABC --idempotency-key trip-pay-1",
+    output_summary: "Settles all listed orders in one charge (banks/EVO see one transaction). Returns {payment_group_id, status, total_amount, currency, orders[]}. Use --watch to poll until settled / partially_settled / failed; upstream-confirmation-failed orders are refunded."
+  },
+  error_recovery: {
+    PARAM_INVALID: "Fix --order-ids (a non-empty comma-separated list or JSON array of order ids) and ensure --idempotency-key is present, then retry.",
+    ORDER_NOT_PAYABLE: "One of the order_ids is not in AWAITING_PAYMENT (the error names the specific order_id). Remove/replace it and retry with a NEW idempotency-key.",
+    CURRENCY_MISMATCH: "The batch mixes currencies \u2014 orders in one pay-batch must share a single currency. Split by currency and settle each group separately.",
+    TOKEN_ORDER_MISMATCH: "The token external_transaction_id is not bound to this payment_group. Mint a token for the aggregate total bound to THIS payment_group_id and retry; no funds moved.",
+    AUTHENTICATION_REQUIRED: "EVO requires cardholder 3DS: open three_ds_url, finish authentication, then replay pay-batch with the SAME idempotency-key (or use --watch to poll automatically)."
+  }
+};
 function flightSchema(verb, description, flags, response, example, extra = {}) {
   return { cli: CLI_NAME, noun: FLIGHT_NOUN, verb, description, flags, response, example, ...extra };
 }
@@ -2272,30 +2395,38 @@ var flightListNationalitiesSchema = flightSchema(
 );
 var flightSearchSchema = flightSchema(
   "search",
-  "Search flights (one-way/round-trip/multi-city). journeys always carries all legs; journey-id accumulates progress and only the final search returns a real priceKey (product_token).",
+  "Search flights (one-way/round-trip/multi-city). journeys always carries all legs; for round-trip/multi-city relay the CHOSEN candidate's next_journey_ids into --journey-id until is_final_leg is true \u2014 only then do offers carry a real priceKey (product_token).",
   {
     "trip-type": { type: "int", required: true, description: "1=one-way, 2=round-trip, 3=multi-city." },
-    journeys: { type: "json", required: true, description: "JSON array of {date, origin, destination, origin_type?, destination_type?}. origin/destination are IATA 3-letter codes; *_type 1=city, 2=airport." },
+    journeys: { type: "json", required: true, description: "JSON array of {date, origin, destination, origin_type?, destination_type?}. origin/destination are IATA 3-letter codes; *_type 1=city, 2=airport. Carries ALL legs on every call, including relay calls." },
     "cabin-class": { type: "string", required: false, default: "economy", description: "economy | premium_economy | business | first." },
     "adult-num": { type: "int", required: false, default: 1, description: "Adults (1-9)." },
     "child-num": { type: "int", required: false, default: 0, description: "Children (0-9)." },
     "infant-num": { type: "int", required: false, default: 0, description: "Infants (0-9)." },
     airline: { type: "string", required: false, description: "Airline 2-letter code filter." },
     "transfer-number": { type: "int", required: false, default: 0, description: "0=any,1=direct,2=1 stop,3=2 stops." },
-    "journey-id": { type: "json", required: false, description: "JSON array of already-selected journey ids (relay for round-trip/multi-city)." }
+    "journey-id": { type: "json", required: false, description: "Relay key: copy offers[].next_journey_ids VERBATIM from the candidate the user chose in the previous search. Omit on the first search. Do not build it from the top-level journey_ids, and never send more ids than there are legs (rejected)." }
   },
   {
-    offers: { type: "array", description: "Offers; each has product_token (when price_key_ready), total_sale_price, currency." },
+    offers: { type: "array", description: "Candidates for the current leg. Each has next_journey_ids (relay key), journey_id, segment_ids, paired_segment_ids, total_sale_price (WHOLE-TRIP total), currency, cabin_class, baggage/refund/change_rules, and product_token when price_key_ready." },
     price_key_ready: { type: "bool", description: "True only when all legs are selected (final search)." },
-    journey_ids: { type: "array", description: "journeyId values to relay into the next search." }
+    current_leg: { type: "int", description: "Which leg this result is choosing (1-based)." },
+    total_legs: { type: "int", description: "Total legs in the trip." },
+    is_final_leg: { type: "bool", description: "True when these offers can be bookable. False means relay another round with the chosen candidate's next_journey_ids." },
+    journey_ids: { type: "array", description: "DEPRECATED for relay: flattened across all candidates, so it cannot tell you which id belongs to which. Relay offers[].next_journey_ids instead." }
   },
-  { command: `agenzo-merchant-cli flight-flink search --trip-type 1 --journeys '[{"date":"2026-08-01","origin":"PEK","destination":"SHA"}]'`, output_summary: "Returns offers[]; use a product_token where price_key_ready is true, then verify." }
+  { command: `agenzo-merchant-cli flight-flink search --trip-type 1 --journeys '[{"date":"2026-08-01","origin":"PEK","destination":"SHA"}]'`, output_summary: "Returns offers[]; use a product_token where price_key_ready is true, then verify. Round-trip: the first search has is_final_leg=false and no product_token \u2014 relay the chosen candidate's next_journey_ids to get bookable offers." }
 );
 var flightMoreOffersSchema = flightSchema(
   "more-offers",
   "More fare offers for a priceKey (carried by product_token).",
   { "product-token": { type: "string", required: true, description: "Opaque token from search." } },
-  { offers: { type: "array", description: "Additional fare candidates." } },
+  {
+    offers: { type: "array", description: "Additional fare candidates for the same flight (same shape as search offers[]); all are bookable." },
+    current_leg: { type: "int", description: "Always 1 \u2014 alternative fares for one chosen flight, not a relay round." },
+    total_legs: { type: "int", description: "Always 1." },
+    is_final_leg: { type: "bool", description: "Always true." }
+  },
   { command: "agenzo-merchant-cli flight-flink more-offers --product-token pt_...", output_summary: "Additional fare offers." }
 );
 var flightVerifySchema = flightSchema(
@@ -2306,7 +2437,8 @@ var flightVerifySchema = flightSchema(
     product_token: { type: "string", description: "Authoritative token to pass to create-order." },
     total_price: { type: "int", description: "Verified total price (integer)." },
     currency: { type: "string", description: "Currency code." },
-    price_changed: { type: "bool", description: "True if the price changed since search; re-confirm with the user." }
+    price_changed: { type: "bool", description: "True if the price changed since search; re-confirm with the user." },
+    journeys: { type: "array", description: "The COMPLETE itinerary being priced \u2014 every leg, not just the last one relayed. Use it to show the full trip on a confirmation screen." }
   },
   { command: "agenzo-merchant-cli flight-flink verify --product-token pt_...", output_summary: "Returns the authoritative product_token + price_changed." }
 );
@@ -2349,7 +2481,10 @@ var flightPayOrderSchema = flightSchema(
     "order-no": { type: "string", required: true, description: "Our order reference from create-order." },
     "payment-method-id": { type: "string", required: false, description: "Optional bound-card id to charge (pay_per_call only; omit to use the default card)." },
     "payment-token-id": { type: "string", required: false, description: "Optional network-token id; settles via direct charge instead of EVO preauth." },
-    "authorized-merchant-trans-id": { type: "string", required: false, description: "Resume a 3DS challenge with an already-authorised preauth trans id." },
+    "authorized-merchant-trans-id": { type: "string", required: false, description: "Resume an EVO-card 3DS challenge with an already-authorised preauth trans id." },
+    authenticate: { type: "bool", required: false, default: false, description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless." },
+    "return-url": { type: "string", required: false, description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL." },
+    "authorized-charge-no": { type: "string", required: false, description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token), then triggers ticketing on success." },
     "evo-explicit": { type: "bool", required: false, default: false, description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side." },
     "idempotency-key": { type: "string", required: true, description: "Forwarded verbatim as the Idempotency-Key header." }
   },
@@ -3012,6 +3147,17 @@ function formatPayOrder(data) {
     lines.push(["Amount", `${data.price.amount} ${data.price.currency}`]);
     if (data.price.quote_id) lines.push(["Quote ID", String(data.price.quote_id)]);
   }
+  if (data.charge_no) lines.push(["Charge no", String(data.charge_no)]);
+  if (data.three_ds_url) lines.push(["3DS URL", String(data.three_ds_url)]);
+  if (String(data.status) === "AUTHENTICATION_REQUIRED") {
+    return [
+      Formatter.keyValue(lines),
+      Formatter.status(
+        "warning",
+        `Order ${orderRef} needs cardholder 3DS \u2014 open the 3DS URL, then resume pay-order with --authorized-charge-no ${data.charge_no ?? ""}.`
+      )
+    ].join("\n\n");
+  }
   return [
     Formatter.keyValue(lines),
     Formatter.status(
@@ -3029,7 +3175,16 @@ function registerRidePayOrderCommand(parent, deps) {
     "Bound-card id to charge via EVO preauth+capture (fallback path). Exactly one of --payment-token-id / --payment-method-id is required."
   ).option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token). When set, the exactly-one-credential rule is relaxed (this is a continuation, not a fresh charge)."
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call ride via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -3045,7 +3200,10 @@ function registerRidePayOrderCommand(parent, deps) {
     const orderId = need4(opts.orderId, "order-id");
     const paymentTokenId = opts.paymentTokenId;
     const paymentMethodId = opts.paymentMethodId;
-    assertExactlyOneCredential(paymentTokenId, paymentMethodId);
+    const authorizedChargeNo = opts.authorizedChargeNo;
+    if (authorizedChargeNo === void 0) {
+      assertExactlyOneCredential(paymentTokenId, paymentMethodId);
+    }
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
       type: "password"
@@ -3056,6 +3214,9 @@ function registerRidePayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (authorizedChargeNo !== void 0) body.authorized_charge_no = authorizedChargeNo;
     if (opts.evoExplicit) body.evo_explicit = true;
     if (!isYes) {
       const confirmed = await confirm3({
@@ -4002,15 +4163,201 @@ function registerOrdersGetCommand(parent, deps) {
   });
 }
 
-// src/hotel-redaug/search.ts
+// src/orders/pay-batch.ts
+import { confirm as confirm6 } from "@inquirer/prompts";
+var DEFAULT_PAY_BATCH_WATCH_INTERVAL_SECONDS = 5;
+var DEFAULT_PAY_BATCH_WATCH_TIMEOUT_SECONDS = 300;
+var PAY_BATCH_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "settled",
+  "partially_settled",
+  "failed"
+]);
+function parseOrderIds(raw) {
+  const INVALID = '--order-ids must be a comma-separated list OR a JSON array of order ids (e.g. "hho_1,ffo_2,rio_3" or ["hho_1","ffo_2"]).';
+  const trimmed = raw.trim();
+  let ids;
+  if (trimmed.startsWith("[")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      throw new CliError("PARAM_INVALID", INVALID);
+    }
+    if (!Array.isArray(parsed)) {
+      throw new CliError("PARAM_INVALID", INVALID);
+    }
+    if (!parsed.every((el) => typeof el === "string")) {
+      throw new CliError("PARAM_INVALID", INVALID);
+    }
+    ids = parsed.map((s) => s.trim());
+  } else {
+    ids = trimmed.split(",").map((s) => s.trim());
+  }
+  ids = ids.filter((s) => s.length > 0);
+  if (ids.length === 0) {
+    throw new CliError("PARAM_INVALID", INVALID);
+  }
+  return ids;
+}
+function formatPayBatch(data) {
+  const lines = [
+    ["Payment group", String(data.payment_group_id ?? "-")],
+    ["Status", String(data.status ?? "-")]
+  ];
+  if (data.total_amount != null && data.currency) {
+    lines.push(["Total", `${data.total_amount} ${data.currency}`]);
+  }
+  if (data.status === "AUTHENTICATION_REQUIRED") {
+    if (data.three_ds_url) lines.push(["3DS URL", String(data.three_ds_url)]);
+    if (data.merchant_trans_id) lines.push(["Merchant trans ID", String(data.merchant_trans_id)]);
+    if (data.amount != null && data.currency) {
+      lines.push(["Challenge amount", `${data.amount} ${data.currency}`]);
+    }
+  }
+  const out = [Formatter.keyValue(lines)];
+  const perOrder = data.per_order ?? [];
+  if (perOrder.length > 0) {
+    const headers = ["Order ID", "Domain", "Status", "Amount", "Refunded"];
+    const rows = perOrder.map((o) => [
+      String(o.order_id ?? "-"),
+      String(o.domain ?? "-"),
+      String(o.status ?? "-"),
+      String(o.amount ?? "-"),
+      String(o.refunded_amount ?? "-")
+    ]);
+    out.push("", Formatter.table(headers, rows));
+  }
+  return out.join("\n");
+}
+function isBatchTerminal(record) {
+  const status = record.status;
+  return typeof status === "string" && PAY_BATCH_TERMINAL_STATUSES.has(status);
+}
+function registerOrdersPayBatchCommand(parent, deps) {
+  const cmd = parent.command("pay-batch").description(
+    "Settle a batch of orders (may mix ride/hotel/flight) in one aggregate payment via a single payment credential"
+  ).option("--api-key <key>", "API Key for authentication (X-Api-Key)").option(
+    "--order-ids <ids>",
+    "Ordered order ids to settle together \u2014 comma-separated (hho_1,ffo_2,rio_3) or a JSON array. May mix hho_/ffo_/rio_ domains. Amounts come from each order's locked authoritative price (not passed here)."
+  ).option(
+    "--payment-token-id <id>",
+    "[\u8F68 A] Network-token id minted for the aggregate total and bound to this payment_group (unionpay/visa charge path)"
+  ).option(
+    "--payment-method-id <id>",
+    "[\u8F68 B] EVO bound-card id to settle the aggregate total (one 3DS challenge)"
+  ).option(
+    "--evo-explicit",
+    "[\u8F68 B \u786C\u95E8\u69DB] Explicit opt-in to settle via the EVO bound-card rail. Set ONLY when the user explicitly chose EVO; forwarded to the body as evo_explicit=true."
+  ).option(
+    "--payment-group-id <id>",
+    "Optional caller-pre-generated payment group id; omit to let the platform generate one"
+  ).option("--member <id>", MEMBER_OPTION_DESCRIPTION).option(
+    "--idempotency-key <key>",
+    "Idempotency key forwarded verbatim as the Idempotency-Key header"
+  ).option("--watch", "Poll until a terminal batch status or timeout (NDJSON output)", false).option(
+    "--watch-interval <seconds>",
+    "Seconds between polls when --watch is set",
+    String(DEFAULT_PAY_BATCH_WATCH_INTERVAL_SECONDS)
+  ).option(
+    "--watch-timeout <seconds>",
+    "Max seconds to poll before giving up",
+    String(DEFAULT_PAY_BATCH_WATCH_TIMEOUT_SECONDS)
+  );
+  attachSchemaHelp(cmd, ordersPayBatchSchema);
+  cmd.action(async () => {
+    const opts = cmd.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const isYes = Boolean(opts.yes);
+    const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
+      message: "API Key:",
+      type: "password"
+    });
+    const orderIds = parseOrderIds(need9(opts.orderIds, "order-ids"));
+    const idempotencyKey = await resolveIdempotencyKey(opts.idempotencyKey, {
+      yes: isYes,
+      commandPath: "orders pay-batch"
+    });
+    const watchEnabled = Boolean(opts.watch);
+    const watchInterval = resolveSeconds(opts.watchInterval, DEFAULT_PAY_BATCH_WATCH_INTERVAL_SECONDS);
+    const watchTimeout = resolveSeconds(opts.watchTimeout, DEFAULT_PAY_BATCH_WATCH_TIMEOUT_SECONDS);
+    const body = { order_ids: orderIds };
+    if (opts.paymentTokenId !== void 0) body.payment_token_id = opts.paymentTokenId;
+    if (opts.paymentMethodId !== void 0) body.payment_method_id = opts.paymentMethodId;
+    if (opts.evoExplicit) body.evo_explicit = true;
+    if (opts.paymentGroupId !== void 0) body.payment_group_id = opts.paymentGroupId;
+    const member = memberIdOf(opts);
+    if (member !== void 0) body.member_id = member;
+    if (!isYes) {
+      const confirmed = await confirm6({
+        message: `Settle ${orderIds.length} order(s) in one aggregate payment? This moves money \u2014 a single charge covers the authoritative total of all listed orders (banks/EVO see one transaction).`,
+        default: false
+      });
+      if (!confirmed) {
+        throw new CliError("CLIENT_ABORTED", "Aggregate payment aborted by user.");
+      }
+    }
+    const path = "/orders/pay-batch";
+    const headers = { "Idempotency-Key": idempotencyKey };
+    const auth = { type: "api-key", key: apiKey };
+    if (!watchEnabled) {
+      const spinner = format === "json" ? null : createSpinner("Settling order batch...");
+      const result = await deps.apiClient.post(path, auth, body, headers);
+      spinner?.stop();
+      if (!result.success) {
+        throw CliError.fromApi(result, { auth: "api-key" });
+      }
+      const data = result.data;
+      const configManager = new ConfigManager();
+      const commandResult = {
+        data,
+        text: () => formatPayBatch(data)
+      };
+      await renderWithContext(commandResult, { format }, configManager);
+    } else {
+      const deadline = Date.now() + watchTimeout * 1e3;
+      let lastRecord = null;
+      for (; ; ) {
+        const result = await deps.apiClient.post(path, auth, body, headers);
+        if (result.success) {
+          const data = result.data;
+          lastRecord = data;
+          ndjsonWriteLine(data);
+          if (isBatchTerminal(data)) {
+            return;
+          }
+        } else {
+          throw CliError.fromApi(result, { auth: "api-key" });
+        }
+        if (Date.now() + watchInterval * 1e3 >= deadline) {
+          const timeoutLine = {
+            watch_status: "timeout",
+            message: `Polling stopped after ${watchTimeout}s without reaching a terminal batch status.`,
+            last_status: lastRecord
+          };
+          ndjsonWriteLine(timeoutLine);
+          return;
+        }
+        await realSleep(watchInterval * 1e3);
+      }
+    }
+  });
+}
 function need9(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
+
+// src/hotel-redaug/search.ts
+function need10(value, flag) {
+  if (value === void 0) {
+    throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
+  }
+  return value;
+}
 function num5(value, flag) {
-  const n = Number(need9(value, flag));
+  const n = Number(need10(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -4032,7 +4379,7 @@ function positiveInt3(value, flag) {
 }
 var YMD_RE = /^\d{4}-\d{2}-\d{2}$/;
 function stayDate(value, flag) {
-  const raw = need9(value, flag);
+  const raw = need10(value, flag);
   if (!YMD_RE.test(raw)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a YYYY-MM-DD date.`);
   }
@@ -4104,7 +4451,7 @@ function registerHotelSearchCommand(parent, deps) {
     const pageSize = positiveInt3(opts.pageSize, "page-size");
     const body = {};
     if (hasDestination) {
-      body.destination_id = need9(opts.destinationId, "destination-id");
+      body.destination_id = need10(opts.destinationId, "destination-id");
     } else {
       body.lat = coord(opts.lat, "lat", -90, 90);
       body.lng = coord(opts.lng, "lng", -180, 180);
@@ -4147,14 +4494,14 @@ function registerHotelSearchCommand(parent, deps) {
 }
 
 // src/hotel-redaug/quote.ts
-function need10(value, flag) {
+function need11(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
 function num6(value, flag) {
-  const n = Number(need10(value, flag));
+  const n = Number(need11(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -4162,7 +4509,7 @@ function num6(value, flag) {
 }
 var YMD_RE2 = /^\d{4}-\d{2}-\d{2}$/;
 function stayDate2(value, flag) {
-  const raw = need10(value, flag);
+  const raw = need11(value, flag);
   if (!YMD_RE2.test(raw)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a YYYY-MM-DD date.`);
   }
@@ -4202,7 +4549,7 @@ function registerHotelQuoteCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const hotelId = need10(opts.hotelId, "hotel-id");
+    const hotelId = need11(opts.hotelId, "hotel-id");
     const checkIn = stayDate2(opts.checkIn, "check-in");
     const checkOut = stayDate2(opts.checkOut, "check-out");
     if (!(checkOut > checkIn)) {
@@ -4236,7 +4583,7 @@ function registerHotelQuoteCommand(parent, deps) {
 }
 
 // src/hotel-redaug/create-order.ts
-import { confirm as confirm6 } from "@inquirer/prompts";
+import { confirm as confirm7 } from "@inquirer/prompts";
 function parsePriceItems(raw) {
   const INVALID = "--price-items must be a JSON array of {sale_date (string), sale_price (number), breakfast_num (number)}.";
   let parsed;
@@ -4294,14 +4641,14 @@ function parseCancellation(raw) {
   }
   return parsed;
 }
-function need11(value, flag) {
+function need12(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
 function num7(value, flag) {
-  const n = Number(need11(value, flag));
+  const n = Number(need12(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -4309,7 +4656,7 @@ function num7(value, flag) {
 }
 var YMD_RE3 = /^\d{4}-\d{2}-\d{2}$/;
 function stayDate3(value, flag) {
-  const raw = need11(value, flag);
+  const raw = need12(value, flag);
   if (!YMD_RE3.test(raw)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a YYYY-MM-DD date.`);
   }
@@ -4378,18 +4725,18 @@ function registerHotelCreateOrderCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const productToken = need11(opts.productToken, "product-token");
+    const productToken = need12(opts.productToken, "product-token");
     const totalAmount = num7(opts.totalAmount, "total-amount");
-    const currency = need11(opts.currency, "currency");
-    const priceItems = parsePriceItems(need11(opts.priceItems, "price-items"));
+    const currency = need12(opts.currency, "currency");
+    const priceItems = parsePriceItems(need12(opts.priceItems, "price-items"));
     const checkIn = stayDate3(opts.checkIn, "check-in");
     const checkOut = stayDate3(opts.checkOut, "check-out");
     if (!(checkOut > checkIn)) {
       throw new CliError("PARAM_INVALID", "--check-out must be strictly after --check-in.");
     }
-    const guestName = need11(opts.guestName, "guest-name");
-    const contactName = need11(opts.contactName, "contact-name");
-    const contactPhone = need11(opts.contactPhone, "contact-phone");
+    const guestName = need12(opts.guestName, "guest-name");
+    const contactName = need12(opts.contactName, "contact-name");
+    const contactPhone = need12(opts.contactPhone, "contact-phone");
     const body = {
       product_token: productToken,
       total_amount: totalAmount,
@@ -4423,7 +4770,7 @@ function registerHotelCreateOrderCommand(parent, deps) {
     if (member !== void 0) body.member_id = member;
     if (!isYes) {
       const chargeNote = opts.paymentTokenId !== void 0 ? "Payment has already been captured via UPI Agent Pay; this only locks the room." : "This locks the rate but does NOT charge anything yet.";
-      const confirmed = await confirm6({
+      const confirmed = await confirm7({
         message: `Create this hotel order for ${totalAmount} ${currency} (check-in ${checkIn}, check-out ${checkOut})? ${chargeNote}`,
         default: false
       });
@@ -4457,7 +4804,7 @@ function registerHotelCreateOrderCommand(parent, deps) {
 }
 
 // src/hotel-redaug/pay-order.ts
-import { confirm as confirm7 } from "@inquirer/prompts";
+import { confirm as confirm8 } from "@inquirer/prompts";
 
 // src/hotel-redaug/watch.ts
 var DEFAULT_ORDER_WATCH_INTERVAL_SECONDS = 5;
@@ -4587,11 +4934,14 @@ function formatPayOrder2(data) {
   ];
   if (data.settlement_path) lines.push(["Settlement path", String(data.settlement_path)]);
   if (data.pay_status) lines.push(["Pay status", String(data.pay_status)]);
+  if (data.status) lines.push(["Status", String(data.status)]);
   if (data.total_amount != null && data.currency) {
     lines.push(["Amount", `${data.total_amount} ${data.currency}`]);
   }
   if (data.billing_entry_id) lines.push(["Billing entry", String(data.billing_entry_id)]);
   if (data.merchant_trans_id) lines.push(["Merchant trans ID", String(data.merchant_trans_id)]);
+  if (data.charge_no) lines.push(["Charge no", String(data.charge_no)]);
+  if (data.three_ds_url) lines.push(["3DS URL", String(data.three_ds_url)]);
   return Formatter.keyValue(lines);
 }
 function isPaymentTerminal(record) {
@@ -4601,7 +4951,16 @@ function isPaymentTerminal(record) {
 function registerHotelPayOrderCommand(parent, deps) {
   const cmd = parent.command("pay-order").description("Settle an existing hotel order (path decided by billing_mode: monthly_settlement or pay_per_call)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-id <id>", "Order ID to pay (from create-order response)").option("--payment-method-id <id>", "Optional bound-card id to charge (pay_per_call / EVO preauth)").option("--payment-token-id <id>", "Optional network-token id (unionpay/visa charge path)").option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token)"
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -4643,9 +5002,14 @@ function registerHotelPayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (opts.authorizedChargeNo !== void 0) {
+      body.authorized_charge_no = opts.authorizedChargeNo;
+    }
     if (opts.evoExplicit) body.evo_explicit = true;
     if (!isYes) {
-      const confirmed = await confirm7({
+      const confirmed = await confirm8({
         message: `Settle hotel order ${orderId}? This moves money via the order's configured billing mode (monthly_settlement or pay_per_call).`,
         default: false
       });
@@ -4723,7 +5087,7 @@ function registerHotelPayOrderCommand(parent, deps) {
 }
 
 // src/hotel-redaug/get.ts
-function need12(value, flag) {
+function need13(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -4787,7 +5151,7 @@ function registerHotelGetCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const orderId = need12(opts.orderId, "order-id");
+    const orderId = need13(opts.orderId, "order-id");
     if (opts.watch) {
       await watchOrderStatus(deps.apiClient, apiKey, orderId, {
         intervalSeconds: resolveSeconds(
@@ -4821,7 +5185,7 @@ function registerHotelGetCommand(parent, deps) {
 }
 
 // src/hotel-redaug/cancel.ts
-function need13(value, flag) {
+function need14(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -4874,8 +5238,8 @@ function registerHotelCancelCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const orderId = need13(opts.orderId, "order-id");
-    const fcOrderCode = need13(opts.fcOrderCode, "fc-order-code");
+    const orderId = need14(opts.orderId, "order-id");
+    const fcOrderCode = need14(opts.fcOrderCode, "fc-order-code");
     const body = { fc_order_code: fcOrderCode };
     if (opts.reason !== void 0) body.reason = opts.reason;
     const idempotencyKey = await resolveIdempotencyKey(opts.idempotencyKey, {
@@ -4904,15 +5268,15 @@ function registerHotelCancelCommand(parent, deps) {
 }
 
 // src/hotel-redaug/checkout.ts
-import { confirm as confirm8 } from "@inquirer/prompts";
-function need14(value, flag) {
+import { confirm as confirm9 } from "@inquirer/prompts";
+function need15(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
 function num8(value, flag) {
-  const n = Number(need14(value, flag));
+  const n = Number(need15(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -4978,10 +5342,10 @@ function registerHotelCheckoutCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const orderId = need14(opts.orderId, "order-id");
-    const fcOrderCode = need14(opts.fcOrderCode, "fc-order-code");
-    const reason = need14(opts.reason, "reason");
-    const checkoutRooms = parseCheckoutRooms(need14(opts.checkoutRooms, "checkout-rooms"));
+    const orderId = need15(opts.orderId, "order-id");
+    const fcOrderCode = need15(opts.fcOrderCode, "fc-order-code");
+    const reason = need15(opts.reason, "reason");
+    const checkoutRooms = parseCheckoutRooms(need15(opts.checkoutRooms, "checkout-rooms"));
     const refundType = num8(opts.refundType, "refund-type");
     const body = {
       fc_order_code: fcOrderCode,
@@ -4990,7 +5354,7 @@ function registerHotelCheckoutCommand(parent, deps) {
       checkout_rooms: checkoutRooms
     };
     if (!isYes) {
-      const confirmed = await confirm8({
+      const confirmed = await confirm9({
         message: `Request check-out / out-of-policy cancellation for order ${orderId} (${checkoutRooms.length} room(s))? The property must approve and charges may apply.`,
         default: false
       });
@@ -5024,7 +5388,7 @@ function registerHotelCheckoutCommand(parent, deps) {
 }
 
 // src/hotel-redaug/get-checkout.ts
-function need15(value, flag) {
+function need16(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -5060,7 +5424,7 @@ function registerHotelGetCheckoutCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const taskOrderCode = need15(opts.taskOrderCode, "task-order-code");
+    const taskOrderCode = need16(opts.taskOrderCode, "task-order-code");
     if (opts.watch) {
       await watchCheckoutStatus(deps.apiClient, apiKey, taskOrderCode, {
         intervalSeconds: resolveSeconds(
@@ -5164,7 +5528,7 @@ function registerHotelListOrdersCommand(parent, deps) {
 }
 
 // src/hotel-redaug/find-destination.ts
-function need16(value, flag) {
+function need17(value, flag) {
   if (value === void 0 || value.trim() === "") {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -5198,7 +5562,7 @@ function registerHotelFindDestinationCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const keyword = need16(opts.keyword, "keyword");
+    const keyword = need17(opts.keyword, "keyword");
     const body = { keyword };
     if (opts.dataType !== void 0) {
       body.data_type = opts.dataType;
@@ -5222,14 +5586,14 @@ function registerHotelFindDestinationCommand(parent, deps) {
 }
 
 // src/hotel-redaug/hotel-filters.ts
-function need17(value, flag) {
+function need18(value, flag) {
   if (value === void 0 || value.trim() === "") {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
 function num9(value, flag) {
-  const n = Number(need17(value, flag));
+  const n = Number(need18(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -5309,7 +5673,7 @@ function registerHotelFiltersCommand(parent, deps) {
     }
     const body = {};
     if (hasDestination) {
-      body.destination_id = need17(opts.destinationId, "destination-id");
+      body.destination_id = need18(opts.destinationId, "destination-id");
     } else {
       body.lat = coord2(opts.lat, "lat", -90, 90);
       body.lng = coord2(opts.lng, "lng", -180, 180);
@@ -5334,7 +5698,7 @@ function registerHotelFiltersCommand(parent, deps) {
 }
 
 // src/hotel-redaug/list-cities.ts
-function need18(value, flag) {
+function need19(value, flag) {
   if (value === void 0 || value.trim() === "") {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -5367,7 +5731,7 @@ function registerHotelListCitiesCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const country = need18(opts.country, "country");
+    const country = need19(opts.country, "country");
     const body = { country_code: country };
     const result = await deps.apiClient.post(
       "/hotel/cities",
@@ -5388,7 +5752,7 @@ function registerHotelListCitiesCommand(parent, deps) {
 }
 
 // src/hotel-redaug/hotel-detail.ts
-function need19(value, flag) {
+function need20(value, flag) {
   if (value === void 0 || value.trim() === "") {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
@@ -5535,7 +5899,7 @@ function registerHotelDetailCommand(parent, deps) {
       message: "API Key:",
       type: "password"
     });
-    const hotelId = need19(opts.hotelId, "hotel-id");
+    const hotelId = need20(opts.hotelId, "hotel-id");
     const rawWithImages = opts.withImages;
     const withImages = rawWithImages !== "false" && rawWithImages !== false;
     const settings = parseSettings(opts.settings);
@@ -5743,14 +6107,14 @@ function registerHotelSkillCommand(parent) {
 }
 
 // src/flight-flink/_helpers.ts
-function need20(value, flag) {
+function need21(value, flag) {
   if (value === void 0) {
     throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
   }
   return value;
 }
 function num10(value, flag) {
-  const n = Number(need20(value, flag));
+  const n = Number(need21(value, flag));
   if (!Number.isFinite(n)) {
     throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
   }
@@ -5785,7 +6149,7 @@ function registerFindAirportCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const keyword = need20(opts.keyword, "keyword");
+    const keyword = need21(opts.keyword, "keyword");
     const spinner = format === "json" ? null : createSpinner("Resolving airports...");
     const result = await deps.apiClient.post(
       "/flight/find-airport",
@@ -5874,7 +6238,7 @@ function registerListNationalitiesCommand(parent, deps) {
 
 // src/flight-flink/search.ts
 function registerSearchCommand(parent, deps) {
-  const cmd = parent.command("search").description("Search flights (one-way/round-trip/multi-city, journeyId relay)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--trip-type <n>", "1=one-way, 2=round-trip, 3=multi-city").option("--journeys <json>", "JSON array of {date, origin, destination, origin_type?, destination_type?}").option("--cabin-class <c>", "economy | premium_economy | business | first", "economy").option("--adult-num <n>", "Adults (1-9)", "1").option("--child-num <n>", "Children (0-9)", "0").option("--infant-num <n>", "Infants (0-9)", "0").option("--airline <code>", "Airline 2-letter code filter").option("--transfer-number <n>", "0=any,1=direct,2=1 stop,3=2 stops", "0").option("--journey-id <json>", "JSON array of already-selected journey ids (relay)");
+  const cmd = parent.command("search").description("Search flights (one-way/round-trip/multi-city, journeyId relay)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--trip-type <n>", "1=one-way, 2=round-trip, 3=multi-city").option("--journeys <json>", "JSON array of {date, origin, destination, origin_type?, destination_type?}").option("--cabin-class <c>", "economy | premium_economy | business | first", "economy").option("--adult-num <n>", "Adults (1-9)", "1").option("--child-num <n>", "Children (0-9)", "0").option("--infant-num <n>", "Infants (0-9)", "0").option("--airline <code>", "Airline 2-letter code filter").option("--transfer-number <n>", "0=any,1=direct,2=1 stop,3=2 stops", "0").option("--journey-id <json>", "Relay: the chosen offer's next_journey_ids, verbatim (round-trip/multi-city)");
   attachSchemaHelp(cmd, flightSearchSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
@@ -5882,7 +6246,7 @@ function registerSearchCommand(parent, deps) {
     const apiKey = await resolveApiKey(opts.apiKey);
     const body = {
       trip_type: num10(opts.tripType, "trip-type"),
-      journeys: jsonArray(need20(opts.journeys, "journeys"), "journeys"),
+      journeys: jsonArray(need21(opts.journeys, "journeys"), "journeys"),
       cabin_class: opts.cabinClass,
       adult_num: num10(opts.adultNum, "adult-num"),
       child_num: num10(opts.childNum, "child-num"),
@@ -5913,7 +6277,7 @@ function registerMoreOffersCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const productToken = need20(opts.productToken, "product-token");
+    const productToken = need21(opts.productToken, "product-token");
     const spinner = format === "json" ? null : createSpinner("Fetching offers...");
     const result = await deps.apiClient.post(
       "/flight/more-offers",
@@ -5934,7 +6298,7 @@ function registerVerifyCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const productToken = need20(opts.productToken, "product-token");
+    const productToken = need21(opts.productToken, "product-token");
     const spinner = format === "json" ? null : createSpinner("Verifying price...");
     const result = await deps.apiClient.post(
       "/flight/verify",
@@ -5956,7 +6320,7 @@ function registerVerifyCommand(parent, deps) {
 }
 
 // src/flight-flink/create-order.ts
-import { confirm as confirm9 } from "@inquirer/prompts";
+import { confirm as confirm10 } from "@inquirer/prompts";
 function registerCreateOrderCommand(parent, deps) {
   const cmd = parent.command("create-order").description("Create a flight order without charging (locks the fare, await payment)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--product-token <token>", "Authoritative rate token from verify").option("--total-amount <amount>", "Verified total price in decimal units").option("--currency <currency>", "ISO 4217 currency code").option("--trip-type <n>", "1/2/3", "1").option("--contact-name <name>", "Booking contact name").option("--contact-region <code>", "Contact phone country code (no '+')").option("--contact-phone <phone>", "Booking contact phone").option("--contact-email <email>", "Booking contact email").option("--passengers <json>", "JSON array of passengers (gender/id_type are strings)").option("--payment-method-id <id>", "Optional bound-card id (pay_per_call only)").option("--payment-token-id <id>", "Optional UPI network-token id (unionpay charge path)").option(
     "--authorized-merchant-trans-id <id>",
@@ -5968,19 +6332,19 @@ function registerCreateOrderCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const productToken = need20(opts.productToken, "product-token");
+    const productToken = need21(opts.productToken, "product-token");
     const totalAmount = num10(opts.totalAmount, "total-amount");
-    const currency = need20(opts.currency, "currency");
+    const currency = need21(opts.currency, "currency");
     const body = {
       product_token: productToken,
       total_amount: totalAmount,
       currency,
       trip_type: num10(opts.tripType, "trip-type"),
-      contact_name: need20(opts.contactName, "contact-name"),
-      contact_region: need20(opts.contactRegion, "contact-region"),
-      contact_phone: need20(opts.contactPhone, "contact-phone"),
-      contact_email: need20(opts.contactEmail, "contact-email"),
-      passengers: jsonArray(need20(opts.passengers, "passengers"), "passengers")
+      contact_name: need21(opts.contactName, "contact-name"),
+      contact_region: need21(opts.contactRegion, "contact-region"),
+      contact_phone: need21(opts.contactPhone, "contact-phone"),
+      contact_email: need21(opts.contactEmail, "contact-email"),
+      passengers: jsonArray(need21(opts.passengers, "passengers"), "passengers")
     };
     if (opts.paymentMethodId !== void 0) body.payment_method_id = opts.paymentMethodId;
     if (opts.paymentTokenId !== void 0) body.payment_token_id = opts.paymentTokenId;
@@ -5990,7 +6354,7 @@ function registerCreateOrderCommand(parent, deps) {
     const member = memberIdOf(opts);
     if (member !== void 0) body.member_id = member;
     if (!isYes) {
-      const ok = await confirm9({
+      const ok = await confirm10({
         message: `Create this flight order for ${totalAmount} ${currency}? This locks the fare but does NOT charge yet.`,
         default: false
       });
@@ -6029,11 +6393,20 @@ function registerCreateOrderCommand(parent, deps) {
 }
 
 // src/flight-flink/pay-order.ts
-import { confirm as confirm10 } from "@inquirer/prompts";
+import { confirm as confirm11 } from "@inquirer/prompts";
 function registerPayOrderCommand(parent, deps) {
   const cmd = parent.command("pay-order").description("Settle a created order by --order-no (triggers ticketing)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-no <id>", "Our order reference from create-order").option("--payment-method-id <id>", "Optional bound-card id to charge (pay_per_call only)").option("--payment-token-id <id>", "Optional network-token id (unionpay/visa charge path)").option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token)"
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -6044,9 +6417,9 @@ function registerPayOrderCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const orderNo = need20(opts.orderNo, "order-no");
+    const orderNo = need21(opts.orderNo, "order-no");
     if (!isYes) {
-      const ok = await confirm10({
+      const ok = await confirm11({
         message: `Pay and ticket order ${orderNo}? This settles the order and issues tickets.`,
         default: false
       });
@@ -6063,6 +6436,11 @@ function registerPayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (opts.authorizedChargeNo !== void 0) {
+      body.authorized_charge_no = opts.authorizedChargeNo;
+    }
     if (opts.evoExplicit) body.evo_explicit = true;
     const result = await deps.apiClient.post(
       `/flight/${encodeURIComponent(orderNo)}/pay`,
@@ -6072,15 +6450,16 @@ function registerPayOrderCommand(parent, deps) {
     );
     spinner?.stop();
     if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
-    await render2(
-      result.data,
-      opts.format,
-      (d) => Formatter.keyValue([
+    await render2(result.data, opts.format, (d) => {
+      const rows = [
         ["Order no", String(d.order_no ?? "-")],
         ["Status", String(d.status ?? "-")],
         ["Amount", `${d.amount ?? "-"} ${d.currency ?? ""}`.trim()]
-      ])
-    );
+      ];
+      if (d.charge_no) rows.push(["Charge no", String(d.charge_no)]);
+      if (d.three_ds_url) rows.push(["3DS URL", String(d.three_ds_url)]);
+      return Formatter.keyValue(rows);
+    });
   });
 }
 
@@ -6096,7 +6475,7 @@ function registerGetOrderCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const orderNo = need20(opts.orderNo, "order-no");
+    const orderNo = need21(opts.orderNo, "order-no");
     const path = `/flight/${encodeURIComponent(orderNo)}/status`;
     const auth = { type: "api-key", key: apiKey };
     if (opts.watch) {
@@ -6136,7 +6515,7 @@ function registerGetOrderCommand(parent, deps) {
 }
 
 // src/flight-flink/cancel-order.ts
-import { confirm as confirm11 } from "@inquirer/prompts";
+import { confirm as confirm12 } from "@inquirer/prompts";
 function registerCancelOrderCommand(parent, deps) {
   const cmd = parent.command("cancel-order").description("Cancel an un-ticketed flight order (with refund)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-no <id>", "Our order reference").option("--reason <text>", "Optional cancellation reason").option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
   attachSchemaHelp(cmd, flightCancelOrderSchema);
@@ -6145,9 +6524,9 @@ function registerCancelOrderCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const orderNo = need20(opts.orderNo, "order-no");
+    const orderNo = need21(opts.orderNo, "order-no");
     if (!isYes) {
-      const ok = await confirm11({
+      const ok = await confirm12({
         message: `Cancel order ${orderNo}? This requests cancellation and a refund.`,
         default: false
       });
@@ -6221,10 +6600,10 @@ function registerChangeSearchCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
     const body = {
-      order_no: need20(opts.orderNo, "order-no"),
-      date: need20(opts.date, "date"),
-      passenger: need20(opts.passenger, "passenger"),
-      segment_id: need20(opts.segmentId, "segment-id"),
+      order_no: need21(opts.orderNo, "order-no"),
+      date: need21(opts.date, "date"),
+      passenger: need21(opts.passenger, "passenger"),
+      segment_id: need21(opts.segmentId, "segment-id"),
       cabin_class: opts.cabinClass
     };
     const spinner = format === "json" ? null : createSpinner("Searching change options...");
@@ -6240,7 +6619,7 @@ function registerChangeSearchCommand(parent, deps) {
 }
 
 // src/flight-flink/change-apply.ts
-import { confirm as confirm12 } from "@inquirer/prompts";
+import { confirm as confirm13 } from "@inquirer/prompts";
 function registerChangeApplyCommand(parent, deps) {
   const cmd = parent.command("change-apply").description("Submit a change request (returns change_order_no, pending review)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-no <id>", "Our order reference").option("--passenger <code>", "passengerCode").option("--segment-id <ids>", "Comma-separated segment ids").option("--product-token <token>", "Change priceKey token").option("--contact-name <name>", "Contact name").option("--contact-region <code>", "Contact region").option("--contact-phone <phone>", "Contact phone").option("--contact-email <email>", "Contact email").option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
   attachSchemaHelp(cmd, flightChangeApplySchema);
@@ -6250,17 +6629,17 @@ function registerChangeApplyCommand(parent, deps) {
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
     const body = {
-      order_no: need20(opts.orderNo, "order-no"),
-      passenger: need20(opts.passenger, "passenger"),
-      segment_id: need20(opts.segmentId, "segment-id"),
-      product_token: need20(opts.productToken, "product-token"),
-      contact_name: need20(opts.contactName, "contact-name"),
-      contact_region: need20(opts.contactRegion, "contact-region"),
-      contact_phone: need20(opts.contactPhone, "contact-phone"),
-      contact_email: need20(opts.contactEmail, "contact-email")
+      order_no: need21(opts.orderNo, "order-no"),
+      passenger: need21(opts.passenger, "passenger"),
+      segment_id: need21(opts.segmentId, "segment-id"),
+      product_token: need21(opts.productToken, "product-token"),
+      contact_name: need21(opts.contactName, "contact-name"),
+      contact_region: need21(opts.contactRegion, "contact-region"),
+      contact_phone: need21(opts.contactPhone, "contact-phone"),
+      contact_email: need21(opts.contactEmail, "contact-email")
     };
     if (!isYes) {
-      const ok = await confirm12({
+      const ok = await confirm13({
         message: `Submit a change request for order ${body.order_no}?`,
         default: false
       });
@@ -6291,7 +6670,7 @@ function registerChangeDetailCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const changeOrderNo = need20(opts.changeOrderNo, "change-order-no");
+    const changeOrderNo = need21(opts.changeOrderNo, "change-order-no");
     const spinner = format === "json" ? null : createSpinner("Fetching change detail...");
     const result = await deps.apiClient.get(
       `/flight/change/${encodeURIComponent(changeOrderNo)}`,
@@ -6304,7 +6683,7 @@ function registerChangeDetailCommand(parent, deps) {
 }
 
 // src/flight-flink/change-cancel.ts
-import { confirm as confirm13 } from "@inquirer/prompts";
+import { confirm as confirm14 } from "@inquirer/prompts";
 function registerChangeCancelCommand(parent, deps) {
   const cmd = parent.command("change-cancel").description("Cancel a change request (immediate terminal)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--change-order-no <id>", "Change order number").option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
   attachSchemaHelp(cmd, flightChangeCancelSchema);
@@ -6313,9 +6692,9 @@ function registerChangeCancelCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const changeOrderNo = need20(opts.changeOrderNo, "change-order-no");
+    const changeOrderNo = need21(opts.changeOrderNo, "change-order-no");
     if (!isYes) {
-      const ok = await confirm13({ message: `Cancel change request ${changeOrderNo}?`, default: false });
+      const ok = await confirm14({ message: `Cancel change request ${changeOrderNo}?`, default: false });
       if (!ok) throw new CliError("CLIENT_ABORTED", "Change cancellation aborted by user.");
     }
     const idempotencyKey = await resolveIdempotencyKey(opts.idempotencyKey, {
@@ -6336,7 +6715,7 @@ function registerChangeCancelCommand(parent, deps) {
 }
 
 // src/flight-flink/change-pay.ts
-import { confirm as confirm14 } from "@inquirer/prompts";
+import { confirm as confirm15 } from "@inquirer/prompts";
 function registerChangePayCommand(parent, deps) {
   const cmd = parent.command("change-pay").description("Pay a change request fee (like a normal order) and trigger change ticketing").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--change-order-no <id>", "Change order number").option("--order-no <id>", "Original order reference (ownership check)").option("--amount <amount>", "Change fee total in decimal units (change-detail price_total)").option("--currency <currency>", "ISO 4217 currency code", "USD").option("--payment-method-id <id>", "Optional bound-card id (EVO path)").option("--payment-token-id <id>", "Optional UPI network-token id (unionpay charge path)").option(
     "--authorized-merchant-trans-id <id>",
@@ -6348,10 +6727,10 @@ function registerChangePayCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const changeOrderNo = need20(opts.changeOrderNo, "change-order-no");
-    const orderNo = need20(opts.orderNo, "order-no");
+    const changeOrderNo = need21(opts.changeOrderNo, "change-order-no");
+    const orderNo = need21(opts.orderNo, "order-no");
     const amount = num10(opts.amount, "amount");
-    const currency = need20(opts.currency, "currency");
+    const currency = need21(opts.currency, "currency");
     const body = {
       order_no: orderNo,
       amount,
@@ -6365,7 +6744,7 @@ function registerChangePayCommand(parent, deps) {
     if (!isYes) {
       const isResume = opts.authorizedMerchantTransId !== void 0;
       const message = isResume ? `Resume change fee ${amount} ${currency} for change order ${changeOrderNo}? The card is already authorised; this captures it and triggers change ticketing.` : `Pay change fee ${amount} ${currency} for change order ${changeOrderNo}? This charges the customer and triggers change ticketing.`;
-      const ok = await confirm14({ message, default: false });
+      const ok = await confirm15({ message, default: false });
       if (!ok) throw new CliError("CLIENT_ABORTED", "Change payment aborted by user.");
     }
     const idempotencyKey = await resolveIdempotencyKey(opts.idempotencyKey, {
@@ -6412,7 +6791,7 @@ function registerChangePayCommand(parent, deps) {
 }
 
 // src/flight-flink/refund-apply.ts
-import { confirm as confirm15 } from "@inquirer/prompts";
+import { confirm as confirm16 } from "@inquirer/prompts";
 function registerRefundApplyCommand(parent, deps) {
   const cmd = parent.command("refund-apply").description("Submit a refund request (returns refund_order_no, pending review)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-no <id>", "Our order reference").option("--passenger <code>", "passengerCode").option("--segment-id <ids>", "Comma-separated segment ids").option("--reason-type <n>", "Refund reason type code").option("--reason <text>", "Free-text reason").option("--contact-name <name>", "Contact name").option("--contact-region <code>", "Contact region").option("--contact-phone <phone>", "Contact phone").option("--contact-email <email>", "Contact email").option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
   attachSchemaHelp(cmd, flightRefundApplySchema);
@@ -6422,18 +6801,18 @@ function registerRefundApplyCommand(parent, deps) {
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
     const body = {
-      order_no: need20(opts.orderNo, "order-no"),
-      passenger: need20(opts.passenger, "passenger"),
-      segment_id: need20(opts.segmentId, "segment-id"),
+      order_no: need21(opts.orderNo, "order-no"),
+      passenger: need21(opts.passenger, "passenger"),
+      segment_id: need21(opts.segmentId, "segment-id"),
       reason_type: num10(opts.reasonType, "reason-type"),
-      contact_name: need20(opts.contactName, "contact-name"),
-      contact_region: need20(opts.contactRegion, "contact-region"),
-      contact_phone: need20(opts.contactPhone, "contact-phone"),
-      contact_email: need20(opts.contactEmail, "contact-email")
+      contact_name: need21(opts.contactName, "contact-name"),
+      contact_region: need21(opts.contactRegion, "contact-region"),
+      contact_phone: need21(opts.contactPhone, "contact-phone"),
+      contact_email: need21(opts.contactEmail, "contact-email")
     };
     if (opts.reason !== void 0) body.reason = opts.reason;
     if (!isYes) {
-      const ok = await confirm15({
+      const ok = await confirm16({
         message: `Submit a refund request for order ${body.order_no}?`,
         default: false
       });
@@ -6464,7 +6843,7 @@ function registerRefundDetailCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const refundOrderNo = need20(opts.refundOrderNo, "refund-order-no");
+    const refundOrderNo = need21(opts.refundOrderNo, "refund-order-no");
     const spinner = format === "json" ? null : createSpinner("Fetching refund detail...");
     const result = await deps.apiClient.get(
       `/flight/refund/${encodeURIComponent(refundOrderNo)}`,
@@ -6477,7 +6856,7 @@ function registerRefundDetailCommand(parent, deps) {
 }
 
 // src/flight-flink/refund-confirm.ts
-import { confirm as confirm16 } from "@inquirer/prompts";
+import { confirm as confirm17 } from "@inquirer/prompts";
 function registerRefundConfirmCommand(parent, deps) {
   const cmd = parent.command("refund-confirm").description('Confirm ("1") or cancel ("2") a refund').option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--refund-order-no <id>", "Refund order number").option("--confirm <flag>", '"1" confirm / "2" cancel').option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
   attachSchemaHelp(cmd, flightRefundConfirmSchema);
@@ -6486,14 +6865,14 @@ function registerRefundConfirmCommand(parent, deps) {
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await resolveApiKey(opts.apiKey);
-    const refundOrderNo = need20(opts.refundOrderNo, "refund-order-no");
-    const confirmFlag = need20(opts.confirm, "confirm");
+    const refundOrderNo = need21(opts.refundOrderNo, "refund-order-no");
+    const confirmFlag = need21(opts.confirm, "confirm");
     if (confirmFlag !== "1" && confirmFlag !== "2") {
       throw new CliError("PARAM_INVALID", '--confirm must be "1" (confirm) or "2" (cancel).');
     }
     if (!isYes) {
       const action = confirmFlag === "1" ? "confirm" : "cancel";
-      const ok = await confirm16({ message: `${action} refund ${refundOrderNo}?`, default: false });
+      const ok = await confirm17({ message: `${action} refund ${refundOrderNo}?`, default: false });
       if (!ok) throw new CliError("CLIENT_ABORTED", "Refund confirmation aborted by user.");
     }
     const idempotencyKey = await resolveIdempotencyKey(opts.idempotencyKey, {
@@ -6533,10 +6912,18 @@ verbs and pass data between them. For exact flags and field types, read the sche
 ## Workflow (book)
 1. find-airport --keyword "<place>"    \u2192 resolve to IATA city/airport codes
 2. search --trip-type <1|2|3> --journeys '<json>'
-   - journeys ALWAYS carries ALL legs. For round-trip/multi-city, relay journey-id
-     from the previous search into the next until price_key_ready is true.
-   - Only offers where price_key_ready is true carry a real product_token; earlier-leg
-     offers carry only an identifier (product_token null).
+   - journeys ALWAYS carries ALL legs, on every call including relay calls.
+   - Round-trip/multi-city: keep searching until is_final_leg is true. Each round, present the
+     candidates, let the USER pick one, and pass THAT candidate's next_journey_ids verbatim as
+     --journey-id on the next search. Never assemble the list yourself (the top-level journey_ids
+     is flattened across all candidates) and never send more ids than there are legs \u2014 it is
+     rejected, because upstream would otherwise silently answer with the FIRST leg's candidates.
+   - Only offers where price_key_ready is true carry a real product_token. Earlier-leg candidates
+     are NOT bare flight rows: total_sale_price is already the WHOLE-TRIP total and
+     paired_segment_ids names the legs upstream paired with it, so you can show the full
+     itinerary and real total from the first round \u2014 they just are not bookable yet.
+   - A relay search returning ZERO offers means the journey ids went stale OR that leg sold out
+     (upstream reports both as an empty list). Restart from leg 1 for fresh ids.
    - Code<->type consistency: tag each code with its matching type \u2014 an AIRPORT code (e.g. NRT)
      uses type 2, a CITY code (e.g. TYO) uses type 1. Mislabeling (e.g. NRT with type 1, since NRT
      is an airport whose city is TYO) is rejected with code 400 "destination not exist".
@@ -6572,7 +6959,7 @@ verbs and pass data between them. For exact flags and field types, read the sche
 ## Data passing
 - product_token : search \u2192 verify \u2192 create-order (opaque; never fabricate or edit; verify's token wins)
 - order_no      : create-order \u2192 pay-order / get-order / cancel-order
-- journey_id    : search \u2192 next search (relay for round-trip/multi-city)
+- next_journey_ids : chosen offer \u2192 next search's --journey-id (relay for round-trip/multi-city)
 - change_order_no / refund_order_no : *-apply \u2192 *-detail / *-confirm / pay-order (change)
 
 ## Invariants
@@ -6667,10 +7054,11 @@ Key notes:
   registerServicesListCommand(servicesCmd, { discoveryClient, program });
   registerServiceGetCommand(servicesCmd, { discoveryClient, program });
   const ordersCmd = program.command("orders").description(
-    "Unified cross-provider order index (ride + hotel + flight). Use for order history, common filters, and stable pagination."
+    'Unified cross-provider order index (spans ride + hotel + flight). Use list/get for generic "my orders" requests (use ride-elife/hotel-redaug/flight-flink commands once the business is known); pay-batch settles a batch of AWAITING_PAYMENT orders in one aggregate payment (trip checkout).'
   );
   registerOrdersListCommand(ordersCmd, deps);
   registerOrdersGetCommand(ordersCmd, deps);
+  registerOrdersPayBatchCommand(ordersCmd, deps);
   const hotelCmd = program.command("hotel-redaug").description(
     `Hotel booking (Redaug) \u2014 international hotel search, quote, create-order, pay-order, cancel, and check-out.
 
@@ -6724,7 +7112,8 @@ Key notes:
 Workflow (typical order):
   1. find-airport      Resolve a place name \u2192 IATA city/airport codes
   2. search            Search flights (one-way/round-trip/multi-city). journeys carries ALL legs;
-                       relay --journey-id for round-trip/multi-city until price_key_ready is true
+                       round-trip/multi-city: relay the chosen offer's next_journey_ids into
+                       --journey-id until is_final_leg is true
   3. verify            Verify the fare \u2192 authoritative product_token + price_changed flag
   4. create-order      Create the order using verify's product_token (locks the fare, no charge)
   5. pay-order         Settle by --order-no (triggers ticketing); order \u2192 PAID