GatePass — Event Tickets & QR Check-in for WooCommerce

Sell event tickets through WooCommerce. Every paid attendee receives a unique ticket ID and a cryptographically-random QR code by email (HTML + PDF), visible in My Account → My Tickets. Staff check people in with a mobile scanner; every QR is validated server-side, once, even when several gates scan the same code at the same instant.

The plugin lives in gatepass/. Zip that folder to install.

Table of contents

1. Requirements
2. Installation
3. Five-minute setup
4. How the lifecycle works
5. Admin screens
6. Shortcodes & URLs
7. Staff roles
8. Scanner
9. Refunds, cancellations, resends
10. Security model
11. Database
12. Testing report
13. Known limitations
14. Roadmap
15. Troubleshooting

Requirements

No Composer dependencies. QR and PDF generation are implemented in-plugin (no external services, nothing leaves your server).

Installation

1. Download / zip the gatepass directory.
2. Plugins → Add New → Upload Plugin → activate. (Requires WooCommerce active; the plugin refuses to boot otherwise.)
3. Activation creates 5 tables (see Database), two roles (Event Ticket Staff, Event Manager), grants all gatepass_* capabilities to Administrators, and schedules an hourly ticket-expiry cron.
4. Go to Tickets → Settings and set organizer name, support email and brand colours.

Deactivation keeps all data. Uninstall keeps all data unless you tick Delete ALL ticket data when the plugin is uninstalled in Settings.

Five-minute setup

1. Tickets → Events → Add event — name, ticket-ID prefix (e.g. GRB → GRB-2026-000123), date, venue, capacity, banner.
2. Tickets → Ticket Types → Add ticket type — pick the event, name (Regular / VIP / Family…), price, quantity, people per ticket, early-bird price + quantity + window, per-customer max, validity window, features, terms, custom attendee fields. Saving creates (or updates) a virtual WooCommerce product with stock management enabled. You can also link an existing product by ID.
3. Put [gatepass_events] on a page (or just sell the WooCommerce product normally).
4. Tickets → Staff — create scanner accounts. Give staff the scanner URL: Tickets → Scanner in wp-admin or a page containing [gatepass_scanner].
5. Do one test purchase. Check Tickets → All Tickets, the email, the PDF, then scan it.

How the lifecycle works

Admin creates Event  →  Admin creates Ticket Type  →  WooCommerce product synced
  →  Customer buys (cart/checkout/payment: 100% WooCommerce)
  →  Order reaches Processing/Completed (configurable)
  →  gp_tickets rows created (one per attendee, or one per group ticket)
  →  128-bit random token + human ticket ID per row
  →  QR = https://site/?gp_verify=<token>   (no personal data in the QR)
  →  Email (HTML + PDF attachment), email_status recorded
  →  Customer sees tickets in My Account → My Tickets (QR, PDF, status)
  →  Staff scans → POST /wp-json/gatepass/v1/check-in
  →  Atomic UPDATE … WHERE status='active'  →  exactly one scan wins
  →  Ticket = Used; every attempt logged in gp_checkins
  →  Refund / cancel → tickets Refunded / Cancelled → QR rejected
  →  Admin sees everything in All Tickets → ticket detail (scan log + history)

Idempotency. Generation runs under a MySQL GET_LOCK('gatepass_gen_<order_id>') and compares existing rows per order item against the paid quantity, so duplicate webhooks, page refreshes, or processing → completed transitions never create duplicates.

Early bird. Price is decided server-side when the item is added to the cart and re-asserted on every cart calculation (woocommerce_before_calculate_totals), using sold + early_qty and the date window. Add-to-cart validation blocks quantities beyond remaining inventory, event capacity, or per-customer limits (counted across previous paid orders for logged-in users / same billing email).

Group tickets. Ticket type option One QR admits the whole group (one row, people = N, optional partial check-in 2/4 → 4/4) or One QR per person (N rows).

Admin screens

WooCommerce integration points: product edit screen gets a Ticket tab (links to type), order edit screen lists the order's tickets, My Account gets a My Tickets endpoint, order emails/thank-you page list ticket IDs.

