Gift Card

Description / Background

Gift Card is a feature that enables customers to purchase vouchers to give to others. These vouchers can be used to make restaurant bookings on participating restaurants/hotels within HungryHub platform.

Current State:

•   *   Gift Card feature exists for Thailand (THB)
  

  • Available for purchase via web/app
  • Redeemable in app bookings
  • Validity: 365 days from purchase

Multi-Country Expansion:

•   *   Extended to Singapore (SGD) and Malaysia (MYR)
  

  • Gift cards are country-locked and currency-locked
  • A gift card bought for a country can only be redeemed on restaurants in that same country

Objectives

• Enable customers to purchase gift cards as gifts for others
• Support multi-country and multi-currency operations (Thailand, Singapore)
• Provide flexible redemption options based on gift card value
• Enforce country and currency restrictions to ensure proper usage
• Users have the ability to purchase gift cards in multiple denominations (TH/SG)
• Users can choose predefined denominations or enter a custom amount
• Users have a minimum amounts by country: Thailand 50 THB, Singapore 10 SGD
• Users get email delivery of gift card code to recipient
• Users get a copy of gift card code for sender (optional)
• Users have multiple payment method options (Credit/Debit Card, QR Payment)
• Users get gift cards valid for 365 days from the date of purchase
• Users in Thailand (THB): Predefined 100, 200, 500, 1,000, 2,000 THB with minimum custom amount 50 THB, single-use < 1,000 THB, deductible >= 1,000 THB
• Users in Singapore (SGD): Predefined 10, 20, 50, 100, 200 SGD with minimum custom amount 10 SGD, single-use < 100 SGD, deductible >= 100 SGD
• Users can use gift cards at participating restaurants/hotels (indicated by specific icon)
• Users can apply multiple gift cards per booking (same country/currency)
• Users get automatic discount application at checkout
• Users get balance tracking for deductible gift cards
• Users get remaining balance carry-over for future bookings (deductible cards)
• Users get clear visibility of gift card balance after each use
• Users can use gift cards multiple times until balance exhausted or card expires
• Users get easy code entry during booking checkout
• Users get clear error messages for invalid/expired codes
• Users get balance display and transaction history
• Users get multi-language support across interface
• Users get currency estimation display (when applicable)
• Users get a gift card page showing base currency with target currency estimation (Est.)
• Users get a cart window showing base currency with target currency estimation (Est.)
• Users get a checkout page with target currency in Est. with additional note: “Since this gift card is for [Country], you will be charged in their original currency: [amount] [currency]”
• Users get transactional pages (confirmation) using base currency
• Users must pay remaining balance using available payment methods if booking amount exceeds gift card value
• Users can use remaining balance for future bookings if booking amount is less than gift card value (for deductible cards)
• Users cannot cancel gift card purchase
• Users cannot get a refund on gift card purchase (final sale)
• Users cannot modify gift card amount after purchase
• Users cannot change recipient email after purchase
• Users cannot extend gift card validity beyond 365 days
• Users cannot use gift card cross-country (country-locked): TH Gift Card only for Thailand restaurants, SG Gift Card only for Singapore restaurants,
• Users cannot use gift card in a different currency (currency-locked)
• Users cannot use expired gift cards
• Users cannot mix gift cards from different countries in single booking
• Users cannot use gift cards at non-participating restaurants
• User can’t edit bookings made with gift cards
• User can’t transfer gift card balance to another card
• User can’t combine gift card with certain other promotions (if restricted)
• User can’t use gift card for booking modifications
• User can’t reverse gift card redemption once applied
• User can’t exchange gift card for cash
• User can get bookings refunded according to normal refund policies

Upcoming:

• Users have the ability to purchase gift cards in MY
• User have Malaysia rules (MYR): Predefined 15, 30, 80, 150, 300 MYR with minimum custom amount 15 MYR, single-use < 150 MYR, deductible >= 150 MYR
• Users have a minimum amounts by country: Malaysia 15 MYR
• MY Gift Card only for Malaysia restaurants

Terms & Conditions

• Gift Card purchases are final and cannot be canceled or refunded under any circumstances
• Gift cards can only be redeemed in the country they were purchased for
• No cross-country usage allowed

Scope

• Gift card purchase flow with multiple denominations
• Gift card redemption during booking checkout
• Country-specific rules (TH, SG)
• Multi-gift card stacking (same country/currency)
• Gift card balance management
• Email delivery system
• Payment integration (Debit/Credit Card, QR Payment)

Upcoming

• Gift Card for Malaysia

Out of Scope

• Cross-country redemption
• Refunds on gift card purchases
• Gift card editing after purchase
• Corporate bulk purchase features

Location

Web

• Gift Card Page:  https://web.hungryhub.com/hungry-hub-gift-card?locale=en
• Country-specific pages with switcher (TH/SG)
• Checkout page with gift card redemption field

