# Cardholder FX Disclosure
source: https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/use-cases/cardholder-fx-disclosure/index.md

## Context {#context}

An issuer needs to show a cardholder the applicable foreign exchange rate, and the mark-up between that rate and the ECB reference rate, at the point they view or confirm a cross-border/cross-currency card transaction --- the disclosure required under EU Regulation 2019/518.

## Goal {#goal}

Retrieve, in a single call, the Mastercard conversion rate, the calculated cardholder billing amount, the matching ECB reference rate, and the percentage difference between them for the transaction's currency pair and date.

## Actors {#actors}

* **Cardholder** --- views or confirms the transaction and is shown the FX disclosure.
* **Issuer User Interface** --- collects transaction currency, amount, billing currency, and any issuer fee.
* **Issuer Server** --- calls the Enhanced Currency Conversion Calculator API on the cardholder's behalf.
* **Conversion Rate Service** --- the Enhanced Currency Conversion Calculator API's `Conversion-rate-summary` service.

## Preconditions {#preconditions}

* The issuer has a valid Mastercard Developers project with OAuth 1.0a credentials (see [Quick Start Guide](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/quick-start-guide/index.md)).
* The transaction currency, cardholder billing currency, transaction amount, and rate date are known.

## Outcome {#outcome}

The cardholder is shown the Mastercard exchange rate, the ECB reference rate, and the percentage mark-up between them --- satisfying the EU 2019/518 disclosure requirement.

## How It Works {#how-it-works}

1. The cardholder enters or confirms transaction details (transaction currency and amount) in the issuer's website or mobile app.

   Tip: Use `GET /mc-currencies` or `GET /ecb-currencies` to populate a drop-down of valid currencies --- see [Populating Currency Selection Lists](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/use-cases/currency-selection-lists/index.md).
2. The issuer validates the input and populates the cardholder billing currency and any bank fee, either from the cardholder's profile or by asking the cardholder directly.

3. The issuer's server calls `GET /summary-rates`, passing `rate_date`, `trans_curr`, `trans_amt`, `crdhld_bill_curr`, and, if applicable, `bank_fee_pct` and `bank_fee_fixed`. This is the only endpoint that returns the calculated mark-up percentage needed for the disclosure --- `mc-currencies`, `ecb-currencies`, and `rate-statuses` return supporting lookups but not the rate comparison itself.

   Tip: Before relying on today's rates, you can call `GET /rate-statuses` first --- see [Checking Daily Rate Availability](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/use-cases/rate-availability-check/index.md).
4. The Conversion Rate Service looks up the Mastercard rate for the currency pair and sources the matching ECB reference rate.

5. The Conversion Rate Service returns:

   * Mastercard currency conversion rate (`mastercardConvRateInclPctFee` / `mastercardConvRateExclAllFees`)
   * Cardholder billing amount with and without issuer fees (`crdhldBillAmtInclAllFees` / `crdhldBillAmtExclAllFees`)
   * ECB reference rate (`ecbReferenceRate`)
   * Effective exchange rate including all fees (`effectiveConversionRate`)
   * Percentage difference between Mastercard and ECB rates, with and without fees (`pctDifferenceMastercardInclAllFeesAndEcb` / `pctDifferenceMastercardExclAllFeesAndEcb`)
6. The issuer's server passes the applicable fields to the user interface for display to the cardholder.

Diagram cardholder-fx-disclosure Note: As an alternative to calling the API for every transaction, you can call it up to twice per day (once Mastercard rates are updated and once ECB rates are updated) per desired currency pair, and internalize the rate information for cardholder presentment until the next day's rates are published.

## Endpoint Reference {#endpoint-reference}


API Reference: `GET /summary-rates`

## Next Steps {#next-steps}

|                                                            Category                                                            |                     Description                     |
|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| [Testing](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/testing/index.md)             | Positive and negative test cases for this endpoint. |
| [API Reference](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/api-reference/index.md) | Try the Sandbox API directly from your browser.     |
| [Support](https://developer.mastercard.com/enhanced-currency-conversion-calculator/documentation/support/index.md)             | FAQs and support.                                   |