🔒

Protected Content

Please enter the password to access the documentation.

FB
TheDocsFoundryDocumentation

Currency, FX, Payment, Credit-Led Booking, and Reconciliation Strategy

1. Purpose

This document consolidates the decisions, options, workflow, mental model, and implementation guidance discussed for FlyMax around:

  • local currency display
  • FX data provider selection
  • payment currency vs display currency
  • customer payment vs supplier credit-funded booking
  • booking/payment/credit linkage
  • reconciliation and finance truth
  • XE and alternative FX API comparison
  • recommended architecture and implementation order

This is written to be ordered, implementation-oriented, and decision-ready.

2. Governing FlyMax product interpretation

FlyMax is not a redirect-only metasearch product. It is a direct-booking, finance-traceable, support-aware platform with:

  • on-platform customer payment
  • booking creation and continuity
  • credit-led supplier purchasing support
  • finance and reconciliation visibility
  • admin / agent / user role separation
  • support and auditability as first-class concerns

Practical implication

Any currency/payment/booking design must preserve:

  • payment state
  • booking state
  • credit state
  • support-visible event history
  • reconciliation visibility
  • audit trail

3. The corrected FlyMax business/finance model

3.1 Real commercial flow

FlyMax is a two-ledger commercial model:

  1. Customer money ledger

    • Customer pays FlyMax through the payment gateway.

  2. Supplier credit ledger

    • FlyMax books flights using pre-funded / approved credits with Verteil, BSP, IATA-linked, or aggregator-side arrangements.

That means customer payment and supplier booking funding are related, but they are not the same financial event.

3.2 Core consequence

Do not model the system as:

customer payment -> direct supplier settlement -> done

Instead, model it as:

customer payment -> platform-held commercial funds
booking attempt -> supplier credit reservation / consumption
reconciliation -> join both sides into one authoritative business truth

4. Mental model: four money layers

For FlyMax, keep these as distinct concepts:

4.1 Display currency

What the user sees on search/results/checkout pages.

Examples:

  • UAE visitor sees AED
  • India visitor sees INR
  • Saudi visitor sees SAR

4.2 Customer payment currency

What the gateway actually charges the customer in.

This may be:

  • the same as display currency
  • or different if the payment setup does not support shopper-local presentment

4.3 Supplier / fare currency

The validated fare currency returned by supplier-side pricing / booking logic.

4.4 Supplier credit / settlement currency

The currency in which FlyMax supplier credits are held, consumed, or settled.

This can differ from:

  • display currency
  • customer payment currency
  • supplier fare currency

4.5 Platform base/reporting currency

Optional but useful internal reporting currency, for example INR for India-based operations.

5. The correct source-of-truth model

5.1 Do not use FX API as settlement truth

An FX API such as XE, Open Exchange Rates, ExchangeRate-API, or Fixer is useful for:

  • display conversion
  • approximate local pricing
  • internal reporting views
  • dashboards
  • quote estimation

It is not the final source of truth for:

  • gateway settlement
  • actual customer charge outcome
  • supplier credit deduction
  • BSP/aggregator statement math
  • refund-time or dispute-time currency impact

5.2 The three truth sources FlyMax needs

A. FX provider truth

Use for:

  • display conversion
  • indicative customer-local pricing
  • non-accounting reporting conversions

B. Gateway truth

Use for:

  • exact customer charge amount
  • charge currency
  • capture/refund/reversal status
  • gateway fees
  • payout/settlement to FlyMax

C. Supplier credit / statement truth

Use for:

  • credit balance
  • credit reservation
  • credit consumption
  • release / adjustment
  • aggregator / BSP / IATA-linked statement lines
  • supplier-side funding truth

5.3 Authoritative FlyMax truth

The real business truth is FlyMax’s internal reconciliation ledger, built by joining:

  • customer payment records
  • booking / supplier references
  • supplier credit movements
  • later settlement statement rows

6. Currency strategy for FlyMax

6.1 Common rule

