Merchant Portal¶
The Merchant Portal is for importers or merchant clients who need a supplier payment route recommendation from a FlowClaw Operator Company.
What The Merchant Portal Is For¶
The portal helps a merchant:
- sign in to the correct Operator Company workspace
- request a supplier payment route
- compare the recommended route at a safe summary level
- accept the route when ready
- see assigned route cases that an operator has made visible
- manage privacy and data-rights controls
It is not an admin console and it does not expose full route scoring internals.
Top-Level Layout¶
| Area | What it means | Merchant action |
|---|---|---|
| Top ticker | A scrolling trust/status strip shown above the main nav. | Read-only. |
| Top nav | Logo, menu button, signed-in user, active tenant, and sign out. | Use Menu for navigation or Sign Out to end session. |
| GDPR banner | Cookie and data processing notice. | Choose Essential Only, Settings, or Accept All. |
| Left content area | Login, route request, pilot cases, privacy panel, or route decision content. | Main working area. |
| Right content area | Recommended route and execution steps after a route request succeeds. | Review route summary. |
| Sidebar | Navigation and account links. | Switch views. |
Sign In¶
The sign-in screen appears when no profile is loaded.
| Box or button | Meaning | What happens |
|---|---|---|
| Merchant account email. | Sent to POST /auth/login. |
|
| Password | Merchant account password. | Sent with the email for local login when local auth is enabled. |
| Sign In | Starts authentication. | Loads /auth/session, profile, active tenant, and roles if successful. |
If the signed-in user is not a Merchant Client, the portal shows a role mismatch warning. The warning exists because this portal is meant for the customer role, not the Desk Operator or Platform Admin role.
Sidebar Navigation¶
| Sidebar item | What it opens | Current behavior |
|---|---|---|
| New Supplier Route | Main route request form. | Fully wired. |
| Route History | Route history view. | Shows previous or available route activity when configured. |
| Pilot Cases | Assigned route cases visible to this merchant. | Loads /merchant/pilot-cases. |
| Profile Settings | Profile view. | Shows profile/account settings when configured. |
| Privacy & Data (GDPR) | Privacy and data rights panel. | Opens privacy panel. |
| Privacy Policy | External route /privacy-policy. |
Opens the configured privacy page. |
| Terms of Service | External route /terms. |
Opens the configured terms page. |
| Sign Out | Ends session. | Calls POST /auth/logout, clears profile/session state, returns to input view. |
New Supplier Route Form¶
This is the core merchant workflow.
| Field | What it means | Current values |
|---|---|---|
| Merchant Currency | The currency the merchant starts with. | NGN, KES, UGX, ETB, SSP |
| Supplier Settlement | The currency or asset the supplier should receive. | USD, USDT, USDC, CNY, CNH |
| Amount | The payment amount in merchant currency. | Numeric input. Default state in code is 8000. |
| Mode | How far execution is allowed to go. | Simulation, Guided Execution, Live Safe Probe, Automated Execution. |
Mode Meanings¶
| Mode | Plain English meaning |
|---|---|
| Simulation | Compare supplier-payment routes with no live execution. This is the safest default. |
| Guided Execution | Merchant authorizes, then operator approval and manual steps control execution. |
| Live Safe Probe | Tiny controlled live connector test. The backend has a safety cap for this mode. |
| Automated Execution | Policy-gated automation mode for supported configured connectors. |
Simulate Supplier Route Button¶
Button label: Simulate Supplier Route.
What it does:
- Sends the form to
POST /payment-request. - The backend creates a route session.
- The route engine generates candidate routes.
- Policy is evaluated.
- The response is stored in the portal as
session. - The portal switches to the route decision view.
Route Decision View¶
This appears after the route request succeeds.
| Box or field | What it means |
|---|---|
| Recommended Route | The route ID selected by FlowClaw. |
| Hops | Number of route steps in the recommended route. |
| Fee | Estimated route cost percentage from the recommendation. |
| Mode | The execution mode used for the request. |
| Execution Steps | The ordered provider/asset steps in the route. |
| Ask about this session | Runtime assistant box scoped to the current session. |
| Send Request | Sends the typed question to POST /runtime/requests. |
| Accept Route | Calls POST /sessions/{session_id}/approve. |
Accept Route¶
The merchant-side Accept Route button means: "I accept this recommended route."
It is different from a Desk Operator approval in the admin console. Merchant acceptance records the merchant decision; desk-side approval is an operational control decision.
After Accept Route succeeds, the portal switches to execution view and shows updated session state.
Runtime Assistant¶
The runtime assistant is a message box for session-scoped help.
Common merchant questions:
- "Why was this route recommended?"
- "What proof is needed?"
- "What are the steps?"
- "What happens next?"
- "Is this route simulated or live?"
Backend route: POST /runtime/requests.
The request includes:
- message text
- tenant ID
- workspace ID
- optional session ID
Assigned Route Cases¶
The Pilot Cases sidebar item loads merchant-visible route cases.
Backend route: GET /merchant/pilot-cases.
The merchant only sees cases that satisfy all conditions:
- same active tenant
- assigned to this merchant user
merchant_visible=true- returned through the merchant-safe response model
Route Case Fields¶
| Field | What it means |
|---|---|
| Case ID | Route case reference. |
| Corridor | Route corridor being tested, such as Nigeria-to-China. |
| Status | Current case state. |
| Recommendation summary | Merchant-safe route recommendation summary. |
| Required action | What the merchant needs to do, if anything. |
| Proof or outcome summary | Safe evidence/output summary exposed by the operator. |
The merchant view shows the safe summary for the case and hides operator-only scoring, internal notes, governance notes, and sensitive evidence details.
Privacy And Data Rights¶
The Privacy & Data panel explains GDPR-style data rights.
| Box or button | Meaning | Current backend status |
|---|---|---|
| Export My Data (JSON) | Downloads account data when this workflow is enabled. | Data rights action. |
| Essential Only | Stores cookie preference as essential only in browser local storage. | Local browser action. |
| Accept All | Stores cookie preference as all cookies accepted in browser local storage. | Local browser action. |
| Data Processing Consent | Explains processing reasons. | Read-only text. |
| Request Account Deletion | Submits an account deletion request when this workflow is enabled. | Data rights action. |
| Data Protection Officer | Shows contact route for data/privacy issues. | Read-only text. |
Merchant Visibility Rules¶
- Merchant pages show clear recommendations and required actions, not full operator scoring.
- Merchant acceptance records the merchant's decision for the route.
- Merchant users only see cases assigned to them in the active Operator Company workspace.
- Route cases appear in the Merchant Portal only after an operator publishes merchant-safe visibility.
Troubleshooting¶
| Symptom | Likely cause | What to do |
|---|---|---|
| Role mismatch warning | Signed in as admin/operator instead of merchant. | Use a Merchant Client account or switch to /index.html for operator work. |
| No pilot cases | No assigned visible cases, wrong tenant, or not a merchant role. | Ask the Desk Operator to assign and publish visibility. |
| Route request fails | Auth/session/tenant issue or backend validation error. | Check active tenant and API error message. |
| Export data is unavailable | Data export workflow is not enabled for the deployment. | Use the privacy/contact workflow. |
| Account deletion request is unavailable | Deletion workflow is not enabled for the deployment. | Use the privacy/contact workflow. |