> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the rate service works

> An overview of the rate service concepts, what a rate offer contains, where wholesale rates come from, and how environments are set up.

The rate service is the real-time API an acquirer calls to get a foreign exchange rate for a currency pair at the moment of payment. This page covers the core concepts, what a rate offer contains, where rates come from, how a request flows end to end, and how environments are set up.

## Prerequisites

Before reading this page, make sure you are familiar with:

* The [**What is DCC**](https://docs.fexco.com/dcc/guides/getting-started/what-is-dcc.md) page to understand the actors involved and the end-to-end DCC lifecycle.

For field-by-field request and response details, see the guide for the API you are integrating with:

* [Rate Service Classic](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-rate-service-classic.md)
* [Rate Service Connect](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-rate-service-connect.md)
* [ISO 8583](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-iso.md)

## What a rate offer contains

Regardless of which API you use, a rate offer is built from the same set of concepts:

| Concept | What it means |
| - | - |
| Eligibility | The card BIN, scheme, and currency determine whether DCC can be offered at all. If a card is not eligible, the API signals that no offer is available rather than returning an offer with zero values. See the [Error Handling](https://docs.fexco.com/dcc/api-reference/error-handling.md) page for more details. |
| Amount conversion | A base amount in the merchant currency is converted to a foreign amount in the cardholder's currency, using an exchange rate. |
| Margin | A markup applied over the wholesale exchange rate. The margin is returned alongside the offer for receipt printing and regulatory purposes. |
| Rate source and timestamp | Identifies where the underlying wholesale rate came from and when it was sourced. |
| Expiry | The window during which the offer is valid. The cardholder must accept or decline before it expires. |

## Where rates come from

Fexco sources wholesale exchange rates from leading financial data providers, applies a margin that is bespoke per acquirer, merchant or ATM, and currency, and uploads the resulting rates several times throughout each trading day.

## How a rate request flows end to end

A DCC transaction moves through the same sequence regardless of which rate API the acquirer uses:

1. **The acquirer sends a rate request**: At the moment of payment, the terminal or host calls the rate service with the card BIN (minimum 9 digits recommended for accurate currency recognition), the base transaction amount, and the merchant currency, identified by the acquirer ID and merchant ID issued during boarding.
2. **Fexco checks eligibility**: The BIN, card scheme, and currency are evaluated to determine whether DCC can be offered.
3. **Fexco builds the offer**: Using the most recently sourced wholesale rate, the service converts the base amount into the cardholder's currency and applies the applicable margin.
4. **The offer is returned to the terminal**: The response includes the converted amount, the exchange rate, the margin, and the expiry window during which the offer remains valid.
5. **The cardholder accepts or declines**: This happens locally, between the terminal and the cardholder, before the offer expires.
6. **The acquirer reports the outcome**: Separately from the rate request, the acquirer submits transaction files that report which offers cardholders actually accepted.
7. **Settlement follows**: Those transaction files drive settlement and commission calculation. See [Settlement and commission](https://docs.fexco.com/dcc/guides/transaction-import/settlement.md) for that process.

> [!NOTE]
>
> Refunds are not covered by the original rate offer. When a refund is processed, it uses the prevailing rate at the time of the refund, not the rate from the original transaction.

The following diagram shows who talks to whom at each step.

Click each step to walk through a rate request

## Pre-authorisation and completion

The flow above covers single, immediate purchases. Pre-authorisation scenarios, such as hotel check-ins or car rentals where the final amount is not known upfront, follow a different pattern.

### Exchange rate handling

The exchange rate is **not** locked at pre-authorisation. A new rate request is made for each subsequent stage of the transaction:

* **Incremental authorisations** (for example, adding room charges to a hotel stay) each require a new rate request.
* **Completion** (the final charge at check-out) also requires a new rate request. The rate used at completion is the prevailing rate at that time, not the rate from the original pre-authorisation.

### Tips and amount changes

When the final amount includes a tip or other adjustment, the sale amount and the tip are converted together at a single rate. There is no separate conversion for the tip.

### Offer ID

The offer ID from each rate request is carried in the `rateOfferRef` field in the transaction file. Each new rate request produces a new `rateOfferRef` value, so the completion record references the rate used at completion, not the rate from the original pre-authorisation.

### Rate expiry

Because a new rate is obtained at each stage, rate expiry does not affect the completion. However, if the cardholder does not respond before the expiry window closes on any individual rate offer, a new rate request is required before proceeding. See [Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md) for details.

## Environments

Base URLs are customer-specific. Fexco does not publish fixed public endpoints. Your Fexco project manager issues your production URLs, acquirer ID, and merchant IDs as part of setup.

> [!NOTE]
>
> No self-service sandbox environment is available for any of the rate APIs. Once you complete early onboarding, Fexco provides a certification environment where you can send real requests and compare responses against the examples on this portal. For Rate Service Connect, testing is currently limited to curated OpenAPI request and response examples.

## Next steps

* [Choose a rate API](https://docs.fexco.com/dcc/guides/rate-service/choose-rate-api.md): compare Rate Service Classic, ISO, and Rate Service Connect to decide which to integrate against.
* [Request a DCC offer (Rate Service Classic)](https://docs.fexco.com/dcc/guides/rate-service/dcc-offer-rate-service-classic.md): build a rate request against Rate Service Classic.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.