Use this rule everywhere:

  • Display in user-preferred / market currency
  • Quote final payable amount before payment
  • Charge in a supported payment currency
  • Book using supplier pricing and credit rules
  • Reconcile customer payment + supplier credit consumption + platform revenue logic

6.2 Local display currency

Use for:

  • search results
  • comparison screens
  • booking details
  • dashboards
  • email/notification rendering where appropriate

Default from:

  • market / country version
  • locale
  • logged-in user preference
  • agent organization preference
  • admin configuration

User examples

  • UAE site or user -> AED
  • India site or user -> INR
  • KSA site or user -> SAR

6.3 Payment currency

The payment currency should be the best supported charge currency given:

  • merchant/gateway account capability
  • country / acquiring setup
  • card / payment method support
  • market / regulatory constraints

Important

Display currency and payment currency can be:

  • same (best UX)
  • or different (must be clearly disclosed before payment)

6.4 Supplier booking / credit currency

This is determined by:

  • supplier/Verteil pricing response
  • commercial settlement setup
  • internal credit pool currency

This is often not the same as customer payment currency.

7.1 Do not use “live forex” style refresh for browsing

For FlyMax, use:

  • hourly FX refresh for display and indicative conversion
  • locked quote for checkout
  • mandatory reprice/revalidate before booking/payment completion

7.2 Why hourly is enough

In flight booking, price movement usually comes more from:

  • offer expiry
  • repricing
  • fare/availability change

than from tiny FX movements over a few minutes.

So:

  • hourly FX is usually enough for display
  • booking accuracy comes from supplier reprice/validate, not ultra-fast FX polling
  • FX provider plan: hourly
  • internal refresh: every hour
  • display cache TTL: 30–60 minutes
  • checkout quote TTL: 10–15 minutes
  • mandatory reprice before pay/book: always

8. Payment vs credit booking workflow

8.1 High-level happy path

Search
-> Display conversion
-> Offer selected
-> Reprice / Validate
-> Checkout quote created
-> Customer payment intent created
-> Customer payment captured
-> Supplier credit held/reserved
-> Booking request sent to Verteil/Aggregator
-> Booking confirmed/ticketed
-> Supplier credit consumed
-> Reconciliation completed
-> Notifications and support-visible event chain created

8.2 Key principle

FlyMax should not treat payment success alone as full business completion.

A booking is truly complete only when all of these align:

  • customer payment success
  • supplier booking success
  • supplier credit consumption success
  • internal reconciliation linkage success

9. Failure-path mental model

9.1 Payment failed

  • do not start booking
  • no supplier credit hold
  • quote expires or is retried

9.2 Payment succeeded but credit hold failed

  • booking should not proceed
  • move to exception queue
  • refund or operator recovery depending on business policy

9.3 Payment succeeded, credit held, booking failed

  • release credit hold
  • mark booking failed
  • trigger refund / balance recovery workflow

9.4 Booking succeeded but internal credit consume failed

  • booking is real externally
  • treat as finance/ops exception
  • do not silently lose traceability
  • operator repair flow required

9.5 Refund / change scenario

A refund or change workflow must know:

  • whether supplier credit was consumed
  • whether it was later released or adjusted
  • what the customer originally paid
  • what portion is refundable to customer
  • what portion is recoverable from supplier-side credit flow

10.1 Checkout / Payments

Responsible for:

  • checkout quotes
  • payment intents
  • auth/capture/refund/reversal
  • payment webhooks
  • receipts

10.2 Booking Orchestrator

Responsible for:

  • reprice / validate
  • booking request orchestration
  • supplier refs
  • booking/ticket states
  • booking retries and exception handling

10.3 Credit Ledger

Responsible for:

  • supplier credit accounts
  • reservation / hold
  • consumption
  • release
  • adjustment
  • statement import hooks

10.4 Reconciliation / Finance

Responsible for:

  • booking-payment-credit joins
  • exception reports
  • settlement visibility
  • operator repair queues
  • ledger exports

