Flow: Physical Sales at Petrol Station (PIN-Based System)¶

Actor¶

Customer purchasing tickets at Petrol retail location using HNS mobile app PIN

Preconditions¶

Petrol has predefined allocated sectors and total available seats for this match (e.g., 220 seats in D1)
Customer has HNS mobile app installed on their phone
Customer has completed ticket holder details in app BEFORE visiting Petrol station
Sales are open (scheduled sale time has passed, e.g., 12:00)
Customer has Croatian OIB (primary buyer must have OIB)

Flow Steps¶

Part 1: Customer Preparation (In HNS Mobile App - Before Visiting Petrol)¶

Access Petrol Sales Section
- Hidden Section: The Petrol sales section is not visible in the app's standard navigation or match page
- Access Method: Customer scans QR code displayed at Petrol station
- QR code contains deeplink that opens HNS mobile app directly to Petrol purchase flow for current/upcoming match
- If app not installed, deeplink redirects to app store first
- Customer must be logged in to proceed (prompted to log in if not)
- Availability Check on Entry:
  - System checks Petrol allocation availability when page loads
  - If tickets available: Proceed to Step 2
  - If sold out: Display message: "Petrol ticket allocation for this match is sold out. Check the HNS app for other available tickets or try again later."
    - Option to view match in main app (for other sales channels)
    - Option to close
Select Number of Tickets
- Customer selects number of tickets to purchase (1-4)
- Proceed to ticket holder details entry
Per-Ticket Identity Capture
- Important Notice Displayed:
  - System shows information banner: "Email Required: Each ticket will be delivered to the HNS mobile app linked to the email address you provide. All tickets with the same email must enter the stadium together on the same device."
  - Additional note: "If someone doesn't have a mobile phone or email address, use the email of the person who will accompany them and have both tickets on the same device."
- First Ticket (Primary Buyer):
  - Automatically pre-filled with customer's default profile (logged-in user)
  - Customer is the primary ticket holder - they must purchase at least one ticket for themselves
  - Customer can edit details if needed
- Additional Tickets (2-4):
  - For each additional ticket, customer can either:
    - Select from saved profiles: Choose from previously saved profiles (family, friends) in account
    - Enter new details: Manually enter name, date of birth, nationality, OIB (for Croatians) or passport (for foreigners), email, phone
  - Option to save new details as profile for future purchases
- Email Field:
  - Email address field visible, by default prefilled with customer's email
  - System validates email format
  - System allows same email for multiple tickets with warning: "These tickets will be on the same device and must enter together"
  - If email left blank: Ticket remains on customer's app - customer must enter stadium together with this ticket holder
  - Note: Email assignment is final and cannot be changed after purchase
- Minor Ticket Holder Restriction:
  - If ticket holder is a minor (under 18 based on date of birth), email field is disabled
  - Info message: "Tickets for minors cannot be assigned to a separate email. Minor must enter with accompanying adult."
  - Ticket remains on customer's app; minor and adult must enter together
- Real-time Validation:
  - Format checks, required fields, OIB checksum validation
  - Blacklist check against HNS security database for all attendees
  - Progress indicator shows completion status (e.g., "2 of 4 tickets completed")
Checkout (Without Payment)
- Customer reviews order summary:
  - Match details (teams, date, venue)
  - Number of tickets
  - Ticket holder details for each ticket
  - Price per ticket and total amount (for reference - payment at Petrol)
- No payment collected at this step - payment will be processed at Petrol station
- Customer confirms details and proceeds to PIN generation
- CTA button: "Generate Petrol PIN"
PIN Generation & Confirmation
- System generates unique purchase PIN
- PIN format: 5-digit numeric only (e.g., "34442")
- PIN is match-specific (different PIN for each match)
- Confirmation Screen displays:
  - PIN displayed prominently: "Your Petrol Purchase PIN: 34442"
  - Match details
  - Number of tickets: X
  - Total amount to pay at Petrol: €XX.XX
  - PIN valid until: [expiration date/time]
- Info text: "Show this PIN to Petrol staff to complete your purchase"
- Instructions: "Visit any Petrol station with HNS ticket sales to complete your purchase"
Access Pending PIN (Return to This Page)
- Customer can return to view their pending Petrol PIN from:
  - "My Tickets" section → "Pending Purchases" tab
  - Shows all active Petrol PINs awaiting completion at Petrol station