Shortcodes & URLs

Staff roles

Staff never see full phone numbers in scan responses (masked), never see payment data.

Scanner

• Works in any modern mobile browser over HTTPS (Safari iOS 14.3+, Chrome Android). Uses html5-qrcode.
• Asks for camera permission, prefers the rear camera, lets you flip cameras.
• Continuous scanning; the same code is debounced for 4 s so a lingering QR doesn't spam the server.
• Big ENTRY APPROVED (green) / ENTRY DENIED (red) panel with reason (already used at 19:42 by Priya, refunded, not valid yet, wrong event), attendee, ticket type, admits N.
• Sound + vibration, configurable auto-"scan next" countdown.
• Manual lookup (ticket ID, order #, phone, email) with one-tap check-in as fallback for damaged screens / dead phones.
• Live counters: today's check-ins, people inside, sold, rejected.
• Offline: shows a red banner and refuses to validate. Offline validation is intentionally not supported — a single source of truth is what makes one-time QR enforceable across gates.

Refunds, cancellations, resends

Security model

• Tokens: random_bytes(16) → 32 hex chars (128 bits). Ticket IDs are separate, human-readable, and cannot be used to check in from the public page — only staff endpoints accept them.
• QR payload contains only the verify URL. No name, email, phone, order or payment data.
• One-time use: a single UPDATE … WHERE id=? AND status='active' AND checked_in_count + ? <= people; rows_affected decides the winner. No read-then-write race.
• REST: cookie auth + X-WP-Nonce, current_user_can('gatepass_scan'), per-user and per-IP rate limits (transients), IP + UA logged on each attempt.
• All admin mutations via admin-post.php with check_admin_referer + capability checks; all SQL via $wpdb->prepare; all output escaped.
• Public verify page returns only status + event name + admits count; it never mutates.
• Screenshots: a static QR cannot stop a screenshot. It can guarantee the screenshot only works once — the first scan wins, the ticket owner's second scan is rejected and staff see who scanned first and when. For higher-risk events pair with ID checks or enable per-person QRs.

Database

Schema is versioned (gatepass_db_version) and upgraded with dbDelta on load. Orders are only ever accessed through wc_get_order() / WC_Order CRUD — HPOS safe.

Testing report

Run php tests/run.php (no WordPress needed). Current result: 28 passed, 0 failed.

Behaviours verified by code review / design (require a live WooCommerce install to exercise end-to-end):

Not yet exercised in a live store in this iteration: WooCommerce Blocks checkout attendee-field capture (classic checkout fields are used; Blocks users get attendee names from billing details), real SMTP delivery, and a physical-camera scan. See Known limitations.

Known limitations

• Static QR. The QR is fixed per ticket. One-time use is guaranteed server-side; screenshot prevention is not possible with any static QR. Dynamic/rotating QR (P2) needs a customer-side app or logged-in wallet page with a signed, time-limited token.
• Offline scanning is intentionally unsupported (see Scanner).
• Attendee fields on Blocks checkout. Custom per-attendee fields are collected on the product page. If you use the Checkout Block, per-attendee capture at checkout is not injected; names default to the billing name and can be edited by admin.
• Seating, affiliates, WhatsApp/SMS, CRM sync are not included (P2).
• PDF fonts are core Helvetica (Latin-1). Non-Latin attendee names render in the HTML email and web wallet correctly but may show as ? in the PDF.
• Refund partial-quantity mapping voids the most recent unused tickets for that line item; it cannot know which specific attendee the refund was for.

Roadmap

P1 (next): attendee fields in Checkout Block via the Additional Fields API · per-event staff assignment · Apple/Google Wallet passes · WhatsApp/SMS delivery (Twilio) · bulk ticket import · seating charts. P2: rotating QR in the customer wallet page · offline PWA with signed manifests and conflict resolution · device fingerprint anti-fraud · affiliate tracking via WooCommerce coupons · analytics dashboards.

Troubleshooting