> ## 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 (ISO 8583)

> Send a DCC rate request to DHS using binary ISO 8583 messages over TCP.

The [ISO 8583](https://en.wikipedia.org/wiki/ISO_8583) option
uses binary-encoded messages conforming to ISO 8583:1987. This is the right choice if your payment stack
already speaks ISO 8583 and you want to avoid protocol
translation.

## Before you start

You need the following to request a DCC offer using ISO 8583:

* A DHS host IP address and ISO 8583 port number (8583 by
  default) provided by your Fexco project manager.
* 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).
* Your IP address registered with Fexco (DHS accepts connections
  only from pre-agreed IP addresses).

> [!NOTE]
>
> DHS listens on port 8583 for ISO 8583 connections. Each
> connection uses a dedicated thread. The socket times out after
> 5 seconds of inactivity by default.

## Send a DCC offer request

ISO 8583 messages are prefixed with a 2-byte binary message
length and a 5-byte Transport Protocol Data Unit (TPDU). If your
system does not use TPDU for routing, zero-fill all 5 bytes. DHS
swaps the source and destination addresses in the TPDU when
responding.

**Step 1**

### Build the request message

The card rate request uses Message Type Indicator (MTI)
`0904`. The merchant rate request also uses MTI `0904` but
with Processing Code `930000` and the foreign currency code
in bit 50 instead of the card BIN in bit 2.

The table below shows the key fields for a card rate
request.

| Component | Value |
| :- | :- |
| Message Length | 2-byte binary message length (excludes itself). |
| TPDU | 5-byte Transport Protocol Data Unit. |
| MTI | `0904` (request). |
| Bit 2 (Card ID) | Card BIN. 6 to 12 digits for currency recognition. 11 digits recommended for optimal precision. Requires a BCD length prefix. |
| Bit 3 (Processing Code) | `970000` for card rate, `930000` for merchant rate. BCD-encoded, no length prefix. |
| Bit 4 (Base Amount) | Transaction amount in minor units (optional). BCD-encoded, no length prefix. |
| Bit 37 (Reference Number) | 12-character unique transaction identifier. ASCII-encoded, fixed length. |
| Bit 42 (Merchant ID) | 15-character merchant identification number. ASCII-encoded, fixed length, right-justified and zero-filled. |
| Bit 48 (Acquirer ID) | Three-letter acquirer identification code. Requires a BCD length prefix. |

For the full bit-level field reference, see
[ISO 8583 format reference](https://docs.fexco.com/dcc/developer-resources/codes/field-mapping.md).

> [!NOTE]
>
> Numeric fields are BCD-encoded, right-justified, and
> zero-filled. Alphanumeric fields are ASCII-encoded. Variable-length
> fields (LLVAR/LLLVAR) require a BCD length prefix that specifies the
> number of bytes that follow. Fixed-length fields (such as bit 42 Merchant
> ID) do not use a length prefix. The 64-bit bitmap in bit 1 indicates
> which fields are present in the message. The Base Amount (bit 4) must
> be in minor units per ISO 4217 (for example, `000000010000` for 100.00
> in a currency with 2 decimal places). See
> [Currency precision](https://docs.fexco.com/dcc/developer-resources/codes/currency-precision.md).

**Step 2**

### Read the response fields

The card rate response uses MTI `0914`. Check bit 39
(Response Code) first. A value of `00` means success.
The table below shows the key response fields.

| Component | Value |
| :- | :- |
| Bit 39 (Response Code) | `00` means success. |
| Bit 44 (DCC Offered) | `TRUE` or `FALSE`. |
| Bit 5 (Foreign Amount) | Converted amount in minor units (when DCC is offered and base amount was provided). |
| Bit 50 (Foreign Currency Code) | Three-digit ISO 4217 currency code. |
| Bit 55 (Exchange Rate) | Exchange rate for the conversion. |
| Bit 56 (Rate Source Name) | Rate source name for receipt printing. |
| Bit 58 (Margin Rate Percentage) | Markup applied to the wholesale rate. |

For the full bit-level field reference, see
[ISO 8583 format reference](https://docs.fexco.com/dcc/developer-resources/codes/field-mapping.md).

**Step 3**

### Validate and act on the response

Before presenting a DCC offer to the cardholder, validate
the response in the following order:

1. Confirm that the Reference Number (bit 37) in the response
   matches your request.
2. Check the Response Code (bit 39). A value of `00` means the
   request was processed successfully. Any other value
   indicates an error. See
   [Error handling](https://docs.fexco.com/dcc/api-reference/error-handling.md) for the
   full list of response codes.
3. Check the DCC Offered field (bit 44). If `TRUE`, use the
   exchange rate, foreign amount, margin, and rate source
   fields to display the DCC choice to the cardholder. If
   `FALSE`, process the transaction in the merchant's base
   currency.

> [!TIP]
>
> The response code is `00`, DCC Offered is `TRUE`, and the
> exchange rate and foreign currency code fields are present.
> If the response code is not `00` or DCC Offered is `FALSE`,
> see
> [Troubleshoot rate service errors](https://docs.fexco.com/dcc/guides/rate-service/troubleshoot.md).

**Step 4**

### Present the offer to the cardholder

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

* The transaction amount in the merchant's base currency
  (bit 4).
* The converted amount in the cardholder's currency
  (bit 5, Foreign Amount).
* The exchange rate (bit 55).
* The margin percentage (bit 58).
* The rate source and timestamp (bit 56, bit 57).

The cardholder must accept or decline before the rate
expires. The Valid Hours field (bit 60) indicates how long
the rate remains valid. 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).

## Keep the connection alive with echo messages

The socket times out after 5 seconds of inactivity. To keep a
connection open between rate requests, send an echo request
(network management message) at intervals shorter than the
timeout, for example every 3 to 4 seconds.

The echo request uses MTI `0800` with Network Management
Information Code `301`. The following fields are required:

| Component | Value |
| :- | :- |
| MTI | `0800` (network management request). |
| Bit 7 (Transmission Date and Time) | `MMDDhhmmss` format. |
| Bit 11 (System Trace Audit Number) | 6-digit trace identifier. |
| Bit 70 (Network Management Info Code) | `301` (echo). |

Bit 42 (Merchant ID) and bit 48 (Acquirer ID) are optional in
the echo request. The server responds with MTI `0810` and
includes a Response Code (bit 39) of `00` for success.

> [!NOTE]
>
> Any additional fields included in the echo request are returned
> in the echo response.

## Next steps

* [Handle rate expiry](https://docs.fexco.com/dcc/guides/rate-service/rate-expiry.md):
  understand what happens when a rate offer expires and how to
  handle it.
* [Handle domestic and unsupported cards](https://docs.fexco.com/dcc/guides/rate-service/domestic-unsupported.md):
  manage transactions where DCC cannot be offered.
* [Troubleshoot rate service errors](https://docs.fexco.com/dcc/guides/rate-service/troubleshoot.md):
  resolve common DHS error responses.


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