​

Business rules

Business rules define the operational policies the platform enforces regardless of which feature delivers them. Every rule listed here has a direct implementation in the codebase.

​

Guide onboarding

1. KYC required before publishing. A guide must complete KYC (Know Your Customer) verification before any of their packages can be submitted for approval or made visible to travelers. The kyc middleware in web.php enforces this gate on all package and booking management routes.
2. Document review. An admin must review and approve the submitted identity documents. The guide receives a notification when their status changes.
3. Status history retained. All KYC submission attempts and admin decisions are stored so that disputes can be audited.
4. Additional documents may be requested. An admin can request supplementary documentation before approving an application.
5. Minimum experience. Guides must have at least 6 months of professional experience and hold a valid tour guide license.

​

Package approval workflow

Packages move through the following states: Additional package rules:

• Guides may not publish packages until KYC is approved.
• All tour descriptions must be accurate; misleading content is grounds for suspension.
• Package images must be real photos from the actual tour — stock imagery is prohibited.
• All fees must be disclosed in the package listing; no hidden charges are permitted.
• Complete safety information must be included for any package involving physical activity.

​

Booking lifecycle

Bookings move through the following status values, stored as integers in the bookings table:

​

State transition rules

• Advance booking: Travelers must book at least 24 hours before the tour date.
• Guide confirmation: After payment, the guide must accept or reject the booking. A time limit applies; if the guide does not respond, the system triggers an automatic action.
• Rejection refund: If the guide rejects a booking, a refund is automatically initiated.
• Cancellation window: Travelers may cancel up to 48 hours before the tour date without penalty. The cancellation route is POST /api/v1/bookings/{uid}/cancel.
• Modification window: Booking modifications are allowed up to 24 hours before the tour.
• Stale booking pruning: Unpaid bookings (status 0) with a tour date 5 or more days in the past are automatically deleted by the Booking::prunable() method. This frees capacity and keeps the table clean.
• Double-booking prevention: The system checks total confirmed participants per date against the package’s maximumTravelers value. Dates at capacity are marked unavailable in the booking calendar. The GET /api/v1/bookings/availability endpoint exposes this check publicly.
• Booking reference: Each booking is assigned a non-guessable transaction ID in the format BK-XXXXXXXXXXXXXXXX (16 random hex characters), generated via random_bytes(8) to prevent enumeration attacks.

​

Payment and payout rules

​

Traveler payment

• Payment is required at the time of booking. Unpaid bookings expire after 5 days.
• Payment must be completed within 2 hours of booking confirmation to secure the slot.
• Multiple payment gateways are available; the traveler selects one at checkout.
• Currency conversion uses real-time market rates.
• Payment submission is throttled to 10 requests per minute per session to prevent double-submission.

​

Platform commission

• The platform charges a commission of 10–15% per booking, determined by the guide’s subscription tier.
• Commission rates are configurable by admins.
• All gateway processing fees are disclosed to the traveler before payment is confirmed.

​

Guide payouts

• Guides request payouts from their earnings dashboard. Supported payout methods include Flutterwave, Paystack, and bank transfer.
• Payout requests are processed according to the configured payout schedule.
• Refund processing takes 5–7 business days.
• Guides can check payout limits and supported currencies before submitting a request.

​

Refunds

• Cancellations within the policy window trigger automatic refunds.
• Guide-rejected bookings are refunded automatically.
• Weather-related cancellations are eligible for refund subject to admin review.

​

Review eligibility

1. Completed booking required. You can only leave a review if you have a booking in status 1 (confirmed/paid) or 2 (completed) for the package. This is enforced by User::forReviewBooking(), which scopes to status IN (1, 2).
2. No duplicate reviews. The system prevents a user from submitting more than one review per booking.
3. Content standards. Reviews must follow community guidelines; inappropriate content is flagged for moderation.
4. Guide replies. Guides may post a single reply to each review on their packages.
5. Admin moderation. Admins may remove reviews that violate guidelines. Only reviews with status = 1 are displayed publicly on package pages.
6. Review display. Reviews are shown on the package detail page, sorted by date. Only top-level reviews (those with parent_review_id = null) are displayed; guide replies are nested.

​

Coupon and discount rules

• Coupon codes are managed by admins and can be applied at checkout via POST /coupon/check.
• A coupon code must not appear in browser history or server logs; the route is POST-only.
• Discounts are applied to the booking subtotal before payment is processed.
• Guides can also apply a per-package discount via POST /user/package/{id}/discount.
• The system validates coupon eligibility (expiry, usage limits, applicable packages) before applying any reduction.

​

Subscription plans for guides

• Guides must hold an active subscription plan to list packages and receive bookings.
• Plans are tiered; higher tiers provide lower commission rates and higher listing limits.
• An active plan must have status = 1 and an expiry_date in the future. The User::activePlan() relationship enforces both conditions.
• Guides can enable auto-renew (POST /user/plan/renew) to avoid service interruption.
• Expired plans prevent new package submissions until the guide purchases or renews a plan.
• Admins configure available plan tiers, pricing, and associated limits from the admin dashboard.

​

Geographic and regulatory rules

• The platform operates primarily within the African continent.
• Guides must comply with the local tourism regulations of their operating region.
• Tax collection and remittance follow the applicable local laws for each jurisdiction.
• International travelers are supported; the checkout flow adapts currency and payment options based on the traveler’s location.