FuelVoucher

Validate fueling vouchers across app, POS, ESB, and fuel switch.

FuelVoucher is a multi-app voucher and fueling authorization platform for station owners, operators, and customers. It lets a customer generate a voucher in a mobile app, validate it at the POS with QR or NFC, route eligibility checks through a voucher service and ESB to the fuel switch, and then reconcile fuel dispensed, refunds, and charges accurately. The product matters because it replaces manual approval and fragmented settlement with a secure, auditable flow from voucher issue to final fueling consumption.

Business Goals

  • Reduce voucher fraud and duplicate redemption by at least 95% within 3 months of launch.
  • Increase successful fueling authorization completion to 98%+ within 8 weeks of pilot rollout.
  • Cut manual operator exception handling by 60% within 6 months.
  • Achieve 30 active station sites and 10,000 monthly voucher validations within 12 months.
  • Improve settlement accuracy so refund and overage billing discrepancies stay below 0.5% of transactions.

User Goals

  • Let customers create and present a fueling voucher from a mobile app in under 60 seconds.
  • Let POS operators scan QR or tap NFC and instantly know whether the voucher is valid and how many liters are allowed.
  • Let station owners monitor voucher usage, wallet balance, and settlements in one dashboard.
  • Let operators record actual fueling and refunds without manual spreadsheet reconciliation.
  • Let customers view a complete fueling history and receipt trail in their app.

Non-Goals

  • Replacing the core POS software used at the station.
  • Building a full payment gateway or card acquiring network.
  • Handling physical fuel pump hardware firmware changes beyond standard ESB integration.
  • Supporting arbitrary discount campaigns unrelated to voucher-based fueling authorization.

Customer Farah, 34 - A frequent driver who buys or receives prepaid or entitlement-based fuel vouchers and wants a fast, trustworthy way to redeem them at any supported station.

Customer Farah, 34

  • As a customer, I want to create or receive a voucher in my app, so that I can redeem fuel without carrying paper coupons.
  • As a customer, I want to scan a QR code or tap NFC at the station, so that redemption is quick and contactless.
  • As a customer, I want to see my fueling history and refund adjustments, so that I can verify what I was charged.

Station Operator Reza, 41 - A forecourt operator using the POS to validate vouchers, initiate fueling, and record any post-fueling refund or excess consumption.

Station Operator Reza, 41

  • As an operator, I want to validate a voucher in the POS, so that I know immediately whether the customer is authorized.
  • As an operator, I want to see the maximum allowed liters from the fuel switch response, so that I can prevent over-dispensing.
  • As an operator, I want to submit final dispensed liters and refund liters, so that billing is reconciled automatically.

Station Owner Mina, 52 - Owns one or more stations and needs visibility into voucher sales, usage, exceptions, and settlement performance across sites.

Station Owner Mina, 52

  • As a station owner, I want a dashboard of issued, redeemed, rejected, and refunded vouchers, so that I can manage operations and revenue.
  • As a station owner, I want to configure station-level integration credentials, so that each site connects securely to the ESB and voucher service.
  • As a station owner, I want audit logs for every voucher decision, so that disputes can be resolved quickly.

Voucher issuance and wallet · High priority

  • The customer app and station owner app must support wallet-backed voucher creation, top-up, and voucher generation with either liter-based or amount-based value.
  • Support voucher generation for amount or liters with a required expiry date and station scope.
  • Deduct or reserve value in the wallet at issuance time based on configured business rules.
  • Generate a signed voucher token containing a unique voucher ID, customer identifier, and value parameters.
  • Support balance display and wallet transaction history in the customer and owner apps.
  • Reject issuance when customer identity or wallet balance is insufficient.

POS voucher validation · High priority

  • The POS must validate the presented voucher token from QR or NFC before any fueling starts.
  • Accept QR scan and NFC tap as input methods.
  • Validate token signature locally in the POS before network round-trips.
  • Send token to voucher service to check duplication, status, expiry, and lock the voucher for single use.
  • Return clear POS messages for valid, expired, duplicated, revoked, or unsupported vouchers.
  • Cache the last validation result only for the duration of the transaction and never for reuse.

ESB and fuel switch authorization · High priority

  • After voucher acceptance, the POS must send voucher details to the ESB which forwards a standardized authorization request to the fuel switch.
  • Transmit national ID, phone number, PAN or equivalent identity data only when available and required by rules.
  • Receive from the fuel switch the allowed liters for this customer and voucher combination.
  • Display the allowed liter cap to the operator before fueling starts.
  • If the fuel switch rejects or times out, the POS must stop the flow and show a retryable error.
  • All requests and responses must carry correlation IDs for traceability.

