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: PSS (Passenger Service System); the airline reservation or host system that holds the ticket and performs the refund. Where the ticket is held in a GDS (Global Distribution System) such as Amadeus, Sabre or Travelport rather than an airline host, the same fields apply and the GDS performs the refund.

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: the total refund amount on the refund once it has been processed. It comes straight from the PSS response; Deal Engine does not recompute it.

Reconcile against the executed total refund amount, never against the quote.

Read the executed amounts back once the candidate reaches REFUNDED; the status written by the fulfillment engine. See Refund lifecycle & statuses for the status vocabulary (NEW / REVIEW / READY / REFUNDED / ERROR).

The read path is document(ticketNum) { quote { status fulfillment { fareToRefund taxesToRefund fareRulePenalty totalRefundAmount currency } } }; the same shape a synchronous createQuote returns. See API usage & integration §3.6.

Amount field glossary

Quote / refund candidate

Field	Meaning
`refundAmount`	Total estimated refund (fare + taxes − penalties)
`refundFareAmount`	Estimated fare portion, gross of penalty; the penalty is not yet deducted. Summing `refundFareAmount + refundTaxAmount` overstates the refund by the penalty.
`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`	Total refund amount (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.

Executed amounts

Four amounts describe an executed refund:

Amount	Meaning
Fare amount to refund	Fare portion of the refund
Tax amount to refund	Tax portion of the refund. Taxes are included by definition; per tax line, `willRefund` is the final inclusion flag
Penalty amount	Penalty withheld
Total refund amount	The authoritative executed figure; what actually refunded

All four are gross, and each stands alone. None of them is expressed net of another: the fare amount to refund is not net of the penalty, and the penalty amount is not already subtracted from the fare or tax amounts. Use the fare, tax and penalty amounts to explain the total; book the total refund amount.

Why quote and executed can differ

PSS 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: rounding is defined per currency: the PSS's FX service returns the rounding to apply for each currency. Your account may override it by market, by currency, or for a specific requirement, as agreed in your FSD.
Manual override: manuallyRefunded / manualTotalAmount supersede automated values when present.

Precedence, when both are present: book manualTotalAmount where manuallyRefunded is set; otherwise book the executed total refund amount. A populated manual override means the refund was settled outside the automated path.

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.