Official System Manual & Knowledge Base

Architecture & Data Flow

1. Complete System Ecosystem

Eldoret Sherehe is a high-speed, secure event ticketing infrastructure designed specifically for Kenya. It bridges Public Ticket Buyers, Safaricom M-Pesa Daraja APIs, Event Organizers, and Gate Check-In Security with instant STK Push, automated SMS ticket delivery, and encrypted 5-character alphanumeric QR passes.

Diagram 1: End-to-End Ticketing & Verification Architecture

Instant STK Push No manual paybill dialing needed

Dual Delivery Instant SMS + 3D PDF pass

Zero Counterfeits 5-character codes & QR hashing

Mobile Scanner Works in any phone browser

Attendee & Buyer Guide

2. Event Showcase, Interactive Cart & Guest M-Pesa Checkout

The public event page on Eldoret Sherehe provides a seamless, continuous workflow where attendees can explore event logistics, select single or group passes, apply promo codes, and complete payment via Safaricom M-Pesa without ever needing to create an account, log in, or reload the page.

Diagram 2: Guest Checkout & Multi-Tier Fulfillment Journey

1

Full-Page Event Showcase

Browse event details: exact gate opening and closing times, dress code, age guidelines, artist lineup. If the organizer added GPS coordinates, attendees get a Venue & Location Guide with 1-click Google Maps navigation; if omitted, only the clean venue name is shown.

2

Interactive Multi-Tier Cart

Choose between Single Tickets (1 QR pass per unit) and Group Passes (clearly stating persons admitted, e.g. Couples = 2 PDFs, Squad = 4 PDFs). Live cart updates counts and totals in real time.

3

Apply Cash Promo Code

Enter a promoter or campaign code (e.g., VIP200). The engine instantly validates tier eligibility and subtracts flat cash amounts (e.g. -KES 200), showing net payable totals immediately.

4

Guest Checkout & Delivery

Provide Name, Email, and Phone. Toggle "Pay with different M-Pesa number" if gifting passes. On payment, you receive 1 consolidated SMS with download links to each ticket and separate emails for each ticket generated (each with its own PDF pass attached).

Live Safaricom Diagnostics & In-Place Retry

During payment, an interactive modal runs a 60-second countdown while listening to Safaricom Daraja callbacks. If a payment issue occurs, the system provides an immediate, plain-language diagnostic explanation:

Insufficient Balance: Explains that M-Pesa funds are below the order total and advises topping up before retrying.

Incorrect PIN: Advises that the wrong M-Pesa PIN was entered on the mobile handset.

Prompt Cancelled: Explains that the payment prompt was dismissed or cancelled on the phone.

Transaction Timeout: Notifies that the PIN was not entered within the 60-second carrier limit.

Zero Cart Loss: The "Retry Payment" button allows attendees to immediately re-prompt their phone without having to re-select tickets, re-type names, or re-enter promo codes.

Buying passes as a gift or for someone else?

Simply check the toggle "Pay with a different M-Pesa phone number" on the checkout form. Enter your own M-Pesa number for the PIN prompt, and enter your friend's phone number and email for delivery. The tickets and SMS gate links will be sent directly to them!

Multi-Ticket Delivery Rule One Consolidated SMS + Separate Emails per Ticket Generated

When an attendee selects multiple packages or quantities (e.g., Regular Pass × 3 or a combination of Regular, VIP, and Group passes), the fulfillment engine ensures optimal clarity and sharing ease:

Exactly 1 Consolidated SMS

Instead of sending multiple separate SMS messages that clutter the buyer's inbox, the system dispatches one single SMS listing download links for all issued tickets:

CONFIRMED!
Event: Nairobi Tech Summit
Passes (3):
1. Regular Pass (A1B2C):
https://eldoretsherehe.com/download.php?code=A1B2C
2. Regular Pass (D3E4F):
https://eldoretsherehe.com/download.php?code=D3E4F
3. Regular Pass (G5H6J):
https://eldoretsherehe.com/download.php?code=G5H6J
Show QR code at gate.

Separate Emails per Ticket Generated

For every individual ticket issued (e.g. 3 passes = 3 separate emails), a dedicated email is dispatched with the pass number (e.g. Pass 1 of 3, Pass 2 of 3) and that ticket's specific PDF attached directly (M-Tickets_Pass_[CODE].pdf):

Email 1: Regular Pass [A1B2C] + Attached PDF
Email 2: Regular Pass [D3E4F] + Attached PDF
Email 3: Regular Pass [G5H6J] + Attached PDF
Allows the purchaser to forward individual passes directly to colleagues, friends, or family with zero confusion!

Attendee Pass

3. Downloading & Presenting Your Ticket

How to Access Your PDF Ticket