Fuel dispensing and settlement · High priority

  • The system must record actual liters dispensed, compare with allowance, and charge or refund the difference automatically.
  • Allow the operator to enter the final dispensed liters after fueling completes.
  • If dispensed liters exceed allowed liters, calculate the extra amount and send a charge instruction to the voucher service.
  • If refund liters are entered, create a refund adjustment record and forward it to voucher service and ESB for settlement.
  • Generate a post-fueling token or receipt reference for audit and customer lookup.
  • Prevent duplicate settlement by enforcing idempotency on the final consumption request.

Customer reporting and audit · Medium priority

  • Customers and station owners must be able to retrieve fueling reports using QR, NFC, or transaction reference.
  • Let customers open transaction history from the app and filter by station, date, and status.
  • Support scanning a receipt QR or tapping NFC tag to retrieve a completed fueling record.
  • Store immutable audit logs for issuance, validation, authorization, fueling, refund, and settlement events.
  • Expose exportable reports for station owners in CSV and PDF.
  • Mask sensitive identity data in user-facing receipts.

Guided Voucher Redemption

  • Customer signs in or registers in the customer app and creates a wallet-backed voucher in under 2 minutes.
  • Customer presents a QR code or NFC token at the station POS.
  • Operator scans or taps the token and immediately sees a validation result.
  • POS requests allowance from voucher service, then routes authorization through ESB to the fuel switch.
  • POS shows permitted liters and the operator starts fueling within 10 seconds end-to-end.
  • After fueling, the operator confirms actual liters and the customer receives a digital receipt and history entry.

1. Issue Voucher

  • The customer, station owner, or operator creates a voucher in the appropriate app, choosing liters or amount and confirming identity fields.
  • Validate required fields such as phone number and national ID before issuing.
  • Generate a signed token and persist a voucher record with status Reserved.
  • If wallet funds are insufficient, block issuance and show the exact shortfall.

2. Present Token

  • The customer presents the voucher at the POS using QR code or NFC.
  • Support offline display of the token in the app for low-connectivity situations.
  • Refresh the token display if the voucher is reissued or canceled.
  • Reject screenshots or stale tokens if the signing timestamp or nonce is invalid.

3. Validate and Lock

  • The POS validates the token signature and sends it to the voucher service to lock redemption.
  • Check signature locally before making network calls.
  • Detect duplicate redemption attempts using voucher status and idempotency keys.
  • Show specific error states for expired, already used, suspended, or mismatched customer data.

4. Authorize Fueling

  • The POS sends voucher details through the ESB to the fuel switch, which computes the permitted liters.
  • Send only the minimum required identity data and transaction metadata.
  • Handle fuel switch latency with a visible spinner and timeout fallback.
  • If the fuel switch returns zero liters, immediately block fueling and log the reason.

5. Settle and Report

  • After fueling, the operator records actual liters and any refund liters, and the system settles the transaction.
  • Charge extra liters automatically according to configured price per liter.
  • Refund unused liters where policy allows and store the adjustment in the voucher service.
  • Make the completed transaction visible in customer and owner reporting within 30 seconds.

Power Features and Edge Cases

  • Multi-station rules for vouchers that can be redeemed only at selected station groups.
  • Partial redemption support for vouchers issued as amount and converted to liters at the current station price.
  • Manual override workflow with supervisor PIN when network or ESB connectivity fails.
  • Automatic fraud controls for repeated failed scans, device mismatch, and suspicious refund patterns.
  • Admin rule engine for identity-based allowance logic such as national code, phone number, and PAN validation.

Operational Clarity and Trust

  • Large, high-contrast POS states for Valid, Locked, Allowed Liters, Fueling, Settled, and Failed.
  • One-tap QR scan and NFC tap actions with audible feedback for busy forecourt environments.
  • Accessibility support with readable typography, color-safe status indicators, and minimal input steps.
  • Low-latency feedback with optimistic transitions, but no claim of success until voucher service and ESB confirm.
  • Clear customer-facing receipt screens that show voucher ID, station, liters, adjustments, and final amount.

Farah receives a prepaid fueling voucher in her customer app before a long trip. She opens the app at the station, displays the QR code, and the operator scans it on the POS. Within seconds the voucher is validated, locked, routed through the ESB, and approved by the fuel switch with a clear maximum liter allowance.

The operator sees the permitted liters and starts fueling without guessing or calling a supervisor. After the pump stops, the operator enters the exact liters dispensed, the system settles any overage or refund automatically, and Farah immediately sees the completed transaction in her app. The station gets a clean audit trail, fewer disputes, and faster throughput at the forecourt.

