Refund amounts & reconciliation

Which amount is authoritative, what each field means, and why an estimate and the final executed amount can differ.

Terms used below: GDS/PSS (Global Distribution System / Passenger Service System) — the airline reservation or host system (Amadeus, Sabre, Galileo, and airline PSS) that holds the ticket and performs the refund. BSP (Billing and Settlement Plan) — the IATA settlement layer between airline and agency.

Quote vs. executed amount

Quote amount — an estimate. createQuote projects the refund from fare rules, taxes, and penalties. No money has moved.
Executed amount — the authoritative figure, recorded when the refund is processed and exposed as Document.refund.total. It comes straight from the GDS/PSS/BSP response; Deal Engine does not recompute it.

Reconcile against Document.refund.total, never against the quote.

Amount field glossary

Quote / refund candidate

Field	Meaning
`refundAmount`	Total estimated refund (fare + taxes − penalties)
`refundFareAmount`	Estimated fare portion
`refundTaxAmount`	Estimated tax portion
`refundPenaltyAmount`	Estimated penalty withheld
`refundableBaseFareAmount`	Refundable base fare before penalties
`secondPenaltyAmount`	Second penalty component, where fare rules define one

Fulfillment

Field	Meaning
`fareToRefund`	Fare to refund
`taxesToRefund`	Taxes to refund
`fareRulePenalty`	Penalty deducted from fare
`vatOnPenalty`	VAT on the penalty
`serviceFee`	Service fee deducted from taxes
`totalRefundAmount`	Net refund (formula below)

totalRefundAmount = max(0, fareToRefund − fareRulePenalty)
                  + max(0, taxesToRefund − vatOnPenalty − serviceFee)

Each side floors at zero — a penalty larger than the fare can't produce a negative component.

`unifiedRefund` (executed view on a `Document`)

Field	Meaning
`totalRefund`	Total refunded — the executed figure
`totalFare`	Fare portion
`totalTax`	Tax portion
`totalPenalty`	Penalty withheld

Why quote and executed can differ

GDS/PSS/BSP recalculation — the airline recalculates taxes and penalties at execution time.
FX date — currency conversion uses a rate tied to a date; quote and execution can fall on different dates.
Rounding at quote time.
Manual override — manuallyRefunded / manualTotalAmount supersede automated values when present; treat them as the source of truth.

Differences are typically a few minor currency units and expected. Reconciling against the executed total absorbs them.

Form of payment

Default: one aggregate refund amount. A per-FoP breakdown is available via Quote.fopInfo[] when FoP distribution is enabled for your account:

Field	Meaning
`fopType`	Payment type (e.g. card, cash)
`brand`	Card brand
`cardNumber`	Masked card number
`amount`	Amount refunded to this FoP
`currencyCode`	Currency

FoP distribution is opt-in per account. Confirm with Deal Engine whether it is enabled for yours before relying on fopInfo[]; without it you receive aggregates only.

Do not use cardRefund / cashRefund on AmountsSummary — they always return 0 and are pending deprecation.

Miles / award tickets

The mile-denominated fare is not refunded through Deal Engine — only the monetary taxes are quoted and refunded (decision reason: VOLUNTARY MILES). Mile reinstatement happens in the airline's loyalty programme, outside Deal Engine.