@fun-xyz/fiat-contract 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-OGNYHIOE.mjs";
+} from "./chunk-LVVQ46YG.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -295,7 +295,7 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = z.enum(["TRANSAK", "SWAPPED", "BANXA"]);
+var $provider = z.enum(["TRANSAK", "SWAPPED", "BANXA", "MOONPAY", "STRIPE"]);
 var FiatProviderSchema = $provider;
 var $kycProvider = z.enum(["SUMSUB"]);
 var KYCProviderSchema = $kycProvider;
@@ -392,7 +392,7 @@ var $refund = obj({
   expectedBy: z.string()
 });
 var RefundSchema = $refund;
-var $surfaceKind = z.enum(["URL_REDIRECT", "URL_EMBED", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var $surfaceKind = z.enum(["URL_REDIRECT", "KYC_SDK", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
 var SurfaceKindSchema = $surfaceKind;
 var $surface = obj({
   kind: $surfaceKind,
@@ -557,6 +557,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("CAPTURE"),
+  quote: $quote,
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -564,6 +565,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("INPUT_REQUIRED"),
+  quote: $quote,
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -571,6 +573,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("NO_ACTION_REQUIRED"),
+  quote: $quote,
   reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -778,45 +781,43 @@ var FIXTURE_DATA = {
     "state": {
       "kind": "KYC",
       "phase": "INPUT_REQUIRED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
       "form": {
-        "formId": "personal_details",
+        "formId": "kyc_q_8f2_1",
         "fields": [
           {
-            "id": "firstName",
+            "id": "tin",
             "type": "TEXT",
-            "labelFallback": "First name",
+            "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "dob",
-            "type": "DATE",
-            "labelFallback": "Date of birth",
-            "required": true
-          },
-          {
-            "id": "country",
-            "type": "COUNTRY",
-            "labelFallback": "Country",
+            "id": "address",
+            "type": "TEXT",
+            "labelFallback": "Home address",
             "required": true
-          },
-          {
-            "id": "sourceOfFunds",
-            "type": "SELECT",
-            "labelFallback": "Source of funds",
-            "required": true,
-            "options": [
-              {
-                "id": "salary",
-                "labelFallback": "Salary"
-              }
-            ]
-          },
-          {
-            "id": "idProof",
-            "type": "HOSTED_LINK",
-            "labelFallback": "Verify your ID",
-            "required": true,
-            "url": "\u2026"
           }
         ]
       }
@@ -828,7 +829,8 @@ var FIXTURE_DATA = {
         "mode": "SUBMIT",
         "endpoint": "POST /fiat/kyc/form",
         "params": {
-          "formId": "personal_details"
+          "quoteRef": "q_8f2",
+          "formId": "kyc_q_8f2_1"
         },
         "inputs": {
           "values": {
@@ -913,11 +915,84 @@ var FIXTURE_DATA = {
       }
     ]
   },
+  "screen-08-kyc-capture": {
+    "state": {
+      "kind": "KYC",
+      "phase": "CAPTURE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "surface": {
+        "kind": "KYC_SDK",
+        "provider": "SUMSUB",
+        "params": {
+          "accessToken": "eyJ\u2026"
+        },
+        "expiresAt": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/kyc/capture",
+          "params": {
+            "quoteRef": "q_8f2"
+          }
+        }
+      }
+    ]
+  },
   "screen-09-kyc-in-review": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "IN_REVIEW"
+      "reason": "IN_REVIEW",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -925,10 +1000,7 @@ var FIXTURE_DATA = {
         "id": "poll",
         "mode": "AWAIT",
         "poll": {
-          "endpoint": "GET /fiat/kyc",
-          "params": {
-            "quoteRef": "q_8f2"
-          },
+          "endpoint": "GET /fiat/quotes/q_8f2",
           "intervalMs": 3e3,
           "backoffFactor": 1.5,
           "maxIntervalMs": 1e4,
@@ -942,28 +1014,70 @@ var FIXTURE_DATA = {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
       "reason": "ON_HOLD",
-      "retryAfter": "2026-08-20T09:00:00Z"
+      "retryAfter": "2026-08-20T09:00:00Z",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": []
   },
-  "screen-11-kyc-rejected-escalation": {
+  "screen-11-kyc-rejected": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "REJECTED"
+      "reason": "REJECTED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "failureReason": {
+        "category": "KYC_REJECTED",
+        "retryable": false,
+        "recovery": "CONTACT_SUPPORT"
+      }
     },
     "provider": "TRANSAK",
-    "transitions": [
-      {
-        "id": "escalate",
-        "mode": "SUBMIT",
-        "endpoint": "GET /fiat/kyc",
-        "params": {
-          "tier": "escalated"
-        }
-      }
-    ]
+    "transitions": []
   },
   "screen-12-pending-order": {
     "state": {
@@ -1241,8 +1355,8 @@ var FIXTURES = [
   {
     id: "screen-03-kyc-input-required",
     file: "screen-03-kyc-input-required.json",
-    source: "FE_DOC",
-    docRef: "Screen 3 \xB7 Identity form (KYC)",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 L1 input round",
     screen: 3,
     stateKey: "KYC/INPUT_REQUIRED",
     notes: ["Carries the FORM_VALUES input spec \u2014 the no-double-carry case of the accepted split."]
@@ -1270,34 +1384,40 @@ var FIXTURES = [
       "TODO(open-decision): report target per card topology is a Transak ask (contract Flow A)."
     ]
   },
+  {
+    id: "screen-08-kyc-capture",
+    file: "screen-08-kyc-capture.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 embedded Sumsub WebSDK",
+    screen: 8,
+    stateKey: "KYC/CAPTURE",
+    notes: ["The client mounts the Sumsub adapter; no URL or iframe is emitted."]
+  },
   {
     id: "screen-09-kyc-in-review",
     file: "screen-09-kyc-in-review.json",
-    source: "FE_DOC",
-    docRef: "Screen 9 \xB7 Verifying identity",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 pending quote",
     screen: 9,
     stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW"
   },
   {
     id: "screen-10-kyc-on-hold",
     file: "screen-10-kyc-on-hold.json",
-    source: "FE_DOC",
-    docRef: "Screen 10 \xB7 Verification on hold",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 verification on hold",
     screen: 10,
     stateKey: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
     notes: ["transitions: [] and NOT terminal \u2014 the fixture that proves terminality is table data."]
   },
   {
-    id: "screen-11-kyc-rejected-escalation",
-    file: "screen-11-kyc-rejected-escalation.json",
-    source: "FE_DOC",
-    docRef: "Screen 11 \xB7 Verification unsuccessful",
+    id: "screen-11-kyc-rejected",
+    file: "screen-11-kyc-rejected.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 non-retryable rejection",
     screen: 11,
     stateKey: "KYC/NO_ACTION_REQUIRED:REJECTED",
-    notes: [
-      "TODO(open-decision): the escalation transition is a flagged placeholder \u2014 a GET carrying params is not a real request shape (FE doc Screen 11 + open question 7).",
-      "The terminal REJECTED variant (failureReason + transitions []) is described in prose, not published as JSON \u2014 no fixture."
-    ]
+    notes: ["Only an explicit non-retryable provider or identity-vendor outcome reaches this state."]
   },
   {
     id: "screen-12-pending-order",
@@ -1342,7 +1462,7 @@ var FIXTURES = [
     docRef: "Screen 16 \xB7 Not available",
     screen: 16,
     stateKey: "BLOCKED",
-    notes: ["The only flatly terminal state entry in the table."]
+    notes: ["A flatly terminal availability state; explicit non-retryable KYC rejection is terminal too."]
   },
   {
     id: "worked-example-01-quote",
@@ -1374,10 +1494,6 @@ var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
     reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
-  },
-  {
-    stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {

package/dist/table.d.ts

@@ -42,8 +42,7 @@ export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | '
 export declare const TERMINAL_ORDER_STATUSES: readonly ["SETTLED", "EXPIRED", "CANCELLED", "FAILED", "REFUNDED"];
 export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
 /**
- * Endpoint template as written in the docs — `:id` stands for an order id, so
- * `"POST /fiat/orders/:id/cancel"` matches the emitted `"POST /fiat/orders/o_31c/cancel"`.
+ * Endpoint template as written in the docs. Named `:` segments match one emitted path segment.
  */
 export type EndpointTemplate = FiatEndpoint;
 export interface AllowedTransition {
@@ -91,7 +90,7 @@ export declare const STATE_KEYS: StateKey[];
  * named by the table (QUOTE's capture-first entry) while the doc's endpoint table still lists no
  * session-minting call for that rail.
  */
-export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/kyc", "POST /fiat/kyc/form", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
+export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/quotes/:quoteRef", "POST /fiat/kyc/form", "POST /fiat/kyc/capture", "POST /fiat/kyc/sdk-token", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
 /**
  * Documented endpoints no flow state offers, and why. Declared so an endpoint nothing can reach is
  * visible instead of silent — the table test asserts the unoffered set equals exactly these.

package/dist/table.js

@@ -36,7 +36,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.7.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -162,21 +162,23 @@ var TRANSITION_TABLE = {
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
-        endpoint: "GET /fiat/kyc",
-        note: 'report target per FE bindings ("POST surface report \u2192 GET /fiat/kyc") and contract Flow C.'
+        endpoint: "POST /fiat/kyc/capture",
+        note: "Reports SDK submission; provider eligibility is re-evaluated through quote orchestration."
       }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: [
-      "Dropped from v1 (no UK headless-module coverage) \u2014 FE Screen 8 is a tombstone. Kind retained as vocabulary; the handshake (supportedStepKinds) keeps the backend from routing v1 SDKs here."
-    ]
+    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -188,16 +190,20 @@ var TRANSITION_TABLE = {
       { id: "submit_round", mode: "SUBMIT", endpoint: "POST /fiat/kyc/form" }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
     notes: [
       "One POST per round; conditional requirements may open another round.",
-      "FILE fields stream to POST /fiat/kyc/document \u2014 an upload path the harness owns, not a transition.",
+      "FILE fields use POST /fiat/kyc/document to obtain or report a direct provider/vendor upload; document bytes never transit Fun. The harness owns this auxiliary path, not a transition.",
       "Hosted KYC links arrive as HOSTED_LINK form fields, not as a Surface."
     ]
   },
@@ -208,12 +214,16 @@ var TRANSITION_TABLE = {
     reason: "IN_REVIEW",
     screens: [9],
     docStatus: "SPECIFIED",
-    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/kyc" }],
+    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/quotes/:quoteRef" }],
     mayReturn: [
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
@@ -243,20 +253,11 @@ var TRANSITION_TABLE = {
     reason: "REJECTED",
     screens: [11],
     docStatus: "SPECIFIED",
-    allowedTransitions: [
-      {
-        id: "escalate",
-        mode: "SUBMIT",
-        endpoint: "GET /fiat/kyc",
-        when: "an escalation round is offered",
-        note: "TODO(open-decision): placeholder shape \u2014 the FE doc flags that a GET carrying params is not a real request shape, and OQ7 owns which rejections escalate. FE doc open question 7."
-      }
-    ],
-    mayReturn: KYC_ANY,
-    terminal: false,
+    allowedTransitions: [],
+    mayReturn: [],
+    terminal: true,
     notes: [
-      "Terminal *variant*: failureReason {KYC_REJECTED, retryable: false, recovery: CONTACT_SUPPORT} + transitions [] \u2014 renders in place, never routes through ORDER{CREATED, FAILED}. Because escalation is also legal here, the entry is not flatly terminal.",
-      "TODO(open-decision): contract OQ7 \u2014 terminal vs escalating rejections are not enumerated."
+      "Only explicit non-retryable outcomes reach REJECTED. Correctable failures return CAPTURE or INPUT_REQUIRED; provider-specific declines re-route before becoming user rejection."
     ]
   },
   PENDING_ORDER: {
@@ -418,8 +419,10 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/payment-session",
   "POST /fiat/session",
   "POST /fiat/session/verify",
-  "GET /fiat/kyc",
+  "GET /fiat/quotes/:quoteRef",
   "POST /fiat/kyc/form",
+  "POST /fiat/kyc/capture",
+  "POST /fiat/kyc/sdk-token",
   "POST /fiat/kyc/document",
   "POST /fiat/instruments",
   "POST /fiat/orders",
@@ -431,13 +434,17 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/surface-result"
 ];
 var UNOFFERED_ENDPOINTS = [
+  {
+    endpoint: "POST /fiat/kyc/sdk-token",
+    reason: "SDK token refresh is adapter-driven rather than a flow transition."
+  },
   {
     endpoint: "GET /fiat/payment-methods",
     reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
   },
   {
     endpoint: "POST /fiat/kyc/document",
-    reason: "FILE fields stream to it directly; the harness owns that upload path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
+    reason: "FILE fields use it for a direct provider/vendor upload handshake and completion report; the harness owns that auxiliary path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
   },
   {
     endpoint: "POST /fiat/instruments",

package/dist/table.mjs

@@ -11,7 +11,7 @@ import {
   tableEntry,
   unofferedEndpoints,
   unreachableStates
-} from "./chunk-OGNYHIOE.mjs";
+} from "./chunk-LVVQ46YG.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/dist/types.d.ts

@@ -56,19 +56,12 @@ export type HttpVerb = 'GET' | 'POST';
  * cannot express "no slash", so `GET /fiat/orders/${string}` also admits sub-paths. Precision at
  * that level is the table's job (`allowedTransitions` + `endpointMatches`), not the type's.
  */
-export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | 'GET /fiat/kyc' | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
+export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | `GET /fiat/quotes/${string}` | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/capture' | 'POST /fiat/kyc/sdk-token' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
 /**
- * FiatProvider is metadata: it selects the embedded provider SDK for CLIENT_SURFACE steps and
- * feeds analytics. It never drives sequencing (contract §The fiat step response).
- * TODO(open-decision): the docs name only Transak as a v1 provider for the headless flow
- * (contract §Decisions 3; Swapped-headless does not exist yet, Banxa is Tradeoff #4).
- * `SWAPPED` added at fun-backend's request (2026-08-17) so its legacy fops payment-provider id
- * has one shared vocabulary instead of a second fun-backend-local enum — it never appears as a
- * `FiatStepResponse.provider` value since Swapped's fops flow doesn't emit this response.
- * `BANXA` added at 0.7 (Provider Landscape: Tier 1). A vendor name here is a routing key only —
- * it never decides which fields exist, which is what keeps provider churn out of this package.
+ * Routing metadata, not sequencing policy. Reserved values may be emitted only after their adapter
+ * and conformance fixture land.
  */
-export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA';
+export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA' | 'MOONPAY' | 'STRIPE';
 /**
  * The order status vocabulary. Monotonic ranks, no backwards moves. Terminal outcomes are
  * OrderStatus, never FlowState kinds.
@@ -202,7 +195,7 @@ export interface Refund {
     expectedBy: string;
 }
 /** What the user sees, and therefore where it can be placed. */
-export type SurfaceKind = 'URL_REDIRECT' | 'URL_EMBED' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
+export type SurfaceKind = 'URL_REDIRECT' | 'KYC_SDK' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
 /**
  * Identity vendors Fun verifies into. Its own axis rather than a `FiatProvider` value, because
  * Fun is the KYC-of-record in its own tenant — an identity surface is never the onramp's to mint.
@@ -442,20 +435,23 @@ export type FlowState =
     channel: 'EMAIL_OTP';
     error?: FailureReason;
 }
-/** Dropped from v1 (no UK module coverage) — kind retained, handshake-gated. */
+/** Pre-order KYC states carry the routed quote so the entry screen can keep price visible. */
  | {
     kind: 'KYC';
     phase: 'CAPTURE';
+    quote: Quote;
     surface: Surface;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'INPUT_REQUIRED';
+    quote: Quote;
     form: FormDescriptor;
     error?: FailureReason;
 } | {
     kind: 'KYC';
     phase: 'NO_ACTION_REQUIRED';
+    quote: Quote;
     /**
      * Note the deliberate name collision (Charles's nit, review 2026-08-14): `ON_HOLD` appears
      * here as a KYC reason *and* in `OrderStatus`. They are different things and both names come
@@ -470,10 +466,9 @@ export type FlowState =
     reason: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
     retryAfter?: string;
     /**
-     * Terminal REJECTED variant carries this (FE doc Screen 11: `KYC_REJECTED`,
-     * `retryable: false`, `recovery: CONTACT_SUPPORT`) and renders in place — it never routes
-     * through `ORDER{CREATED, FAILED}`.
-     * TODO(open-decision): contract OQ7 — which rejections escalate vs terminate.
+     * REJECTED is reserved for an explicit non-retryable outcome and renders in place — it
+     * never routes through `ORDER{CREATED, FAILED}`. Correctable outcomes return CAPTURE or
+     * INPUT_REQUIRED; a provider-specific decline is handled by quote rerouting first.
      */
     failureReason?: FailureReason;
     error?: FailureReason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
   "license": "MIT",
   "repository": {