- Pending PIN card displays:
  - Match name and date
  - PIN number (tap to reveal/copy)
  - Number of tickets
  - Amount to pay
  - Expiration countdown
  - Status: "Awaiting Petrol Payment"
- Customer can:
  - View full details (same as confirmation screen)
  - Edit ticket holder details (PIN remains valid, data updated)
  - Cancel PIN request (releases the pending request)

Part 2: At Petrol Station¶

Customer Presents PIN
- Customer visits Petrol retail location
- Customer shows PIN on their phone to Petrol POS staff
- Customer shows ID document for identity verification
Staff Enters PIN in Quota Portal
- Petrol staff logs into HNS Quota Web Portal (special "Petrol Role")
- Staff enters the 5-digit PIN in search field
- System validates PIN and checks Petrol allocation availability
- If requested tickets available:
  - System immediately reserves seats for 20 minutes (prevents concurrent sales at other POS locations)
  - Seats assigned using snake algorithm
  - Reservation countdown timer displayed to staff
  - System retrieves and displays customer data:
    - Customer name and details
    - Number of tickets requested
    - Ticket holder details for all tickets
    - Assigned seat numbers
    - Total amount to pay at Petrol: €XX.XX
- If partial availability (e.g., requested 4, only 2 available):
  - Staff informs customer: "Only X tickets available"
  - Options:
    - Customer accepts reduced quantity - system reserves available seats
    - Customer declines - transaction cancelled, no reservation made
  - If accepted, system reserves available seats for 20 minutes
- If no tickets available:
  - System displays: "Petrol allocation sold out"
  - No reservation made, transaction cannot proceed
- Cancel Reservation Option:
  - "Cancel Reservation" button available throughout the process
  - If customer decides not to proceed, staff can immediately release reserved seats
  - Seats return to available inventory for other customers
Staff Verifies Customer Identity
- Staff compares:
  - Customer's face with ID document
  - ID document name with primary ticket holder name in system
