A mobile-first delivery application designed to eliminate cash handling risks by integrating QRPH (InstaPay/GCash/Maya) payments directly into the rider's workflow.
This application was built in less than 24 hours during the Build and Ship Philippines Hackathon. It successfully won the Bounty challenge by solving a critical logistics problem: removing the need for riders to carry large amounts of cash. The app coordinates order verification, real-time QRPH payments via PayRex, and proof of delivery in a seamless flow.
View Live Demo
(Replace this line with a link to your demo video or a GIF of the app flow)
- Framework: Next.js 16 (App Router)
- Database & Realtime: Supabase (PostgreSQL)
- Payments: PayRex API (QRPH Integration)
- Styling: Tailwind CSS & [shadcn/ui](https://ui.shadcn.com/ for the base)
- Deployment: Vercel
- Utilities:
bwip-js(Barcode Generation),html5-qrcode(Scanner),leaflet(Maps Integration),webauthn(Biometrics Integration)
- Mobile-First Design (Optimized for one-handed usage)
- Role-Based Auth (Admin Dashboard vs. Rider Interface)
- Order Queue (View pending deliveries with COD amounts)
- Barcode Verification (Scan package to confirm correct order)
- Dynamic QRPH Generation (Generate exact amount QR via PayRex)
- Real-time Status Updates (Supabase Realtime syncing)
- Cash Fallback (Toggle between Cash and QRPH)
- Proof of Delivery (Photo capture & upload)
- Settlement Dashboard (Track daily earnings & payment splits)
- Dynamic QR Integration (Basic generation implemented)
- Row Level Security (RLS) (Disabled for hackathon speed)
- PayRex Webhook Signature Verification (Skipped for simpler implementation)
- Complex QR Expiry/Regeneration Logic (Basic flow only)
- Database & Auth First: Started by implementing the Supabase database schema and configuring Authentication to distinguish between "Admin" and "Rider" roles.
- Core Logic: Built the state machine for orders (
Pending→En Route→Arrived→Completed) and the barcode scanning verification system. - Payment Integration: Tackled the PayRex API documentation to generate static QR codes, and setting up the webhooks needed to accept the transaction.
- MVP Implementation: Connected the frontend to the backend, ensuring the Rider app updates instantly when an Admin creates an order.
- Bonus Features: Implemented some of the features in the bonus points tab in the bounty, like the biometrics.
- Rapid Prototyping: How to leverage Next.js and Vercel to ship a full-stack app in under 24 hours.
- Supabase Realtime: Utilizing Postgres changes to push instant updates to the rider's screen without refreshing.
- PayRex API: Understanding the flow of QRPH generation and webhook handling for cashless payments.
- Mobile UX: Designing strictly for mobile constraints (thumb zones, large buttons).
- Security: RLS (Row Level Security) was disabled on Supabase tables to speed up development. In a production environment, strict policies must be enabled to prevent unauthorized data access.
- Error Handling: Better handling for network dropouts during image uploads.
- Webhook Security: Implementing strict signature verification for PayRex webhooks to prevent spoofing.
Follow these steps to deploy the application and set up the necessary services.
Ensure you have accounts for the following services:
- Create a new project in Supabase.
- Database: Go to the SQL Editor and import/run the
database.sqlscript (orschema.sql) provided in this repository. - Authentication: Go to Authentication > Providers > Email and Disable "Confirm email" (for faster testing).
- Security: Disable RLS (Row Level Security) for all tables.
- Realtime: Go to Database > Replication and Enable Realtime for the
ordersanduserstables. - Buckets: create delivery-photos bucket at the storage tab.
- Log in to your PayRex account.
- Create a Static QRPH.
- Edit the image to contain only the QR code itself.
- Save this image as
static-qrph.pngand place it in thepublic/folder of your cloned project (or upload it to a public URL).
- Fork or Clone this repository to your GitHub.
- Log in to Vercel and Add New Project.
- Select your repository and choose the Next.js framework.
- Add the following vercel Environment Variables before deploying:
NEXT_PUBLIC_SUPABASE_URL=[Your Supabase Project URL]
NEXT_PUBLIC_SUPABASE_ANON_KEY=[Your Supabase Anon API Key]
PAYREX_API_KEY=[Your PayRex Secret API Key]
STATIC_QRPH_IMAGE_URL=/static-qrph.pngOnce Vercel generates your live domain (e.g., cod.vercel.app), go to Settings > Environment Variables in Vercel and add the following:
# Your Vercel domain WITHOUT https:// (e.g., cod.vercel.app)
NEXT_PUBLIC_WEBAUTHN_RP_ID=your-project.vercel.app
# Your Vercel domain WITH https:// (e.g., https://cod.vercel.app)
NEXT_PUBLIC_APP_URL=https://your-project.vercel.app-
Go to your PayRex Dashboard > Webhooks.
-
Add a new webhook endpoint using your Vercel domain:
https://<YOUR_VERCEL_DOMAIN>/api/webhooks/payrex
(Example:
https://cod.vercel.app/api/webhooks/payrex) -
Under the events list, check the box for:
payment_intent.succeeded
- Navigate to your deployed Vercel URL.
- Click the Register button at the bottom of the login screen.
- Create the following accounts (you can optionally add biometrics or skip):
- Admin Account:
admin@agartha.ph - Rider Account:
rider@agartha.ph
- Admin Account:
After creating the users in the app, you need to manually elevate the admin user's role in the database.
- Go to your Supabase Dashboard > SQL Editor.
- Paste and run the following script:
-- Update the user role to 'admin'
UPDATE public.users
SET role = 'admin', full_name = 'Admin User'
WHERE email = 'admin@agartha.ph';