> ## 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 Connect)

> Check card eligibility and get a Dynamic Currency Conversion (DCC) rate offer using the Rate Service Connect API.

Rate Service Connect uses a single endpoint,
[Create DCC Rate Offer](https://docs.fexco.com/api-reference/dcc-rate-offers/create-dcc-rate-offer.md),
for all DCC rate requests regardless of channel (POS, ATM, or
e-commerce) or transaction type (purchase, refund,
pre-authorization, and others). The transaction details are sent
as a JSON body, and the merchant and acquirer are identified
through request headers.

Unlike Rate Service Classic, Rate Service Connect authenticates every request with a
JSON Web Token (JWT) signed using your private key. It also
returns ready-to-use `offerText` and `receiptText` fields, so
you do not need to build the cardholder prompt or receipt line
yourself.

## Before you start

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

* A signed client certificate and private key for JWT
  construction. See
  [Certificate and JWT authentication](https://docs.fexco.com/dcc/api-reference/authentication/jwt-pki.md).
* Your acquirer ID (three-letter code assigned by Fexco).
* A card acceptor ID (merchant ID) for a boarded merchant.
  See [How merchant boarding works](https://docs.fexco.com/dcc/guides/merchant-boarding/how-it-works.md).
* The Rate Service Connect base URL for your environment. See
  [Environments](https://docs.fexco.com/dcc/api-reference/environments.md).

## Send a DCC offer request

The steps below cover building the request, reading the
response, and presenting the offer to the cardholder. For the
full list of parameters, response fields, and transaction types,
see
[Create DCC Rate Offer](https://docs.fexco.com/api-reference/dcc-rate-offers/create-dcc-rate-offer.md)
in the API reference.

**Step 1**

### Build and send the request

Send a `POST` request to the
[Create DCC Rate Offer](https://docs.fexco.com/api-reference/dcc-rate-offers/create-dcc-rate-offer.md)
endpoint with the required headers and a JSON body
containing the card Bank Identification Number (BIN),
transaction amount, and transaction type. Replace the
placeholder values with your own.

The example below uses the `PURCHASE` transaction type.
Rate Service Connect also supports `REFUND`, `CASH_ADVANCE`,
`REVERSAL`, `PREAUTHORIZATION`,
`INCREMENTAL_AUTHORIZATION`, and
`COMPLETE_AUTHORIZATION`. See the
[API reference](https://docs.fexco.com/api-reference/dcc-rate-offers/create-dcc-rate-offer.md)
for details on each type.

The `posEntryMode` value is a three-character code defined
by [ISO 8583](https://en.wikipedia.org/wiki/ISO_8583)
that indicates how the card number was captured and the
PIN entry capability of the terminal. In the example
below, `079` means ICC with no PIN entry capability
specified.

> [!NOTE]
>
> For ATM integrations, the `amount` value must include
> both the withdrawal amount and any access fee charged
> to the cardholder.

```bash title="Request" theme={null}
curl -X POST \
  "https://YOUR_DHS_HOST/dcc/offers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "x-acquirer-id: YOUR_ACQUIRER_ID" \
  -H "x-card-acceptor-id: YOUR_CARD_ACCEPTOR_ID" \
  -d '{
    "referenceCode": "TXN-2026-001234",
    "transactionType": "PURCHASE",
    "paymentDetails": {
      "bin": "409019",
      "cid": "111",
      "posEntryMode": "079"
    },
    "orderDetails": {
      "amount": "100",
      "fee": "2.5",
      "currency": "EUR"
    },
    "terminalInformation": {
      "terminalId": "TERM001234",
      "terminalType": "POS"
    }
  }'
```

```json title="Response (201, test data)" theme={null}
{
  "id": "f3f48451-8c53-460e-8f6b-85df444907c1",
  "referenceCode": "TXN-2026-001234",
  "baseAmount": "100",
  "foreignAmount": "10",
  "foreignFeeAmount": "0.25",
  "foreignTotalAmount": "10.25",
  "exchangeRate": {
    "baseCurrency": { "alphaCode": "USD", "minorUnits": 2 },
    "foreignCurrency": { "alphaCode": "EUR", "minorUnits": 2 },
    "rate": "0.1012",
    "marginPercentage": "4.5",
    "source": "REUTERS WHOLESALE INTERBANK",
    "sourceTimestamp": "2026-07-12T11:20:13Z",
    "expiry": "2026-10-08T14:35:00Z"
  },
  "offerText": "Do you wish to proceed with currency conversion at rate 0.1? I will pay 10.00 EUR instead of 100.00 USD.",
  "receiptText": "Currency conversion applied: 100 USD = 10 EUR at rate 0.1.",
  "issueAt": "2026-10-29T11:15:11Z"
}
```

The `offerText` field contains the DCC choice to present
to the cardholder, and `receiptText` contains the
DCC-compliant line for the printed receipt. Both are
ready to use without additional formatting.

The `currency` field uses an
[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
alphabetic currency code (for example, `EUR`, `USD`,
`GBP`).

For the complete list of response fields, see
[Create DCC Rate Offer](https://docs.fexco.com/api-reference/dcc-rate-offers/create-dcc-rate-offer.md)
in the API reference.

> [!TIP]
>
> A `201` response with `foreignAmount`, `offerText`, and
> `receiptText` means the card is eligible for DCC. Proceed
> to step 2. If the response is a `400` with an error code,
> the card is not eligible. Process the transaction in the
> merchant's base currency instead. See
> [Handle domestic and unsupported cards](https://docs.fexco.com/dcc/guides/rate-service/domestic-unsupported.md)
> and
> [Troubleshoot rate service errors](https://docs.fexco.com/dcc/guides/rate-service/troubleshoot.md).

**Step 2**

### Present the offer to the cardholder

Use the `offerText` field to display the DCC choice to the
cardholder. The cardholder must accept or decline before
the `expiry` timestamp in the `exchangeRate` object. 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).

If the cardholder accepts, use the `receiptText` field for
the DCC-compliant receipt line.

## Next steps

* [Certificate and JWT authentication](https://docs.fexco.com/dcc/api-reference/authentication/jwt-pki.md):
  review the certificate request process and JWT construction if
  you have not completed authentication setup.
* [Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md):
  understand how to handle expired offers and when to request a
  new one.
* [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.


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