Developer

API Reference

Complete endpoint reference for the Waste Warriors REST API.

Base URL

https://api.wastewarrior.co.ke/api

Auth

Bearer token (Laravel Sanctum)

Format

JSON — application/json

🔐 Auth

POST	/auth/register	Register a new user (producer or recycler)
POST	/auth/login	Login and receive a Sanctum token
POST	/auth/logout	Revoke current token
GET	/auth/me	Get authenticated user profile
POST	/auth/fcm-token	Register FCM push token

🏭 Producer — Pickups

GET	/producer/pickups	List own pickup requests (paginated)
POST	/producer/pickups	Create a new pickup request
GET	/producer/pickups/{id}	Get pickup detail
PUT	/producer/pickups/{id}	Update a pending pickup
POST	/producer/pickups/{id}/cancel	Cancel a pickup
POST	/producer/pickups/{id}/pay	Pay for a completed pickup

♻ Recycler — Pickups

GET	/recycler/pickups	List available and assigned pickups
GET	/recycler/pickups/{id}	Get pickup detail
POST	/recycler/pickups/{id}/accept	Accept a pickup request
POST	/recycler/pickups/{id}/start	Mark as in-progress
POST	/recycler/pickups/{id}/complete	Mark as completed
POST	/recycler/pickups/{id}/cancel	Cancel an accepted pickup

💳 Payments & Wallet

GET	/wallet/balance	Get wallet balance
GET	/wallet/transactions	List transactions (paginated)
POST	/wallet/transfer	Transfer balance to another user
POST	/mpesa/stk/topup	Initiate STK Push top-up
POST	/mpesa/stk/pickup/{id}	Initiate STK Push for pickup payment
GET	/mpesa/stk/{checkoutId}/status	Poll STK Push payment status
POST	/mpesa/withdraw	Request B2C payout to M-Pesa

📍 Location & Tracking

POST	/pickups/{id}/location	Push GPS position (recycler)
GET	/pickups/{id}/location/current	Get latest recycler position (producer)
GET	/pickups/{id}/location/trail	Get location trail (up to 200 points)

👥 Sub-Users (Recycler)

GET	/recycler/sub-users	List team members
POST	/recycler/sub-users	Add a team member
PUT	/recycler/sub-users/{id}	Update team member
DELETE	/recycler/sub-users/{id}	Remove team member

🛠 Admin

GET	/admin/users	List all users (paginated, filterable)
GET	/admin/users/{id}	Get user detail
POST	/admin/users/{id}/toggle-payment	Toggle payment permission
POST	/admin/users/{id}/toggle-receive	Toggle receive permission
POST	/admin/users/{id}/status	Update user status
GET	/admin/settings	List platform settings
PUT	/admin/settings/{key}	Update a platform setting
GET	/admin/analytics/overview	Platform analytics overview
GET	/admin/analytics/financials	Financial analytics

🔔 M-Pesa Callbacks (Public)

POST	/mpesa/stk/callback	STK Push result callback (Safaricom)
POST	/mpesa/c2b/validation	C2B payment validation
POST	/mpesa/c2b/confirmation	C2B payment confirmation
POST	/mpesa/b2c/result	B2C result callback
POST	/mpesa/b2c/timeout	B2C timeout callback

Need more detail?

Check the full docs for request/response examples, error handling, and webhook setup.

Read the Docs →