10.5 FX / Pricing

Responsible for:

  • display conversion
  • FX cache
  • checkout quote support
  • never the final settlement truth

11.1 Payment state

PENDING
-> AUTHORIZED
-> CAPTURED
-> FAILED
-> REFUND_PENDING
-> REFUNDED
-> REVERSED

11.2 Booking state

QUOTED
-> PAYMENT_PENDING
-> PAYMENT_CONFIRMED
-> CREDIT_HELD
-> BOOKING_IN_PROGRESS
-> BOOKED
-> TICKETED
-> FAILED
-> CANCELLED
-> REFUND_PENDING
-> REFUNDED

11.3 Credit state

AVAILABLE
-> HELD
-> CONSUMED
-> RELEASED
-> ADJUSTED
-> RECONCILED

12. Core tables to create first

12.1 Quote / booking side

checkout_quotes

  • id
  • tenant_id
  • user_id / agent_id
  • supplier_offer_ref
  • supplier_amount_minor
  • supplier_currency
  • customer_amount_minor
  • customer_currency
  • markup_minor
  • fee_minor
  • discount_minor
  • fx_snapshot_id
  • expires_at
  • status

booking_attempts

  • id
  • checkout_quote_id
  • payment_intent_id
  • supplier_provider
  • supplier_order_ref
  • supplier_booking_ref
  • booking_status
  • ticket_status
  • failure_code
  • idempotency_key
  • created_at

12.2 Payment side

payment_intents

  • id
  • checkout_quote_id
  • gateway
  • gateway_payment_ref
  • payment_currency
  • payment_amount_minor
  • status
  • captured_at
  • refunded_amount_minor
  • idempotency_key

payment_events

  • id
  • payment_intent_id
  • event_type
  • raw_payload
  • occurred_at

12.3 Credit side

credit_accounts

  • id
  • supplier_program
  • account_currency
  • available_minor
  • reserved_minor
  • consumed_minor
  • adjusted_minor

credit_reservations

  • id
  • booking_attempt_id
  • credit_account_id
  • reserved_amount_minor
  • currency
  • status
  • supplier_ref
  • expires_at

credit_movements

  • id
  • credit_account_id
  • booking_attempt_id nullable
  • movement_type // TOPUP, HOLD, RELEASE, CONSUME, ADJUST
  • amount_minor
  • currency
  • external_statement_ref nullable
  • occurred_at

12.4 Reconciliation side

  • id
  • booking_attempt_id
  • payment_intent_id
  • credit_reservation_id
  • reconciliation_status
  • exception_reason
  • reviewed_by
  • reviewed_at

supplier_statement_lines

  • id
  • supplier_program
  • statement_ref
  • external_booking_ref
  • amount_minor
  • currency
  • line_type
  • imported_at

ledger_entries

  • id
  • journal_id
  • account_code
  • direction
  • amount_minor
  • currency
  • booking_attempt_id nullable
  • payment_intent_id nullable
  • credit_movement_id nullable
  • created_at

13. Append-only ledger rule

Do not rely only on mutable balance columns.

Use append-only event/movement tables as the real source of truth:

  • payment_events
  • credit_movements
  • ledger_entries

Then maintain balance/projection tables for speed.

Why:

  • auditability
  • replay/rebuild ability
  • reconciliation
  • dispute/debug support
  • safe correction flows

14. Core invariants

  1. No booking finalize without confirmed payment
    unless a clearly approved alternate agent-credit path exists.

  2. No credit consumption without booking confirmation.

  3. Every booking attempt must link to one commercial quote.

  4. Payment, booking, and credit state must be queryable together.

  5. Refund logic must know whether supplier credit was held, consumed, or released.

  6. All operator overrides must create audit entries.

  7. Every external call must be idempotent or protected by internal idempotency keys.

Use transactional outbox + idempotent handlers.