Via Direct Link in SMS: Open the SMS you received upon payment and tap the ticket link (e.g., https://eldoretsherehe.com/download.php?code=A7X9K).
Via Re-Download Tool: If you accidentally deleted the SMS, visit Re-Download Ticket, type your 5-character code, and hit download.
Save Offline: Download the PDF to your phone files or take a clear screenshot of the QR code so you can access it at the gate even without mobile internet.

Gate Admission Tip: Turn up your phone screen brightness when presenting your QR code to the gate security officer for instantaneous scanning.

Sample Ticket Pass

Eldoret Sherehe PAID

Nairobi Sunset Fest 2026

Package: VIP All-Access

Date: Sat, 24 Oct 2026 • 6:00 PM

A7X9K

Show this QR code at the entrance

High-Resolution PDF Pass

Organizer Portal

4. Registering & Setting Up as an Event Organizer

Organizing events on Eldoret Sherehe gives you full self-service control: custom ticket packages, live revenue dashboards, M-Pesa STK push for your attendees, direct SMS broadcasts, and real-time gate scanner apps.

Diagram 3: 6-Stage Organizer Operational Lifecycle

1

Step 1: Sign Up

Open register.php, provide your Brand/Company Name, Email, and Phone number. Registration is free with instant account creation.

2

Step 2: Sign In

Log in at admin/index.php using your registered username or email and password.

3

Step 3: Setup Password OTP

You can update your security settings or change your password anytime under ?tab=password using instant SMS or Email OTP.

Billing & Top-Up

5. Credit Wallet & Pay-As-You-Go System

The platform operates on a transparent, affordable Pay-As-You-Go Credit System. Organizers maintain a small credit wallet that powers event listings and outgoing SMS notifications.

Diagram 4: Financial Flow & Credit Wallet Architecture

What are credits used for?

Event Listing: A one-time listing fee (typically 500 credits) to publish and activate an event on the public marketplace.
Ticket SMS Dispatch: Delivering the instant SMS ticket containing the 5-character pass code to attendees upon successful payment.
Audience Broadcasts: Sending custom bulk SMS updates, reminders, and directions to registered attendees.

How to Top-Up Your Wallet

Navigate to Credit Wallet (?tab=wallet).
Select a pre-set bundle (e.g., KES 500 = 500 Credits, KES 1,500, KES 5,000) or enter a custom amount.
Enter your Safaricom M-Pesa phone number.
Click Top Up Credits and enter your PIN on your phone. Credits reflect immediately!

Low Credit Badge: When your credit balance falls below 500 credits, a red "Low" pill appears on your sidebar next to Credit Wallet. Top up to ensure uninterrupted event listings and attendee SMS delivery.

Event Management

6. Creating Events & Multi-Tier Pricing

Organizers can create events with custom ticket categories (Early Bird, Regular, VIP, Corporate Table), banner posters, venue directions, and hard capacity limits.

Step-by-Step Event Setup

Click Events (?tab=events) in your organizer dashboard.
Click + Add New Event (or click the pencil icon to edit an existing event).
Fill in the core parameters in Step 1: Event Essentials:
- Event Title: High-impact, recognizable event name.
- Venue / Location Name: Specific physical venue name (e.g. KICC Tsavo Ballroom, Nairobi or Eldoret Sports Club).
- Venue GPS Coordinates Optional, but Recommended: Exact latitude and longitude pin. When provided, ticket buyers receive an interactive Venue & Location Guide with 1-click Google Maps turn-by-turn navigation. If left blank, the customer page displays only the venue name text.
- Date & Start Time: Exact event schedule.
- Ticket Limit / Capacity: Maximum tickets that can be sold before the system displays "Sold Out" (leave 0 for unlimited).
- Banner Poster: Upload JPG or PNG (Recommended: 1200x630 or 1080x1080).
Configure ticket packages, rules, artist lineup, and payment gateway across wizard steps, then click Publish Event Live (or Update Event Now).

Setting Venue GPS Coordinates (Map Picker)

When clicking Pin / Search on Map next to coordinates, organizers can choose any of 4 fast methods:

1. Search & Autocomplete: Type any landmark or road in Kenya (e.g. Carnivore Grounds, Sarit Expo) to see instant geocoded suggestions and auto-pin.

2. Click or Drag Pin: Click anywhere on the interactive map canvas or drag the marker pin directly to your exact gate or admission checkpoint.

3. Quick Paste: Paste latitude & longitude from WhatsApp or Google Maps (e.g. -1.2884, 36.8233) and click Apply.

4. Use My Current GPS: If you are physically on site, tap "Use My Current Location" to lock the coordinates from your phone/laptop.

Zero Clutter Guarantee: If coordinates are omitted, the customer page will cleanly hide the Location Guide card and display only the venue name.

Setting Ticket Packages / Tiers

Once an event is saved, add your custom pricing tiers under the event card:

Early Bird Pass KES 1,000

Limit: 100 tickets • Discounted first 48 hours

VIP Admission KES 3,500

Limit: 50 tickets • Complimentary drinks + front row

Corporate Table of 6 KES 20,000

Limit: 10 tables • Reserved table + branded signage

Physical Box Office

7. Box Office: Selling Tickets Manually for Cash

For gate sales, walk-in attendees paying cash, or complimentary VIP passes, organizers do not need to route through M-Pesa. Use the built-in Box Office module (?tab=sell).

1. Select Event & Tier

Choose which event and ticket tier the customer is purchasing at the desk.

2. Enter Attendee Phone

Enter the customer's mobile number so they receive their SMS ticket pass instantly.

3. Issue Ticket

Click Issue Ticket. The ticket is immediately generated, recorded in reports, and validated at the gate.

Real-Time Ledger

8. Live Transactions & Ticket Resending

The Transactions module (?tab=transactions) gives organizers a live audit trail of every purchase attempt, confirmed payment, and check-in status.

Status Badge	Meaning	Action Available
PAID	Payment confirmed via Safaricom M-Pesa. Ticket is valid and ready for gate scan.
USED	Ticket has already been verified and admitted at the gate by security.	View timestamp of admission.
PENDING	STK Push prompt was dispatched to phone; waiting for user PIN entry.	Auto-polls or user can re-try.
FAILED	User cancelled STK prompt, timed out, or had insufficient M-Pesa balance.	Can re-initiate booking.

One-Click Resend: If an attendee complains they did not receive their SMS (or mistyped their phone number), locate their ticket in ?tab=transactions using their 5-character code or M-Pesa receipt, click Resend, and the system immediately dispatches a fresh SMS.

Audience Messaging

9. Bulk SMS Broadcast to Attendees

Need to announce a gate opening time, parking advisory, artist line-up release, or weather alert? The Broadcast tab (?tab=broadcast) lets organizers message all confirmed ticket holders of any event in bulk.

How to Dispatch an SMS Announcement

Go to Broadcast (?tab=broadcast).
Select the target event from the dropdown menu (e.g., Nairobi Tech Summit 2026).
Review the target recipient count (e.g., "342 Paid Attendees").
Type your message (keep it concise, under 160 characters for a single SMS credit per user).
Click Send Broadcast. Delivery receipts update in real time.

Gate Security

10. Gate Check-In & Mobile Scanner Operations

Gate security and ushering teams use the built-in web scanner at admin/validate.php. It works seamlessly on any Android, iPhone, tablet, or laptop browser without installing any app from the App Store.

Diagram 5: Gate Scanner Validation Decision Tree

Camera Scanner Mode

Tap Scan QR Code on the validator screen. Your browser will ask for camera permission. Point the rear camera at the customer's QR code. Scanning happens in under 200 milliseconds!

Manual 5-Digit Fallback

If an attendee's phone screen is severely cracked, battery dying, or smudged, type their 5-character alphanumeric code (e.g. A7X9K) directly into the text box and click Validate Code.

Self-Service Help

11. Troubleshooting Matrix & FAQs

Solution: Ensure your phone has active Safaricom cellular reception and is unlocked. If your SIM card was busy with another menu or USSD session, wait 10 seconds and click "Pay with M-Pesa" again. Also ensure your phone format begins with 07... or 254....

Solution: Telecommunication SMS delivery can sometimes experience a 30-60 second network queue. You do not need to worry! Simply visit Re-Download Ticket, or contact event support with your M-Pesa Transaction code (e.g., SLK9XX...), and the organizer can resend the SMS instantly.

Solution: The system has recorded that this ticket was already scanned and admitted earlier. The screen displays the exact time and date it was validated. Gate staff must deny entry to prevent duplicate passes or ticket sharing.

Solution: Either the security staff is logged into a different event's scanner account, or the attendee has presented a ticket purchased for another event. The screen will specify which event the ticket was issued for.

Solution: For organizers using their own dedicated Daraja credentials under ?tab=configs, attendee ticket funds land directly in their own Safaricom Paybill or Till number in real-time. For platform-managed accounts, settlements are reconciled and disbursed via B2C M-Pesa or bank transfer as outlined in the organizer agreement.

Solution: Password resets are fully automated via Multi-Channel 6-Digit OTP:

Navigate to the Sign In screen and click Forgot Password? (or promoter_login.php?action=forgot for promoters).
Enter your registered email address or username. The platform identifies your user account whether you are an Organizer, Promoter, or Vendor / Equipment Supplier.
Select your preferred OTP delivery channel: Email or SMS.
Check your device or email inbox (OTP emails arrive directly in your Primary Inbox with authenticated sender verification).
Enter the 6-digit numeric passcode. The input automatically strips accidental spaces or punctuation if copied from an SMS or notification.
Enter your new password (min. 6 characters) and click Save Password & Sign In.

OTP codes remain valid for 15 minutes and are single-use. If your code expires, simply click Resend OTP to dispatch a fresh verification code.

Eldoret B2B Ecosystem Sourcing • Quoting • Invoicing Live Event P&L

12. B2B Event Vendor Marketplace, Procurement, Invoicing & Event Production P&L

The AlphaBridge B2B Event Vendor Marketplace seamlessly connects Event Organizers directly with vetted local Eldoret service providers across 14 Master Categories: Sound & Audio Engineering, Staging & Truss Rigging, DJ Backlines, Photography & Drone Cinematography, Mobile Catering & Mixologists, VIP Portable Sanitation, Security Stewards & Bodyguards, Event Décor & Thematic Draping, LED Video Walls & Livestreaming, Master of Ceremonies (MC), Heavy-Duty Tents & Marquees, Silent Diesel Power Generators, Paramedic Ambulances, and Stage Lighting & SFX.

Diagram 2: Complete B2B Procurement, Quoting, Invoicing & P&L Lifecycle

INV-XXXXXX • Milestone dates locked: Deposit Due (T+3) & Balance Due (T-1) • Paid directly via Vendor Till / Paybill / Bank → Official Receipt REC-XXXXXX Protected with Dynamic QR Code Authenticity Clearance SYNC P&L 5. UNIFIED EVENT PRODUCTION P&L Real-time bottom-line cashflow tracking: Net Margin = Tickets - Credits - Invoices • Tracks Total Invoiced vs Deposits Paid vs Outstanding Balance • Itemized production cost breakdown by audio, staging, catering

VENDOR GUIDE

12.1 Step-by-Step for Local Event Service Providers & Suppliers

Event gear suppliers, sound technicians, caterers, DJs, and security firms in Uasin Gishu County can list their company, publish rental gear inventories, receive tender inquiries, and issue binding legal quotations and invoices.

1

Onboarding & Storefront Registration

Navigate to vendor_register.php. Enter your Business Name, Primary Contact Person, official phone, registered email, and physical yard/office location (e.g. Eldoret CBD, Pioneer, Elgon View, Rivatex, Annex, Kapsoya).

Eldoret Yard Location

2

Settlement Configuration (How You Get Paid)

Configure your direct receiving channel so organizers can pay milestone deposits and final balances directly to your account:

Safaricom Buy Goods Till: 5-6 digit merchant Till number.
M-Pesa Paybill: Business shortcode + Account reference note.
Bank Account: Bank name, account name, and account number.

3

Building Your Digital Gear Catalogue

In the Vendor Portal, click Add Catalogue Item:

Master Category & Sub-Service Tag: Pick from the 14 categories.
Pricing Unit Model: per_day, per_event, per_hour, per_head, per_sqm, per_unit.
Rate Structure: Fixed rate or Price Range (Min - Max).
Lead Time: Setup lead time required in hours.
Transport Included Flag: Indicate if delivery within Eldoret is included.

4

Responding to Inquiries & Generating Quotes

Under the Quotes & RFQs tab, review incoming direct inquiries or open tenders. Click Build Quote to populate itemized line items, add transport/setup fees, apply customer discounts, define the deposit percentage (e.g. 50%), and set terms.

Instant Corporate PDF Quote

Vendor Tip: Always keep your equipment images high-resolution and maintain accurate daily stock quantities. Organizers in Eldoret filter their searches by yard proximity and item availability!

ORGANIZER GUIDE

12.2 Step-by-Step for Event Organizers (Procurement & Sourcing)

Event hosts can plan equipment requirements, estimate production costs, request competitive quotations, negotiate revisions, and execute binding contracts inside their dashboard at Admin → Vendor Marketplace.

1

Automatic Event Context

Select your event from the top dropdown bar. All procurement wishlists, RFQ dates, venue locations, and production P&L metrics will automatically bind to that event.

2

Pre-Quote Budget Estimator

Browse the verified directory, click Add to Wishlist, and tune quantity and days needed. The live estimator calculates your gear budget before you contact vendors.

3

Two Sourcing Pathways & Active Listing Rule

Pathway A: Send a Direct RFQ to a single supplier.
Pathway B: Broadcast an Open Tender across Eldoret. Note: To broadcast an open tender, organizers must have an active event listing (settled listing fee) and post the tender for their selected active listed event.

4

Side-by-Side Comparison

Evaluate proposals from competing suppliers side-by-side: review line rates, transport setup fees, deposit requirements, and vendor verification trust badges.

5

Threaded Negotiations

Need a counter-offer? Submit revision messages directly into the quote discussion thread. Vendors submit revised quote versions (v2, v3) with updated totals.

6

Accepting & Invoicing

Clicking Accept Quote automatically locks pricing, declines competing bids, and generates an official Commercial Invoice (INV-XXXXXX) with deposit terms.

Unified Event Production P&L Financial Tracker

The system unifies ticketing box office cashflows with supplier procurement into a live bottom-line metric:

Net Projected Profit = Gross Ticket Sales - Platform Credit Usage - Contracted Vendor Invoices

Ticket Revenue Paid Tickets

Platform Cost Credits Used

Vendor Invoiced Contract Sum

Deposits Paid Settled Now

Balance Due Due T-1 Day

Net Margin Real Profit

TRUST & VETTING STANDARD

12.3 "Verified Eldoret Supplier" Trust Badge Standard

To protect organizers and ensure high service standards across Uasin Gishu County, the platform maintains a rigorous verification protocol before certifying event service providers.

Verification Protocol

Compliance officers verify national identification, business permits, physical equipment yard addresses, and proven event execution records before awarding the trusted supplier seal.

Badge Benefits

Verified suppliers receive top ranking in search queries, a green [✓] Verified Eldoret Supplier trust badge on public directories, and certified trust marks on all official PDF documents.

ANTI-FRAUD SECURITY

12.4 Cryptographic Document Verification & QR Codes

All formal Quotations (QT-XXXXX), Commercial Invoices (INV-XXXXXX), and Official Receipts (REC-XXXXX) generated by the system embed a scannable authenticity QR code linked to verify_doc.php.

1. Scan Document QR Using any smartphone camera or QR scanner

2. Live Registry Check Direct database lookup of cryptographic reference

3. Instant Authenticity Clearance Displays certified vendor, dates, and amounts

Anti-Fraud Warning: Never accept PDF invoices or receipts that have missing or unverified QR codes. Genuine Eldoret Sherehe documents will always show the green "Official Document Authenticity Cleared" badge when scanned.

Exhibitors & Physical Booths

13. Event Stall Vendor Marketplace & Booking System

The Event Stall Vendor & Booking System integrates physical event booth allocation into Eldoret Sherehe. Event organizers can advertise booth spaces across 10 specialized categories, set upfront lock deposits, negotiate pricing directly with vendors, receive automated two-stage M-Pesa payments, enforce automated lock expiration countdowns, and verify vendor staff credentials at the event gate.

Diagram 6: Stall Reservation, Negotiation, Two-Stage Lock & Gate Scanner Lifecycle

10 Specialized Stall Categories

Vendors register and organizers filter booths using this standard taxonomy:

1. 360° Photo & Media Booths

2. Electronic Gaming & VR

3. Tabletop & Skill Games

4. Outdoor Inflatables & Rides

5. Beauty, Glam & Body Art

6. Food & Culinary Grills

7. Beverage, Bars & Lounges

8. Fashion & Thrift Pop-Ups

9. Arts, Crafts & Pottery

10. Corporate Brand Activations

6 Setup Utility Checklist Tags

Checkboxes for venue preparation and gate scanner displays:

Needs 240V Standard Electricity
High-Power / 3-Phase Required
Water Access Required
Open Flame / Charcoal / Gas Used
Brings Own Branded Tent
Needs Vehicle / Truck Access

Exhibitor Workflow: How to Book a Stall

1

Browse Public Stalls Marketplace

Visit stalls.php or click the stalls banner on any event ticket checkout page. Inspect dimensions, utilities, full price, upfront deposit required, remaining slots, and organizer direct WhatsApp links.

2

Book at Listed Price OR Propose Negotiation

Click Book at Listed Price to pay the standard terms, OR click Negotiate with Organizer to propose a custom total fee and upfront deposit alongside a pitch describing your setup.

3

Pay Upfront Lock Amount via M-Pesa

Select Pay via M-Pesa STK Push. Paying the upfront amount locks your position, reserves 1 slot, assigns your booth code (e.g. ST-02), and starts your balance countdown timer.

4

Clear Balance & Download Staff QR Passes

Track your timer in vendor_portal/index.php?tab=stalls. Complete the remaining balance via M-Pesa before the timer reaches 0 to unlock your Vendor Staff Entry QR Passes and official Allocation Certificate.

Organizer Workflow: Managing Stalls & Allocations

Create Packages

In ?tab=stalls, click Create Stall Package. Enter full price, upfront lock amount, inventory count, and expiration rule (countdown days vs cutoff date).

Price Negotiations

Review exhibitor proposals with Accept (locks custom rates), Counter-Offer (counter price + deposit + note), or Decline with instant SMS alerts.

Offline & Free Stalls

Allocate complimentary spots to sponsors (KES 0) or log cash payments collected offline. Instant vendor registration creates their account automatically.

Gate Scanner Behavior (`validate.php`)

When security scans a Vendor Staff Pass (STP-...):

GREEN: Entry Allowed → Confirmed Paid or Complimentary. Displays business name, stall #, and utilities.

RED: Balance Warning → Shows exact KES amount owing. Buttons to trigger instant M-Pesa STK push or Cash Override.

Segregated Financial Accounting Ledger

The financial dashboard maintains strict wall-fencing between revenue streams:

Online M-Pesa Revenue: Verified Daraja collections.
Offline / Cash Revenue: Bookkeeping tracking (isolated from wallet payouts).
Complimentary Stalls: Count of free partner spots.
Pending Balances: Expected incoming revenue from locked spots.

Promoter & Organizer Guide

14. Event Promoter Portal, Manual Cash Promo Codes & Invoicing

The Promoter & Influencer Ecosystem enables Event Organizers to partner with campus brand ambassadors, club resident DJs, MCs, street hype teams, and digital content creators using Event-Specific Manual Cash Promo Codes. The platform tracks ticket conversions with mathematical precision while keeping commission payouts transparent, direct, and settlement-flexible.

1. Strictly No Referral Links

No affiliate URLs, tracking query parameters, or browser cookies. All buyer discounts and promoter sales attributions operate strictly through memorable uppercase Promo Codes entered at checkout.

2. Manual Cash Only (No %)

No percentage calculations. Organizers manually configure exact flat Cash Amounts (in KES) for buyer discounts and promoter commissions per individual ticket tier (e.g. KES 100 off, KES 50 commission).

3. Off-Platform Settlements

The platform does not hold or move promoter commission funds. Promoters invoice organizers directly for accrued earnings, choose their preferred payout channel, and mark payments received to issue official receipts.

Diagram 14: End-to-End Promoter Attribution & Off-Platform Invoicing Lifecycle

PROMOTER USER MANUAL

14.1 Promoter's Step-by-Step Practical Handbook

As an Event Promoter (Campus Ambassador, MC, DJ, or Influencer), you earn direct cash commissions whenever ticket buyers use your unique Promo Code during checkout on Eldoret Sherehe. Here is how to register, promote, track sales, and get paid.

1

Create Account

Visit promoter_register.php. Enter your Full Name, Email, Phone Number, and a secure password.

Public Registration

2

Receive Promo Code

The event organizer assigns an active Promo Code (e.g. CAMPUS50) to your account. Your dashboard will display your code.

Assigned by Organizer

3

Promote & Track

Share your code across social media and campus. Track live ticket sales, gross revenue, and accrued commission in your portal.

Live Telemetry

4

Invoice & Get Paid

Click Generate Invoice. Select your payout option (M-Pesa, Bank, Cash, Till, Paybill, Cheque). Mark as paid upon settlement.

Direct Settlements

Understanding Your Promoter Dashboard KPI Cards (`promoter_portal/`)

TICKETS SOLD

Total Ticket Units

Number of passes redeemed

GROSS REVENUE

KES [Gross Sales]

Total cash value driven

EARNED COMMISSION

KES [Total Earned]

Cumulative earnings to date

UNBILLED BALANCE

KES [Ready to Bill]

Available to invoice now

How to Create & Send an Invoice to the Organizer

Log in to your portal at promoter_login.php.
In the Invoices & Earnings section, verify that your Unbilled Commission Balance is greater than KES 0.
Click the Generate Invoice button.
Enter the Invoice Amount (you can request full settlement or a partial installment).
Select your desired Payment Method from the 6 available options (see below) and fill in the required account details.
Click Submit Invoice. The organizer is immediately notified via SMS and Email to review and execute payment.

The 6 Supported Off-Platform Payout Channels

1. M-Pesa Send Money Enter your Safaricom mobile phone number (e.g. 0712345678). The organizer sends funds directly to your phone.

2. M-Pesa Till / Buy Goods Enter your business or personal Buy Goods Till Number. The organizer pays via the Lipa na M-Pesa Buy Goods menu.

3. M-Pesa Paybill Enter your Business Shortcode (Paybill number) and your specific Account Number reference.

4. Bank Wire Transfer Enter your Bank Name (e.g. Equity, KCB, Absa), the Account Holder Name, and Bank Account Number.

5. Cash in Hand For physical meetings where the organizer hands over physical Kenya Shillings banknotes in cash.

6. Bank Cheque Enter the exact legal Payee Name that must be written across the official bank cheque.

Acknowledging Payment & Issuing Official Transaction Receipts

Once the organizer sends the payment to your phone or bank account, log in to your promoter portal and locate the invoice under My Invoices. Click Mark as Paid (or Partially Paid), enter the transaction code (e.g. M-Pesa reference RKT92JSL4Q or bank transfer reference), and submit. The system instantly marks the tickets as settled and generates an official PDF Transaction Receipt for both you and the organizer.

ORGANIZER OPERATIONS

14.2 Organizer's Master Guide to Promoter Management (`?tab=promoters`)

Event Organizers have complete autonomy to create, allocate, monitor, and settle promoter campaigns inside the Organizer Dashboard at admin/index.php?tab=promoters. Here is how to configure promo codes, set profit margins, and manage payouts.

1

Create Promo Code

Click Create Promo Code. Specify the uppercase alphanumeric code (e.g. VIP100). Link to a registered promoter or keep as an in-house marketing code.

2

Tier-by-Tier Allocations

Select which ticket packages are eligible. Input exact flat cash amounts: Buyer Discount (KES) and Promoter Commission (KES).

3

Set Abuse Controls

Protect margins with expiration cutoffs: Date/Time Expiry, Max Total Tickets Cap, and Max Redemptions Per Phone.

Organizer Margin Safety Formula

Net Event Revenue = Ticket Price - Buyer Cash Discount - Promoter Cash Commission

Rule: Always ensure that Buyer Discount + Promoter Commission < Ticket Price. For example, on a KES 1,000 ticket, granting a KES 100 buyer discount and a KES 50 promoter commission leaves you with a healthy net of KES 850 per ticket sold.

Real-Time Funnel Telemetry & Telemetry Logs

The system records every buyer interaction with promo codes in real time inside promoter_redemption_attempts. Organizers can inspect where potential buyers drop off:

1. Applied in Cart Buyer entered code in cart and saw discount.

2. STK Pushed Buyer initiated checkout; phone prompted for PIN.

3. Ticket Paid Payment cleared; ticket issued & commission attributed.

Reviewing Invoices & Archiving PDF Receipts

When a promoter raises an invoice, it appears under ?tab=promoters&sub=invoices with status Pending.

Inspect Details: Click to view the promoter's chosen payment channel (e.g. M-Pesa Send Money number, Till, or Bank account).
Transfer Funds: Send the requested KES amount using your business M-Pesa app or bank portal.
Receipt Generation: Once the promoter marks the invoice as Paid in their portal, the status updates to Paid and an immutable Official PDF Transaction Receipt becomes downloadable for your bookkeeping and tax audits.

WORKED EXAMPLES

14.3 Three Practical Real-World Scenarios

SCENARIO A

Campus Ambassador Promo

A university student promotes the campus music festival to classmates.

Ticket Tier: Regular (KES 800)
Promo Code: CAMPUS50
Buyer Discount: KES 50 (pays KES 750)
Promoter Commission: KES 50
Sales Cap: 200 tickets
Promoter Payout: M-Pesa Send Money

SCENARIO B

Celebrity Resident DJ

Headline DJ promotes VIP Lounges and Table Packages on Instagram.

Ticket Tier: VIP Table (KES 15,000)
Promo Code: DJHYPEMC
Buyer Discount: KES 1,000 (pays KES 14,000)
Promoter Commission: KES 1,500 per table
Sales Cap: 20 tables
Promoter Payout: Bank Wire Transfer

SCENARIO C

24-Hour In-House Flash Sale

Organizer runs their own social media ad without an external promoter.

Ticket Tier: Early Bird (KES 500)
Promo Code: FLASH100
Buyer Discount: KES 100 (pays KES 400)
Promoter Commission: KES 0 (unassigned)
Expiry Rule: Date cutoff (24 hours)
Per-Phone Limit: 2 tickets per phone

FAQ & TROUBLESHOOTING

14.4 Frequently Asked Questions for Promoters & Organizers

Referral links fail frequently in mobile environments: in-app browsers (like Instagram and TikTok) strip cookies, buyers switch devices between seeing a post and paying, and tracking links get blocked by modern ad-blockers and iOS privacy protections. Promo Codes are 100% immune to tracking loss because the buyer explicitly types the uppercase code at checkout to get their cash discount.

Yes. If a promoter requests KES 10,000 but the organizer sends KES 5,000, the promoter can click Mark as Partially Paid and record KES 5,000. The invoice status reflects partial settlement, the remaining KES 5,000 stays active, and an interim receipt is generated.

The system records an stk_pushed attempt in the funnel telemetry logs, but does NOT credit commission or deduct sales cap quotas. Commission is only credited when the payment successfully clears into paid status.

Yes. If the cash discount equals the package price, the cart total becomes KES 0.00. The system automatically bypasses the M-Pesa STK push, instantly issues the QR ticket, sends SMS/email passes, and deducts the organizer's base credit allowance (2 credits).

PERMISSIONS MATRIX

14.5 Organizer vs Promoter Operational Responsibilities

Clear demarcation of roles ensures smooth operations, financial transparency, and fast issue resolution:

Action / Operational Feature	Event Organizer	Event Promoter	Primary Portal
Self-Registration & Profile Setup	Organizer Sign Up	Yes (Free Public Link)	`promoter_register.php`
Create Promo Codes & Uppercase Strings	Full Control	View Assigned Only	`admin/?tab=promoters`
Configure Flat KES Discounts & Commissions	Full Control	Read-Only	`admin/?tab=promoters`
Set Budget Caps, Expirations & Per-Phone Limits	Full Control	Read-Only	`admin/?tab=promoters`
Real-Time Ticket Sales & Revenue Telemetry	All Event Campaigns	Personal Code Only	Both Portals
Generate Commission Invoices & Pick Payout Rail	Receive & Review	Initiates Invoice	`promoter_portal/`
Execute Direct External Payment (Off-Platform)	Executes Payment	Receives Funds	Bank / M-Pesa App
Acknowledge Payment & Issue Official PDF Receipt	Downloads Receipt	Marks Paid & Generates	`promoter_portal/`

DIAGNOSTICS MATRIX

14.6 Common Promo Code Checkout Errors & Solutions

When attendees encounter promo code validation errors during checkout, use this reference matrix to quickly diagnose and resolve the issue:

Error Message On Screen	Root Cause	Organizer Fix (Dashboard)	Promoter / Buyer Action
`Code has expired`	The promotional campaign cutoff date/time has passed.	Edit promo code in `?tab=promoters` and extend the expiration date/time.	Promoter contacts organizer to request campaign extension.
`Usage limit reached`	The maximum total ticket redemption quota set by organizer is exhausted.	Increase the Max Total Redemptions limit in promo code settings.	Promoter celebrates reaching target and requests additional ticket allocation.
`Phone limit exceeded`	The buyer's phone number has already used this code the maximum allowed times.	Adjust Max Per Phone setting if bulk purchases are permitted.	Buyer must complete checkout without promo or use alternate ticket tier.
`Code not valid for tier`	Buyer added a tier that does not have a discount allocated in this campaign.	Check eligible tiers in modal; assign flat KES cash discount to selected tier.	Promoter advises buyers on specifically which ticket packages the discount applies to.
`Invalid promo code`	Typo entered by buyer, or promo code is paused / archived by organizer.	Verify promo code exists and status is set to Active.	Buyer checks spelling. (Note: codes are case-insensitive and whitespace-trimmed).

Quick Access Links

• Promoter Public Login: promoter_login.php
• Promoter Registration: promoter_register.php
• Organizer Promoters Dashboard: admin/index.php?tab=promoters

Infrastructure Security & Compliance

15. Security Hardening, Directory Browsing Shield & Error Protocols

To protect customer privacy, proprietary financial records, and ticket integrity, Eldoret Sherehe enforces multi-layered defense-in-depth across the web server, application runtime, and database tiers. This section documents our directory lockdown, file upload protections, custom error routing, and OWASP Top 10 penetration-testing safeguards.

Zero Directory Browsing Options -Indexes prevents web visitors from inspecting folder contents.

Direct PDF Access Blocked uploads/tickets/ is denied via Apache 2.4/2.2 rules and index 403 guards.

PHP Engine Banned in Uploads php_flag engine off completely neutralizes executable web shells.

Multi-Code Error Engine Dedicated modern error UI for 400, 401, 403, 404, 405, 500, 502, and 503.

DIRECTORY LOCKDOWN

15.1 Why Tickets Cannot Be Browsed or Scraped Directly

Previously, visiting eldoretsherehe.com/uploads/tickets/ without an active index file allowed web visitors to browse and download ticket PDFs. The system now enforces a Triple-Layer Access Barrier:

Defense Layer	Mechanism	Protection Effect
Master `.htaccess`	`RewriteRule ^uploads/tickets(/.*)?$ - [F,L]`	Intercepts URL requests at the Apache server level and immediately responds with `403 Forbidden` before hitting disk.
Folder `.htaccess`	`Require all denied` & `Deny from all`	Hardware/server-level file access denial matching both Apache 2.4 and Apache 2.2 syntax.
Directory `index.php`	`http_response_code(403); header("Location: /error.php?code=403");`	Fallback PHP script redirection guaranteeing a styled 403 landing page even on non-Apache environments (Nginx/LiteSpeed).

How Tickets Are Officially Downloaded: All valid tickets are generated dynamically and delivered on-the-fly through download.php?code=XXXXX. The endpoint verifies that the 5-character alphanumeric ticket code is registered in MySQL, belongs to an active event, and holds a confirmed payment status before streaming the PDF binary.

SECURITY DIRECTIVES

15.2 Protected Directories & Sensitive File Filters

Fully Restricted Directories (Web Access Denied)

/uploads/tickets/ — PDF ticket cache
/uploads/promoter_invoices/ — Promoter commission invoices
/uploads/promoter_receipts/ — Payment receipts
/vendor/ — Composer dependencies and library internals
/scratch/ — Temporary testing scripts and data files
/.git/ — Git metadata, commits, and branch history

Blocked File Extensions (Direct Download Forbidden)

.log | .sql | .bak | .backup | .ini | .conf | .sh | .env | .json | .lock | .md | .zip | .tar | .gz

Protects log files (e.g., mpesa_log.txt, email_error.log), database exports, environment configurations, and server configuration files (php.ini) from public exposure.

ERROR RECOVERY

15.3 Unified Multi-Code Error Engine (`error.php`)

The platform utilizes a centralized, modern error interface configured via Apache ErrorDocument directives. It automatically intercepts HTTP status codes and delivers branded user recovery options:

HTTP 400 Bad Request Malformed parameters

HTTP 401 Unauthorized Login required

HTTP 403 Forbidden Restricted resource

HTTP 404 Not Found Missing page or route

HTTP 405 Method Not Allowed Invalid HTTP verb

HTTP 500 Server Error Internal execution issue

HTTP 502 Bad Gateway Upstream bridge failure

HTTP 503 Unavailable Maintenance / capacity

Incident Telemetry: Every error page generates a unique Incident Reference Code (e.g. INC-403-1760619200) and instructs search engine web crawlers not to index the error page (X-Robots-Tag: noindex, nofollow).

PENTEST READINESS

15.4 OWASP Top 10 Security Hardening Matrix

Summary of security controls audited and implemented prior to third-party vulnerability assessment:

OWASP Category	Mitigated Vulnerability	Enforced Protection in Eldoret Sherehe
A01: Broken Access Control	IDOR & Unauthenticated File Access	Multi-tenant checks (`organizer_id` & `vendor_id` ownership verification), strictly required superadmin session in `setup_db.php` & `sync_repair.php`, and 403 access barriers on upload directories.
A02: Cryptographic Failures	Data Leakage & Plaintext Secrets	Database exception messages masked in production (no credentials in `die()` output), password hashing using `PASSWORD_DEFAULT` (bcrypt), and secure HTTPS headers.
A03: Injection	SQL Injection (SQLi)	100% of dynamic queries use PDO prepared statements with bounded parameters (`?` or `:name`). Raw string concatenations eliminated.
A04: Insecure Design	Arbitrary File Upload & Shell Execution	Multi-stage upload validation in `admin/index.php`: whitelisted extensions, `mime_content_type()`, binary `getimagesize()` check, cryptographically unguessable filenames, and `php_flag engine off` in upload folders.
A05: Security Misconfiguration	Directory Browsing & Verbose Errors	`Options -Indexes` enforced globally, `ini_set('display_errors', 0)` set in all production endpoints, sensitive dot-files and backup archives blocked.
A07: Identification & Auth	Brute Force & Session Hijacking	Timezone-immune OTP verification, rate-limiting on redemption, session regeneration on login, and strict role segregation.