- Requirement: Primary buyer must match the person present (no buying for others who aren't present)
- Staff confirms identity match in system
- Note: Reservation timer continues during verification
Payment Processing
- Must complete within 20-minute reservation window
- Customer pays at Petrol register
- Payment processed through Petrol's payment system (external to HNS) — HNS does not collect or route this money. Method (cash/card/voucher) is not tracked by HNS.
- Staff simply marks the reservation as sold in the quota portal (no amount or payment method captured on the HNS side — the Petrol POS is the authoritative record)
- Receipt printed at Petrol POS
- Note on settlement: This is the customer↔Petrol leg only. Petrol settles the quota allocation with HNS separately via deferred payment post-match (see Admin Petrol Setup → Financial Model and Deferred Payment Collection).
Ticket Confirmation and Delivery
- Staff confirms sale in quota portal
- System immediately:
  - Marks tickets as SOLD
  - Assigns tickets to customer's HNS app account
  - Sends confirmation push notification to customer
  - Sends confirmation email with ticket details
- Customer sees tickets appear in "My Tickets" section of HNS app
- QR codes visible according to standard timing rules (5 hours before match)
- Staff provides verbal confirmation: "Your tickets are now in your HNS app"

Alternative Flows¶

A1: Sales Not Yet Open

Customer tries to generate PIN before scheduled sale time (e.g., before 12:00)
App displays message: "Petrol sales open at [time]. Please try again later."
PIN cannot be generated until sale time
Server-side validation prevents early purchases even if client time is manipulated

A2: PIN Not Found / Invalid

Staff enters PIN that doesn't exist or is expired
System displays: "Invalid PIN. Please verify and try again."
Staff asks customer to:
- Check PIN is entered correctly
- Regenerate PIN in app if expired
- Verify they completed ticket holder details

A3: Blacklist Hit

If any ticket holder OIB is blacklisted (detected during PIN generation or at POS)
At PIN generation: App blocks and displays error: "HNS is prevented from selling a ticket to this person pursuant to applicable law. For all information regarding this restriction, please contact MUP (Ministry of Interior)."
At POS: System shows alert to staff: "Unable to process due to security restriction. Direct customer to contact MUP (Ministry of Interior)."
Sale cannot proceed for blacklisted individuals

A4: No More Seats in Petrol Allocation

Petrol quota exhausted
Staff sees "Sold Out" in quota portal
Staff informs customer: "Petrol allocation is sold out"
Customer directed to HNS app or other channels for remaining tickets

A5: Customer Didn't Complete App Setup

Customer arrives at Petrol without generating PIN
Staff explains: "You need to download the HNS app and enter your details first"
Customer scans the displayed QR code at the station (handles both app download and deeplink)
Customer must complete app setup and generate PIN before purchase

A6: Identity Verification Fails

Staff cannot verify customer identity (name mismatch, no valid ID)
Sale cannot proceed
Staff explains requirement: "Primary ticket holder must be present with valid ID"
Customer may return with proper identification

A7: Customer Wants to Modify Ticket Details at POS

Customer realizes error in ticket holder details at Petrol station
Customer must edit details in HNS app
After edit, PIN remains valid (same PIN, updated data)
Staff refreshes/re-enters PIN to see updated details
Proceed with sale

A8: Reservation Timeout (20 Minutes Exceeded)

If payment not completed within 20-minute reservation window
System automatically releases reserved seats back to Petrol allocation
Staff sees "Reservation Expired" message in quota portal
To proceed, staff must re-enter PIN to create new reservation (if seats still available)
Warning displayed at 5 minutes remaining, 1 minute remaining

A9: Payment Fails at Petrol

Petrol payment system declines payment
Staff does not confirm sale in quota portal
Seat reservation remains active until 20-minute timeout
Customer can retry payment within reservation window
If timeout reached, see A8

A10: Staff Cancels Reservation

Customer decides not to proceed with purchase (can't pay, changed mind, etc.)
Staff clicks "Cancel Reservation" button in quota portal
System immediately releases reserved seats back to Petrol allocation
Confirmation message: "Reservation cancelled. Seats released."
Customer's PIN remains valid - can be used again to create new reservation
Staff informs customer: "Your reservation has been cancelled. You can try again later if seats are available."

A11: System Offline / Connection Issues

If Petrol cannot connect to HNS quota portal
Sale cannot proceed (no offline mode for Petrol sales)
Customer directed to try later or use other channels

Technical Requirements¶

Deeplink / QR Code Access:

Petrol sales section is hidden from standard app navigation (no menu item, no visibility on match page)
Access only via deeplink embedded in QR code displayed at Petrol stations
Deeplink format: hns://petrol-sales/{match-id} (or similar)
QR codes are match-specific and generated by HNS admin for Petrol distribution
Deeplink handling: opens app directly to Petrol flow if installed, redirects to app store if not
Universal links support for iOS/Android to handle both scenarios seamlessly

Quota Portal - Petrol Role:

Dedicated login for Petrol staff with restricted permissions
Can only: search by PIN, view customer details, confirm sales, cancel reservations
Cannot: create quotas, modify allocations, view other customers
Activity logging for all actions

PIN Security:

PINs are single-use per transaction (consumed after successful sale)
PIN links to specific customer account and ticket details
PIN expires after use or after match date
Rate limiting on PIN generation (prevent abuse)
PINs cannot be reused across matches
PIN remains valid after cancelled reservation (can create new reservation)

Sale Timing:

Sales open/close times configured per match by admin
Real-time enforcement (no sales outside window)
Countdown/status visible to both customer (app) and staff (portal)

Seat Reservation (Multi-POS Concurrency):

When staff enters PIN, system immediately reserves requested seats for 20 minutes
Reservation prevents concurrent sales at other Petrol POS locations
Reserved seats removed from available inventory across all POS terminals in real-time
Countdown timer displayed to staff in quota portal
Warning notifications at 5 minutes and 1 minute remaining
Automatic release of seats if payment not confirmed within window
Manual release via "Cancel Reservation" button for immediate seat release
Re-entering same PIN after timeout/cancellation creates new reservation (if seats still available)
Partial availability handled at reservation time, not payment time

Pending Purchases (Mobile App):

Pending Petrol PINs accessible from "My Tickets" → "Pending Purchases" tab
Displays: match details, PIN, ticket count, amount, expiration countdown, status
Customer can edit ticket holder details (PIN remains valid)
Customer can cancel pending PIN request
Automatic cleanup of expired/completed PINs from pending list

Last Updated: January 2026