Skip to main content
The 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 with a Merchant ID (MID).
  • Your IP address registered with Fexco (DHS accepts connections only from pre-agreed IP addresses).
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.
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.For the full bit-level field reference, see ISO 8583 format reference.
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.
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.For the full bit-level field reference, see ISO 8583 format reference.
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 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.
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.
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.

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: 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.
Any additional fields included in the echo request are returned in the echo response.

Next steps