Market Facilitator Journey

Role: Trusted local actor who facilitates order creation and origin scans on behalf of originators
Org: External (verified by Kaya Sync or client org)
Scope: Orders they facilitate only

---

Who They Are

Market Facilitators are informal-sector actors with trusted local presence at collection and dispatch points. They act as a bridge between originators and the Kaya Sync platform:

• Market queens / market women who coordinate freight at market sites
• Loading foremen at staging yards or aggregation points
• Aggregators who bundle small-shipper orders for corridor runs
• Station-side coordinators at transport terminals or road junctions

A Market Facilitator does not transport cargo. Their role ends when the origin scan is confirmed and the order passes to an Operator.

---

Preconditions

• Verified by Kaya Sync or a client organisation (identity check + agreement)
• Account provisioned by System Admin with Market Facilitator role
• Device issued or approved (PAYG or BYOD)

---

1. Onboarding

Step 1.1: Identity Registration (supervised)

• A Kaya Sync Admin creates the Market Facilitator profile
• Fields required: fullName, phoneNumber, idType, idNumber, verificationSource (Kaya Sync or client org name)
• Status set to: PENDING_VERIFICATION
• Errors: DUPLICATE_ACCOUNT, INVALID_ID

Step 1.2: First Login

• Market Facilitator enters phone number on device
• System sends SMS OTP (expires in 300 seconds)
• Enters OTP; receives accessToken, refreshToken, accountId
• Errors: INVALID_PHONE_NUMBER, INVALID_OTP, SESSION_EXPIRED

Step 1.3: Device Binding

• Submits device fingerprint (IMEI/hash/attestation)
• System binds device to account
• Device binding is required before any order or scan action can be performed

---

2. Order Creation on Behalf of Originator

Step 2.1: Capture Originator Details

• Market Facilitator creates a new order in the app
• Enters:
  • Originator name and phone number
  • Designee phone number
  • Cargo description and container count
  • Origin location (GPS or named market/yard)

Step 2.2: Originator Confirmation (if present)

• If the originator is physically present, the app prompts for OTP confirmation
• System sends OTP to originator's phone number
• Originator shares OTP with Market Facilitator; entered to confirm order creation
• If originator is absent, Market Facilitator attests on their behalf (logged in the Event Store)

Step 2.3: Order Created

• Order enters PendingOriginScan state
• Market Facilitator is recorded as the facilitating actor on the order

---

3. Origin Scan Facilitation

Step 3.1: Create Scan Record

• Market Facilitator creates a scan record for each container
• Scan type: ORIGIN
• Supplies GPS coordinates and timestamp

Step 3.2: Capture Video

• Mobile app guides Market Facilitator through capture:
  • Show designee phone number written on the container (OCR-matched by server)
  • Show full container, packaging, and condition
  • Video must be live capture (replay detection active)
• Works offline; video stored encrypted on device until connectivity returns

Step 3.3: Upload and Submit

• Market Facilitator requests a presigned upload URL
• Uploads video directly to object storage
• Submits scan to trigger AI integrity assessment

Step 3.4: AI Integrity Assessment

Outcome	Meaning	Next Step
PASS / PASS_WITH_TOLERANCE	All checks pass	Container → OriginVerified; Order → ReadyForDispatch
HOLD	Mismatch detected	Container → OnHold; rescan required
FAIL	Severe integrity violation	Escalated to Internal Ops Supervisor

---

4. Handoff to Operator

• Once origin scan passes, order enters ReadyForDispatch
• Ops Dispatcher or the auto-allocation engine assigns an Operator
• Market Facilitator's active custody ends at this point
• Market Facilitator receives confirmation that the order has been picked up

---

5. Tracking & Notifications

• Market Facilitator can view the status of orders they facilitated
• Receives SMS/Push notification when order is:
  • Picked up by Operator
  • Delivered to Designee
  • Placed on integrity hold (if relevant to their facilitation)
• Cannot view other organisations' orders or unrelated shipments

---

Edge Cases

Scenario	Behaviour
Originator absent, no OTP possible	Market Facilitator attests on originator's behalf; event logged with facilitator account ID
Origin scan rejected (HOLD)	Market Facilitator must recapture; order stays in PendingOriginScan
Origin scan rejected (FAIL)	Escalated to Internal Ops Supervisor; Market Facilitator notified
Market Facilitator loses connectivity during upload	Video stored encrypted offline; uploaded and submitted when connectivity returns
Dispute raised on a facilitated order	Dispute handled by Internal Ops Supervisor; Market Facilitator's scan evidence included in review

---