User-Centric Metrics

  • 95% of valid voucher redemptions complete in under 10 seconds at POS.
  • Customer transaction lookup success rate above 99%.
  • At least 90% of customers can redeem without operator assistance after the first month.
  • Operator correction rate below 2% of fueling sessions.
  • Refund and overage calculation accuracy above 99.5%.

Business Metrics

  • 10,000 monthly voucher redemptions within 12 months.
  • Station onboarding to live usage within 5 business days on average.
  • 60% reduction in manual reconciliation effort for participating stations.
  • 40% repeat redemption rate among registered customers within 90 days.

Technical Metrics

  • 99.9% API uptime for voucher service and POS gateway.
  • P95 validation latency under 1.5 seconds end-to-end excluding fuel switch outage cases.
  • 0 critical security incidents involving token replay or unauthorized redemption.
  • All authorization and settlement events persisted with 100% audit traceability.

Tracking Plan

  • voucher_created
  • voucher_issued
  • token_scanned
  • token_nfc_tapped
  • voucher_validation_accepted
  • voucher_validation_rejected
  • fuel_authorized
  • fuel_dispensed
  • refund_recorded
  • settlement_completed
  • receipt_viewed
  • report_exported

Technical Needs

  • Mobile apps built with React Native or Flutter for customer, station owner, and operator experiences.
  • Backend services in Node.js or Java Spring Boot with a dedicated voucher service and POS API gateway.
  • PostgreSQL for transactional voucher, wallet, and settlement data.
  • Redis for short-lived token locks, idempotency keys, and validation throttling.
  • Message bus such as Kafka or RabbitMQ for ESB-style event propagation and retries.
  • JWT or signed token scheme using asymmetric keys with rotation and revocation support.
  • Role-based access control with station, operator, owner, and customer scopes.

Integration Points

  • ESB server as the routing layer between POS and fuel switch.
  • Fuel switch authorization API for liter allowance and consume confirmation.
  • SMS or OTP provider for customer identity verification when needed.
  • Push notification service such as Firebase Cloud Messaging for status updates and receipt delivery.
  • Optional national ID or PAN verification service if the deployment requires identity checks.

Data Storage & Privacy

  • Encrypt sensitive data at rest and in transit using AES-256 and TLS 1.2+.
  • Store only the minimum identity fields necessary for voucher decisioning and receipts.
  • Mask national IDs, phone numbers, and PAN-like identifiers in logs and UI by default.
  • Support GDPR and CCPA requests for data export and deletion where local regulations permit.
  • Keep immutable audit logs for financial events, but separate them from mutable profile data.

Scalability & Performance

  • Design POS authorization to handle peak station bursts of 20 to 50 requests per minute per site.
  • Use retry with backoff and idempotency to survive temporary ESB or fuel switch outages.
  • Cache non-sensitive station configuration at the edge to reduce round trips.
  • Define strict timeouts so the operator always gets a decision or a clear fallback path within a few seconds.

Potential Challenges

  • Duplicate redemption or replay attacks could cause revenue loss; mitigate with signed tokens, nonce tracking, and short-lived locks.
  • ESB or fuel switch downtime could block sales; mitigate with queueing, circuit breakers, and manual override rules.
  • Identity data mismatches may reject legitimate customers; mitigate with normalized validation and clear operator error messaging.
  • Refund and extra-charge settlement disputes could create support burden; mitigate with immutable logs and customer-visible receipts.
  • Multi-app coordination may introduce version drift; mitigate with versioned APIs and contract testing across all clients.

Team & resourcing - Small cross-functional team - 3 engineers, 1 product designer, part-time QA, part-time PM.

Phase 1: Voucher MVP · Weeks 1-4

  • Customer app voucher creation with wallet balance
  • Signed QR token generation
  • POS validation against voucher service
  • Basic operator screens for accept/reject
  • Audit logging for issuance and validation

Phase 2: ESB and Fuel Switch Integration · Weeks 5-8

  • POS to ESB request flow
  • Fuel switch allowance response handling
  • Allowed liter display in POS
  • Token lock and duplicate prevention
  • End-to-end staging environment with test station

Phase 3: Settlement and Reporting · Weeks 9-12

  • Final dispensed liter capture
  • Overage charge and refund flow
  • Customer receipt and transaction history
  • Station owner dashboard and exports
  • Exception handling for timeout and manual override

Phase 4: Pilot Hardening · Weeks 13-16

  • Performance tuning and security review
  • Role-based access control and credential rotation
  • Monitoring, alerting, and operational runbooks
  • Pilot rollout to 3 to 5 stations
  • Support tools for dispute resolution and audit lookup