Mobile App

• Gift Card section in main menu
• Redemption during booking checkout
• Gift card management in user profile

Redemption Process

1. 1. User enters Gift Card code during booking checkout (same field as promo code)
   

   2. System validates:
      • Gift card country matches booking country
      • Gift card currency matches booking currency
      • Gift card is not expired
      • Gift card has available balance

2. 1. Gift Card value is applied as discount to booking total
   

   2. If booking amount exceeds Gift Card value:
      • Remaining balance must be paid using available payment methods

3. 1. If booking amount is less than Gift Card value:
    *   Remaining balance can be used for future bookings (for deductible cards)
   

How to find Gift Card

How to find Gift Card

For Customers

1. 1. Navigate to HungryHub website or app
   

   2. Access Gift Card page from main menu or direct URL
   3. Switch between countries (TH/SG) using country selector
   4. Select or enter custom denomination
   5. Complete purchase flow

How to Purchase Gift Card

1. 1. Select country/currency (TH/SG)
   

   2. Choose predefined denomination or enter custom amount
      • Minimum: 50 THB / 10 SGD

2. 1. Enter recipient email address
   

   2. Select payment method (Debit/Credit Card or QR Payment)
   3. Complete payment
   4. Gift card code sent to recipient’s email

Sequence Diagram / Flow

ERD

Backend Implementation

Singapore Giftcard

• Country-aware voucher transaction flow added in `VoucherService::CreateTransaction`:
  • Validates country and currency combinations for voucher purchases.
  • Routes credit card payments to GB PrimePay (TH) or Omise (SG) and persists provider info.
  • Stores `country_id`, `cc_provider`, and `promptpay_provider` on `VoucherTransaction`.
• Added Omise adapter support for voucher transactions to enable Singapore credit card charges.
• Voucher intros are now country-scoped and locale-aware in admin:
  • `Vouchers::Intro` includes `country_id` and additional `header_` columns for more locales.
  • AI translation service + worker added to translate intro fields asynchronously with Redis status tracking.
  • Admin endpoints added: `translate_by_ai`, `translation_status`, `save_all_translations`.

 PR:

https://github.com/hungryhub-team/hh-server/pull/7637

Hybrid Implementation

Singapore Giftcard:

• Two-step gift card purchase flow introduced on the gift card pages:
  • Refactors BuyGiftCard to split selection and payment/summary steps.
  • Adds GiftCardStepper and GiftCardBuyEntry to drive the hybrid purchase flow.
• Multi-currency support (TH, SG, MY) with country-aware UI:
  • Adds currency/country selectors in GiftCardSlider and DropdownLanguageSelector.
  • Filters GiftCardIntros by selected country and updates currency labels in RestaurantCurrencyLabel.
  • Extends constants to include HUNGRYHUB_VOUCHER and countryCode2 typing.
• Summary and pricing display updated:
  • Estimated price appears in CustomVoucherCard, ChargeItem2, and GiftCardTotal.
  • CustomVoucherChargeSummary uses shared booking summary with collapse toggle.
  • GiftCardDetailContent extracts detail and T&C into a reusable component.
• Hybrid event support added for country selection and purchase success/error:
  • Mobile next/back handling updated in GiftCardBuyButton.
  • eventManager and hybrid pages emit new gift card events.
• API/model wiring adjusted for new gift card flow:
  • Updates voucher API modules, giftCardTransaction, and bookingCharge to carry currency and estimated pricing.
  • ReservationStatusWatcher and real-time reservation logic handle voucher-specific redirects.
• Localization updates:
  • Adds strings for confirm order, minimum voucher amount, and gift card notices across locales.

 PR:

https://github.com/hungryhub-team/hh-pegasus/pull/2523

PRD & Task

• Gift card PRD: 1017 - Gift Card
• Gift card bu country: Gift Card by Currency/Country Task:
• Singapore Gift card: https://app.clickup.com/t/86d0zmmgg
• Malaysia Gift card: https://app.clickup.com/t/9003122396/86d0znrya

Design

Figma Design File: https://www.figma.com/design/JybzW8b3n7eKZEWm3vQfL2/Gift-Card-Checkout?node-id=27-8787&t=FLwBKEE2C2I3cHfk-1

API Blueprint

DB Schema / Database Migration

•  Migrations add country_id voucher_intro voucher_transactions .
• Migrations add cc_provider and promptpay_provider on voucher_transactions .
• Migrations add header_es, header_fr, header_de, header_ru, header_ms, header_ko, header_ja, header_id, header_vi, header_zh on `voucher_intro`. Data migrations:
• Backfill voucher_transactions.country_id for existing records.
• Set existing voucher intros to Thailand and seed Singapore voucher intros.

Improvement: