Rebuild a multi-tenant SaaS gift-voucher platform — TypeScript / Next.js / Supabase — production-ready, QA included

We operate a SaaS gift-voucher platform used by hospitality businesses (hotels, restaurants, spas) . Merchants use it to sell, issue, redeem, track and reconcile gift vouchers — online through an embedded sales page, through an admin portal, and through an API used by POS / PMS / spa systems.

We are rebuilding the platform from the ground up on a modern, consolidated stack. This is a defined-scope, production-ready build — not a prototype. Automated tests are expected alongside each module, not retro-fitted at the end. This is a focused, well-specified project rather than a sprawling one.

A full written specification will be available to shortlisted bidders under NDA. This brief contains everything needed to scope and quote.

2. What we need built (Phase 1 scope)

- **Business & user setup** — multi-tenant accounts, portal users, role-based permissions. Onboarding is staff-managed (no self-service signup in Phase 1).
- **Public online voucher sales** — a single hosted, business-branded sales page embedded by **iframe** on merchant websites. Multiple voucher products per business; preset and custom-amount vouchers; a basket allowing multiple vouchers (each with its own recipient) in one order.
- **Hosted payment flow** — card payment via a hosted payment page so we never handle cardholder data. Each merchant uses their own payment account. Vouchers are issued only after **server-side webhook verification** (browser return is never trusted as proof of payment). All webhook handling must be idempotent.
- **Portal voucher sale & complimentary issue** — staff sell vouchers (same payment flow) or issue complimentary vouchers (permission-controlled, audit-logged).
- **API: sale, balance check, redemption** — for POS / PMS / spa integrations. API sale can create a new voucher **or add value to an existing voucher/card** (supports reusable physical cards). All financial API calls require an external reference for idempotency.
- **Redemption** — manual portal redemption (typed code, alias, or QR/barcode scan) and API redemption. **Partial redemption supported; over-redemption must always be rejected, including under concurrent requests.**
- **Voucher ledger** — an append-only transaction ledger is the source of truth for balances. Current balance is stored for speed but must always be reconstructable from the ledger.
- **Expiry policy** — configurable per business and per product, with strict or flexible enforcement. Expiry must respect the statutory minimum-validity floor for the merchant's jurisdiction (Ireland: 5-year/60-month minimum under the Consumer Protection (Gift Vouchers) Act 2019).
- **Cancellation** — administrative, reason-required, audit-logged; prevents future redemption; does not call the payment provider.
- **Email fulfilment** — transactional emails (purchaser confirmation, recipient voucher with code + QR, business copy). One well-designed HTML template with merchant-configurable logo, colours, header/footer and terms. A fulfilment queue with retry, failure logging and manual resend.
- **Voucher search & detail** — strong search; detail view showing order/payment data, full ledger, fulfilment and redemption history, and audit log.
- **Import of existing vouchers** — CSV/Excel import of **active balances only** (no historical transaction migration), with validation, preview and approval before activation.
- **Reporting & reconciliation** — voucher liability, sales, redemptions, payment reconciliation, complimentary, imported, cancelled, expired, email fulfilment, API activity, audit log. Exportable to CSV/Excel.
- **API key management** — multiple named API keys per business, each individually scoped, rotatable and revocable, with usage tracking. Raw key shown once; stored only as a secure hash.
- **Security & multi-tenant isolation** — role-based access, full audit logging, and database-level per-tenant isolation (PostgreSQL Row-Level Security) as defence-in-depth beneath application authorisation.

. Required stack

- **Language:** TypeScript end-to-end
- **Framework:** Next.js (App Router)
- **Database:** PostgreSQL via Supabase, with Row-Level Security
- **Auth:** Supabase Auth (portal users only — public buyers do not authenticate)
- **Hosting:** Vercel
- **Object storage:** Supabase Storage
- **Payments:** Paynt, via hosted payment pages, we will provide API documentation.— but built behind a **thin payment-provider adapter** so the provider can be swapped later as configuration, not a re-integration
- **Email:** Resend (or equivalent transactional provider)
- **Edge/DNS/WAF:** Cloudflare (already in place)
- **Error tracking:** Sentry

We have deliberately chosen a serverless architecture for reliability (no single long-lived app server as a point of failure), ownership/control, and a cost profile suited to our seasonal traffic. **If you believe a different approach is strongly justified, you are welcome to propose it — but please quote the required stack above as your primary bid so we can compare like-for-like, and present any alternative separately with clear reasoning.**

--4. Backward compatibility

The new API should preserve compatibility with our existing v1 API contracts wherever practical, so current POS/PMS/spa integrations keep working at cutover. We will share the v1 API documentation with shortlisted bidders. Any unavoidable deviation must be documented for affected integration partners.

5. Quality & testing (required, not optional)

Automated tests must be written **alongside each module**. At minimum we expect coverage of: no voucher issued before verified payment; duplicate-webhook idempotency; over-redemption rejection under concurrent requests (database row-lock test); API-sale idempotency on repeated external reference; cross-business data isolation (RLS enforced even if application code is bypassed); cancellation prevents redemption; import requires approval before activation; reports reconcile ledger totals to balances.

6. Migration (note in your bid, can be a separate line)

Migration is a separate, controlled, per-merchant activity: export active vouchers, validate in staging, reconcile balances against legacy reports, pilot one merchant, then cut over in controlled batches with the old system kept read-only as fallback. **Only active voucher balances are migrated — not historical transactions.** Our own team will assist with the customer transition (per-merchant data clean-up, comms and scheduling), so you can scope your migration effort on that basis. Migration must not be scheduled across peak (Christmas) trading.

---

7. Timeline

**Speed matters.** We need Phase 1 delivered and a pilot merchant live ASAP. Please state the calendar you can commit to and the team size behind it and confirm earliest start

8. What to include in your bid

1. Relevant experience — particularly multi-tenant SaaS, payment/webhook integrations, ledger-based financial systems, and the stack above. Links to comparable work.
2. Your **Phase 1 estimate** (effort and price) and proposed **payment milestones**. We prefer fixed-price-per-phase tied to milestone acceptance.
3. Proposed **calendar and team size**, with earliest start date.
4. Your approach to **concurrency/over-redemption safety** and **payment-webhook idempotency** — these are the parts that must be right.
5. How you handle **automated testing** within the build.
6. Any alternative stack proposal (optional, separate from your primary like-for-like bid).
7. Any clarifying questions.

We will assess bids on capability, approach, testing discipline, timeline and value — not lowest price alone. A full specification and the v1 API documentation are available to shortlisted bidders under NDA.
Automated responses will be immediately deleted. Show More