Important events

  • checkout.quote.created
  • payment.intent.created
  • payment.captured
  • payment.failed
  • credit.hold.created
  • credit.hold.failed
  • booking.requested
  • booking.confirmed
  • booking.failed
  • credit.consumed
  • credit.released
  • refund.requested
  • reconciliation.matched
  • reconciliation.exception.opened

16. Minimum accounting mental model

Keep at least these internal account concepts:

  • Gateway Clearing / Customer Cash
  • Deferred Booking Liability
  • Customer Refund Liability
  • Supplier Credit Asset
  • Supplier Credit Consumption / Cost of Supply
  • Markup Revenue
  • Service Fee Revenue
  • Gateway Fee Expense
  • FX Difference
  • Manual Adjustment / Exception

Example journal shape

On customer payment capture

Dr Gateway Clearing
Cr Deferred Booking Liability

On booking success / commercial recognition

Dr Deferred Booking Liability
Cr Markup Revenue
Cr Service Fee Revenue
Cr Supplier Funding Payable

On supplier credit consumption

Dr Supplier Funding Payable
Cr Supplier Credit Asset

Finance can refine the exact accounting treatment, but the key design point remains:

customer payment and supplier credit consumption are not the same event

17. FX provider choice for FlyMax

17.1 What FX provider is for

Use the FX provider for:

  • local-currency display
  • indicative customer-facing conversions
  • internal non-settlement reporting views

17.2 What FX provider is not for

Do not use it as the final truth for:

  • gateway settlement
  • supplier credit deduction
  • BSP statement math
  • refund/dispute settlement reconstruction

18. XE and alternatives comparison

Pricing snapshot rule: re-check before procurement. Public pricing/features can change.

Provider Entry Paid Price Free Plan Typical Update Cadence Notable Features Advantages Disadvantages Compatibility / Migration View Best Fit
XE High. Public entry pricing materially above low-cost alternatives; typically annual-first Trial / limited entry path, not a real forever-free developer tier Daily to higher-frequency depending on plan historical data, averages, volatility-style datasets, enterprise positioning, SDKs, XML/CSV-style support in broader platform context strong feature breadth; enterprise feel; mature brand expensive; annual-first billing; weaker value for simple display FX use cases easiest if app is already built tightly around XE-specific shapes/features teams already committed to XE or using its broader enterprise-oriented feature set
Open Exchange Rates Low paid entry Small free plan Hourly on lower tiers; faster on higher tiers latest, historical, time series, base currency options on paid plans best all-round display FX replacement; strong balance of cost + depth not settlement-grade truth; some useful features gated to higher tiers low-to-medium migration effort; clean JSON; strong general replacement best overall replacement for FlyMax display FX
ExchangeRate-API Very low paid entry Useful free plan Daily free; hourly paid; faster on higher tiers latest, pair conversion, historical, straightforward JSON APIs cheapest serious paid option; simple; good for production display FX less feature depth than XE; indicative-only model low migration effort for standard latest/convert/history use best low-cost option
Fixer Low-to-medium paid entry Very small free plan Hourly free; faster paid tiers latest, convert, historical, time series, fluctuation decent endpoint breadth; faster updates available overage-fee risk; packaging less attractive than OXR/ExchangeRate-API medium migration effort; workable but not my first choice usable alternative if endpoint set fits and spend is controlled

19. FX provider recommendation

Open Exchange Rates for display FX.

Why

  • good price/feature balance
  • enough depth for search/result display
  • suitable for hourly refresh
  • strong replacement candidate if current XE usage is mostly latest/historical conversion for app display

Budget-first alternative

ExchangeRate-API

Why

  • lowest-cost practical replacement
  • simple production use
  • good if the app does not need deeper XE-style extras

When to keep XE

Keep XE only if you truly rely on:

  • XE-specific feature set
  • enterprise integration style
  • features beyond normal app display FX needs

20. Compatibility notes for current XE users

20.1 Easy migration cases

If the current app uses XE mainly for:

  • latest rates
  • simple conversions
  • historical lookups
  • local display price rendering

