> ## 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.

# Request a DCC offer (Rate Service Classic)

> Use the Rate Service Classic API to check card eligibility and get a Dynamic Currency Conversion (DCC) rate offer.

The Rate Service Classic API lets you request a DCC rate offer for a specific
transaction at the moment of payment. You send a `GET` request
with the card Bank Identification Number (BIN), the transaction
amount, and the merchant or ATM identifier. DHS (Dynamic Host
Server) checks whether the card is eligible for DCC and returns
the converted amount, exchange rate, and margin.

This guide covers the primary DCC use case: requesting a rate
offer for a single transaction using a BIN and base amount. For
retrieving exchange rates in bulk for multi-currency pricing
(MCP), see
[Request MCP exchange rates](https://docs.fexco.com/dcc/guides/rate-service/mcp-rate.md).

## Before you start

You need the following to request a DCC offer using Rate Service Classic:

* A DHS host URL provided by your Fexco project manager. See
  [Environments](https://docs.fexco.com/dcc/api-reference/environments.md) for the full
  list of base URLs and certificate endpoints.
* An acquirer ID (three-letter alphabetic code assigned by Fexco).
* At least one
  [boarded merchant](https://docs.fexco.com/dcc/guides/merchant-boarding/board-api.md)
  with a merchant ID (MID). In Fexco's systems, the MID
  corresponds to the Merchant Originator Tag.

## Request a rate offer

The following steps walk through a single-card DCC offer request
for a merchant. For ATM integrations, use the ATM variant of the
endpoint (`/acquirers/{acquirerId}/atms/{atmId}/dccoffers`).
For the full list of parameters and response fields, see
[Request a DCC offer](https://docs.fexco.com/api-reference/v2--merchant--dcc-rate-offer/request-a-dcc-offer)
in the API reference.

**Step 1**

### Send the request

Send a `GET` request to the
[Request a DCC offer](https://docs.fexco.com/api-reference/v2--merchant--dcc-rate-offer/request-a-dcc-offer)
endpoint with the following parameters:

1. In the URL path, replace `TST` with your acquirer ID
   and `11111111` with your merchant ID.
2. Set `bin` to the first 11 digits of the card number.
3. Set `baseamount` to the transaction amount in the
   merchant's base currency, including the decimal point
   (for example, `123.45`).
4. Set `posentrymode` to the terminal's POS entry mode.

The `posentrymode` value is a three-character code defined
by [ISO 8583](https://en.wikipedia.org/wiki/ISO_8583). The first two digits indicate how the card
number was captured (for example, `07` for contactless ICC
EMV), and the third digit indicates PIN entry capability
(for example, `1` for PIN capable). In the example below,
`071` means contactless ICC EMV with PIN entry capability.

> [!NOTE]
>
> Fexco recommends sending 11 digits in the `bin` field
> for optimal accuracy in card currency recognition. If
> your integration captures fewer than 11 digits, you can
> send the first 6 digits in `bin` and the remaining
> digits (up to 6 more) in the optional `cid` (Currency
> ID) parameter. See the
> [API reference](https://docs.fexco.com/api-reference/v2--merchant--dcc-rate-offer/request-a-dcc-offer)
> for details.

```bash title="Request" theme={null}
curl -X GET \
  "https://YOUR_DHS_HOST/dhsv2/acquirers/TST/merchants/11111111/dccoffers?bin=41017212345&baseamount=123.45&posentrymode=071"
```

```json title="Response" theme={null}
{
  "baseAmount": "123.45",
  "foreignAmount": "169917.81",
  "exchangeRate": {
    "baseCurrency": {
      "alphaCode": "GBP",
      "minorUnits": 2
    },
    "foreignCurrency": {
      "alphaCode": "USD",
      "minorUnits": 2
    },
    "rate": "1376.4100",
    "marginPercentage": "3",
    "source": "REUTERS WHOLESALE INTERBANK",
    "sourceTimestamp": "2023-07-12T11:20:13.000+0000",
    "expiry": "2099-07-14T11:20:13.000+0000"
  },
  "bin": {
    "number": "410172*****",
    "currency": { "alphaCode": "USD" },
    "schemeCode": 1
  }
}
```

> [!TIP]
>
> A response with `foreignAmount` and `exchangeRate` means
> the card is eligible for DCC. Proceed to step 2. If the
> response body is empty (`{}`), the card is not eligible.
> Charge in the merchant's local currency instead. See
> [Handle domestic and unsupported cards](https://docs.fexco.com/dcc/guides/rate-service/domestic-unsupported.md).

**Step 2**

### Read the response fields

When the card is eligible for DCC, the response contains the
exchange rate and converted amount you need to present the
cardholder with their payment options. The table below
describes the key fields in the response:

| Field | What it contains |
| :- | :- |
| `baseAmount` | The transaction amount in the merchant's base currency. |
| `foreignAmount` | The converted amount in the cardholder's currency. |
| `exchangeRate.rate` | The exchange rate used for the conversion. |
| `exchangeRate.marginPercentage` | The markup applied to the wholesale rate. Required for receipt printing. |
| `exchangeRate.source` | The rate source name. Required for receipt printing. |
| `exchangeRate.sourceTimestamp` | When the rate was sourced. Required for receipt printing. |
| `exchangeRate.expiry` | The deadline for the cardholder to accept or decline the offer. |

For the complete field reference, see
[Request a DCC offer](https://docs.fexco.com/api-reference/v2--merchant--dcc-rate-offer/request-a-dcc-offer)
in the API reference.

**Step 3**

### Present the offer to the cardholder

Display the DCC offer to the cardholder so they can choose
to pay in their home currency or the merchant's local
currency. The offer must include the following information
for regulatory compliance:

* The transaction amount in the merchant's base currency
  (`baseAmount`).
* The converted amount in the cardholder's currency
  (`foreignAmount`).
* The exchange rate (`exchangeRate.rate`).
* The margin percentage (`exchangeRate.marginPercentage`).
* The rate source and timestamp
  (`exchangeRate.source`, `exchangeRate.sourceTimestamp`).

The cardholder must accept or decline before the `expiry`
timestamp. If the offer expires before the cardholder
responds, discard it and request a new one. See
[Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md).

## Next steps

* [Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md):
  understand what happens when a DCC offer expires and how to
  handle it.
* [Handle domestic and unsupported cards](https://docs.fexco.com/dcc/guides/rate-service/domestic-unsupported.md):
  manage the no-offer scenario when a card is not eligible for
  DCC.
* [Request MCP exchange rates](https://docs.fexco.com/dcc/guides/rate-service/mcp-rate.md):
  retrieve bulk exchange rates for multi-currency pricing.
* [Troubleshoot rate service errors](https://docs.fexco.com/dcc/guides/rate-service/troubleshoot.md):
  resolve common Rate Service Classic error responses.


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