Hold Orders (Duffel Integration)

Hold Orders (Duffel Integration)

This document explains how Lezgo will use Duffel’s Hold Orders, who will have access, and what we expect in terms of usage and conversion.

1. Site URL where Hold Orders will be used

• Production URL: https://lezgo.travel
• Staging / Test URL: https://staging.lezgo.travel

Hold Orders will be available only on the flight booking flow (Duffel-powered content). Hotel bookings are out of scope for Hold Orders.

---

2. Business model & why we need Hold Orders

Business model

• Lezgo is a consumer-facing online travel agency (OTA) focused on:
  • Flight and hotel bookings
  • Crypto-first payments (Solana Pay, $LZG, stablecoins) plus traditional payment methods
  • Loyalty, rewards, and games layered on top of travel (e.g. Lezgo Guessr, SEEKER app)
• Duffel is our primary flight content and order management provider.

Why Hold Orders are needed

• Asynchronous payment confirmation:
  Some payment methods (private checkout like cards/bank or third-party gateways) can require authorization or compliance checks. Payment confirmation can take minutes. A Hold Order keeps the itinerary and price while payment is pending.
• Seat/fare volatility and race conditions:
  Airline availability can change in seconds. Holding avoids cases where a user pays just as the fare/seat disappears, reducing refund workflows and frustration.
• High-value / group bookings:
  For multi-city or group travel, users want to lock in price and coordinate payment across travelers without losing the offer.
• Better UX & conversion:
  • Reduces last-second failures due to fare volatility
  • Provides a clear window to finalize payment
  • Improves completion rates for high‑intent users

In short, Hold Orders let users secure an itinerary immediately while the system waits for payment until the airline-provided expiry time.

---

3. Booking flow for Hold Orders

Hold Orders apply only to eligible Duffel fares in the flight flow.

3.1. User-facing flow (high level)

1. Search flights

   • User searches flights (origin, destination, dates, passengers).
   • Results are returned via Duffel.

2. Select itinerary

   • User selects a flight.
   • If the fare supports holding, we show an additional option:
     • “Hold (waiting for payment)” (beside or below the standard “Pay now” option).

3. Enter traveler details

   • User fills passenger information (names, DOB, contact, etc.).
   • Validation happens before any hold is attempted.

4. Choose Hold (waiting for payment) vs Pay now

   • At the “Review & Payment” step:
     • Option A: Pay now (standard Duffel order creation + payment).
     • Option B: Hold order:
       • User confirms they want to hold the itinerary.
       • We create a Duffel Hold Order via API.
       • The UI displays:
         • Hold expiration date/time
         • Summary of itinerary and total price
         • Clear CTAs: “Pay now” or “Cancel hold”.

5. Payment of a held order

   • Before expiry, the user can:
     • Return to their “My trips / Holds” page.
     • Select the held booking.
     • Proceed to payment using:
       • Solana Pay / $LZG / stablecoin
       • Private checkout (card, bank, etc.).
   • On successful payment:
     • We convert the hold into a fully paid order via Duffel.
     • User receives confirmation and e-ticket details.

6. Expiry of holds

   • If the hold is not paid by the expiry time:
     • The hold expires automatically.
     • We clearly mark the booking as “Expired hold” in the UI.
     • No further payment is possible for that hold.

3.2. Design / screenshots (placeholders)

Replace these placeholders with final screenshots when ready:

Note: Using external placeholders prevents local build errors until assets are available.

3.3. Hold timing & expiry

• We strictly use the Duffel-provided hold expiry returned for the fare.
• The UI displays a countdown timer and disables payment after expiry.
• We do not override or extend airline expiries.

---

4. Travellers who will have access to Hold Orders

• User segment:
  • B2C retail travelers using Lezgo’s web/app interface
  • Age 18+ (standard OTA audience)
  • Global, with an initial focus on EU + selected other regions
• Access conditions:
  • Logged-in account with verified email / phone
  • For some payment methods (e.g. private checkout), KYC may be required
• Exclusions:
  • Internal admin/support accounts do not use Hold Orders for their own travel.
  • Not currently enabled for any third-party white-label partners (if applicable).

---

5. Estimated % of bookings using Hold Orders

These are planning estimates and should be customized before you send to Duffel.

• Short-term (first 3–6 months after launch):
  • Expected: 5–10% of flight bookings use Hold Orders
• Longer term (once users are familiar):
  • Expected: 10–20% of flight bookings may use Hold Orders
• Usage profile:
  • Skews towards:
    • Higher basket sizes
    • Multi-passenger or multi-city itineraries
    • Crypto users needing extra time to move funds

---

6. Estimated % of held bookings that will be paid vs expire

Again, these are assumptions for Duffel; adjust to your comfort level.

• Estimated conversion of held bookings to paid:
  • 60–80% of held bookings expected to be paid before expiry
• Estimated expiry rate:
  • 20–40% expected to lapse/expire without payment
• Mitigation & UX:
  • We show:
    • Clear countdown timer to expiry
    • Reminder emails / push notifications (where user has consented)
  • We may limit:
    • Total number of simultaneous holds per user
    • Hold availability based on past behavior (to reduce abuse)

---

7. When to use Hold Orders vs Pay Now

Use a Hold Order (waiting for payment) when any of the following apply:

• Payment flow includes card/bank authorization, OTP/3DS, or gateway checks.
• High-demand itineraries where seat/fare can change during the payment handshake.
• Multi-passenger or multi-city bookings that need a few minutes to coordinate payment.
• You want the order created first to avoid refund flows if inventory moves.

Use Pay Now when:

• Payment can complete instantly and there’s low risk of inventory change.
• Simple one-passenger, point-to-point itineraries with quick checkout.

This is not “pay later”; it is “order created and reserved, waiting for payment” until the airline’s expiry.

---

8. Abuse prevention & limits (policy)

To avoid mass unused reservations, we apply:

• Eligibility: verified account (email/phone) required; KYC when mandated by payment method.
• Quotas: limit active holds per account; block additional holds until paid/cancelled/expired.
• Rate limits: cap hold attempts per user/time window; back off on suspicious patterns.
• Dynamic gating: enable holds only on eligible fares and based on past conversion behaviour.
• Auto-cancel: immediate release at expiry; UI prevents payment attempts after expiry.
• Monitoring: track hold→paid conversion, expiry reasons, and per-route spikes.

Optional (if needed): refundable small hold fee or pre‑authorization to further reduce abuse.

---

Technical Implementation Notes

API Integration

• We’ll use Duffel’s Hold Orders API endpoints:
  • POST /air/hold_orders - Create a hold
  • GET /air/hold_orders/{id} - Retrieve hold status
  • POST /air/hold_orders/{id}/actions/pay - Convert to paid order
  • POST /air/hold_orders/{id}/actions/cancel - Cancel hold

Error Handling

• Handle cases where:
  • Hold cannot be created (fare not eligible, insufficient availability)
  • Hold expires before payment
  • Payment fails after hold creation

User Communication

• Clear messaging about:
  • Hold expiration times
  • Payment deadlines
  • What happens if hold expires
  • How to cancel unwanted holds

---

Security & Compliance

• Fraud Prevention: Monitor hold creation patterns
• Rate Limiting: Prevent abuse of hold functionality
• Data Privacy: Secure handling of passenger data during holds
• Regulatory Compliance: Adhere to travel booking regulations

---

This document serves as both internal planning and external communication with Duffel regarding our Hold Orders implementation.