then migrating to OXR or ExchangeRate-API is straightforward with an adapter layer.

20.2 Harder migration cases

Migration is harder if the app relies on:

  • XE-specific response shapes
  • XML/CSV format dependencies
  • XE-specific enterprise tooling
  • advanced rate packaging assumptions

In that case:

  • keep the internal FX abstraction layer
  • switch providers behind the abstraction gradually
  • run parallel comparison before full cutover
  1. Build Money / FX abstraction layer
  2. Build checkout quote service
  3. Build payment intent + webhook handling
  4. Build credit ledger hold/release/consume
  5. Build booking orchestrator
  6. Build financial link / reconciliation model
  7. Build exception console
  8. Build statement import + final reconciliation workflows
  9. Add dashboards / reporting / alerts

22. Admin and operations screens required

22.1 Finance console

Must show:

  • payment captured but booking failed
  • booking succeeded but credit consume missing
  • unmatched supplier statement lines
  • refund pending with unresolved supplier-side impact
  • amount/currency mismatches
  • aging exceptions

22.2 Support / ops console

Must show:

  • booking timeline
  • payment timeline
  • credit movement timeline
  • supplier refs and payload refs
  • raw provider response links
  • retry/repair/escalation actions

23. Final decision summary

23.1 Core design decisions

Decision 1

FlyMax uses a two-ledger commercial model:

  • customer money ledger
  • supplier credit ledger

Decision 2

Display FX provider is not settlement truth.

Decision 3

Use:

  • FX provider for display
  • gateway for customer payment truth
  • aggregator/BSP/IATA statements for supplier funding truth
  • internal FlyMax ledger as the authoritative business truth

Decision 4

Use hourly FX refresh for browsing and locked quotes for checkout.

Decision 5

Always reprice / validate before payment-booking commit.

Decision 6

Use append-only event/movement ledgers, not balance-only models.

Decision 7

Build reconciliation as a first-class domain, not as a reporting afterthought.

Display FX recommendation

Open Exchange Rates

Budget alternative

ExchangeRate-API

Keep XE only if

Its extra enterprise-specific value is actually being used and justified.

24. One-sentence mental model

Customer pays FlyMax, FlyMax books using supplier credits, and FlyMax’s internal reconciliation ledger becomes the real source of commercial truth by joining payment events, booking events, and credit movements.

25. Procurement / review checklist

Before final implementation or procurement:

  • confirm actual current pricing for XE and alternatives
  • confirm gateway presentment currencies per market
  • confirm supplier credit currency and settlement statement format
  • confirm BSP / aggregator reconciliation fields available
  • define refund policy across customer money and supplier credit
  • define exception ownership between Support, Finance, and Ops
  • define reporting currency policy
  • define audit retention policy
  • define idempotency key strategy across payment and booking boundaries

26. Notes for future expansion

Later, this model can be extended to:

  • multiple providers beyond Verteil
  • more payment rails
  • deeper self-service refund/change support
  • treasury / FX optimization layer
  • predictive reconciliation / ops tooling
  • AI assistance on top of stable operational truth

But those should come after the core payment-credit-booking-reconciliation model is stable.

  • Document ID: FLYMAX-05-Strategy-CURRENCY-FX-PAYMENT-CREDIT-RECONCILIATION-STRATEGY
  • Canonical Version: 1.0.0
  • Lifecycle: Active
  • Scope: Valid
  • Source of Truth: docs/
  • Related Change Ticket:
  • Last Reviewed On: 2026-04-02
  • Next Review Due: 2026-04-02

Approval Sign-off

Role Name Date Status
Product Owner Pending
Technical Lead / Solution Architect George Joseph Pending
Engineering Lead Pending
Commercial / Operations Pending

Document Lineage

  • Supersedes:
  • Superseded By:

Change Log

  • 1.0.0 (2026-04-02) - Added as a strategic planning baseline for currency, payment, credit-led booking, and reconciliation.
Last modified: Apr 2, 2026 by George Joseph (20b472c)