Paste this into Cursor, Bolt, Lovable, or v0 to start building.

Build a production-ready fuel voucher redemption platform called FuelVoucher.

Use a sensible default stack: Next.js 14 for web dashboards, React Native for mobile apps, Node.js with TypeScript and NestJS for backend services, PostgreSQL for transactional data, Redis for token locks and idempotency, and Kafka or RabbitMQ for async integration events. Use JWT plus asymmetric signing for voucher tokens, and design for secure API integration with an ESB and a fuel switch.

Core product:
1) Three user experiences: customer mobile app, station owner app/dashboard, and operator POS/tablet app.
2) Customer app: wallet balance, create voucher with amount or liters, view voucher QR/NFC token, transaction history, receipt lookup.
3) Operator POS app: scan QR or read NFC, validate signature locally, call voucher service to lock redemption, route authorization through ESB, display allowed liters, capture final dispensed liters, capture refund liters, and complete settlement.
4) Station owner dashboard: manage stations, view voucher usage analytics, reconciliation reports, exceptions, and audit logs.
5) Voucher service: issue vouchers, track wallet reservations, enforce one-time redemption, duplicate detection, expiry, status transitions, and settlement calculations.
6) Integration service: send validated requests to ESB, receive fuel switch allowance responses, persist correlation IDs and final consume confirmations.

Primary screens/flows:
Customer onboarding and login, wallet overview, create voucher, show QR/NFC token, voucher history, fueling receipt detail.
Operator POS home, scan/tap screen, validation result screen, allowed liters screen, fueling confirmation, settlement screen, error/retry screen.
Owner dashboard: stations list, redemptions, settlements, refunds, reports, audit logs, settings.

Data model entities:
User, Role, Station, Wallet, Voucher, VoucherToken, VoucherRedemption, FuelAuthorization, FuelDispense, RefundAdjustment, Settlement, AuditEvent, IntegrationRequest, IntegrationResponse.
Include statuses such as Draft, Reserved, Locked, Authorized, Dispensed, Settled, Expired, Revoked, Rejected.

Important logic:
A voucher may be created as either amount-based or liter-based. At redemption, POS must validate the token signature, then the voucher service must lock it to prevent duplicates. The ESB and fuel switch determine the allowed liter cap based on customer identity fields such as national code, phone number, and PAN where applicable. The operator may dispense less than or equal to the allowance. After fueling, the operator enters actual liters and any refund liters; the system calculates any extra charge or refund and sends settlement updates back to voucher service and ESB.

Engineering requirements:
Implement RBAC, audit logging, request correlation IDs, idempotent settlement endpoints, validation errors with clear operator messages, retry/backoff for ESB and fuel switch calls, and observability with structured logs and metrics. Add seed/mock integration modes so the app can be demoed without live ESB or fuel switch access.

Deliver responsive, accessible UI with large POS-friendly controls, QR scanner, NFC-ready hooks, and clear status states for success/failure/loading. Scaffold the backend APIs, database schema, and frontends with realistic folder structure, sample data, and environment variable templates.

Business Idea

hi. we have a business that is have 3 starter as customer, station owner and operator, the should have own application, we want they can communicate with a voucher service, in the vocher service they should have wallet, and we should generate vocher for them, voucher should accept with a pos device that should accept qr or nfc from that apps, then voucher should validate in pos and send this to the voucher service for check duplication and existation, then if get acc from that, send request of the information to esb server, it send data from an amp area that pos can communicate in that to the feul switch, then feul switch based on the the information is in the vocher such as national code, phone number and valid pan card should say that the voucher can used until how many liter, that voucher in first app generation can have liter or amount, and thet feul switch allow or disallow with an liter amount, then we should in pos show the alow based on that and user can choose the liter less equal that amount and after we generate token for that, we should send the used to voucher and esb for send to feul switch, and after feuling , if the operator enter any refund liter for that vocher we should say that to voucher server to charge as rial of that. say if you have any question 1-show voucher app costumer to pos 2- pos validate token signiture 3- send token to voucher service to accept and lock this 4- answer voucher service 5- pos send voucher detail to ESB server and ESB send to feul swtich 7- feul switch answer that this costumer detail have how many alow liter 8- ESB answer this to pos 9- customer choose an amount less equal that feul response 10- pos send that voucher used with liter detail to voucher and voucher server charge for extra amount that user paid. 11- pos generate and print token for feuling 12- send request to ESB to send consume to feul switch 13- get ok from that. 14- customer can get report of feuling by nfc or scan qr in costumer app

Make My PRD

Design by The Resonance | Powered by GPC – The AI Transformation Company