Skip to main content
Use this page when a rate request fails, returns unexpected results, or DCC is not offered when you expect it to be. Find your problem below and follow the steps to resolve it.

Before you troubleshoot

Before you troubleshoot a specific error, run through these checks:
  • Confirm you are using the correct environment (production or cert). See Environments and URLs.
  • Verify your acquirer ID and merchant ID match the values provided by Fexco.
  • Check that the request URL or message does not contain typos, double slashes, or missing path segments.
  • For Rate Service Classic, verify that DHS is active by sending a heartbeat request:
    A successful response returns {"ok": true}. If the heartbeat fails, DHS may be unavailable. Contact your Fexco project manager.

DCC offer not returned for a card

The following results are not errors. They mean DHS processed the request but the card is not eligible for DCC. In each case, process the transaction in the merchant’s base currency.
The Rate Service Classic API returns HTTP 200 with an empty JSON body ({}).

Why this happens

An empty response means DHS processed the request but the card is not eligible for DCC. Common reasons include:
  • The BIN or card number is not recognized as a foreign card.
  • The card is ineligible for DCC under card scheme rules.
  • The card currency is not supported by the merchant’s DCC configuration.
  • The card scheme is not allowed for the merchant ID.
  • No rates are available for the specified merchant ID or currency.

How to fix

No corrective action is needed. Process the transaction in the merchant’s base currency. See Handle domestic and unsupported cards for guidance on what to display to the cardholder.
The ISO API returns response code 22, or Rate Service Connect returns error code 22 with the message “Domestic Card, DCC not available.”

Why this happens

The merchant’s base currency matches the cardholder’s card currency. DCC only applies when the card currency is different from the merchant’s settlement currency.

How to fix

No corrective action is needed. Process the transaction in the merchant’s base currency without offering DCC.
The ISO API returns response code 5, or Rate Service Connect returns error code 5.

Why this happens

This code is returned in either of the following cases:
  • DHS could not determine the currency of the card from the BIN provided. The card may be from an issuer whose BIN range is not in the DHS database.
  • The card is ineligible for DCC under card scheme rules. This includes cards or accounts identified in the Mastercard Parameter Extract (MPE) as ineligible for point of interaction (POI) currency conversion, Visa account ranges enabled with the Visa Multi-Currency Solution, and travel prepaid cards such as Visa TravelMoney.

How to fix

  1. Confirm that the BIN contains at least 6 digits and that the value is correct. Fexco recommends submitting 11 digits where available for optimal accuracy.
  2. If you are sending only 6 digits in the BIN field, add the remaining card digits (7 to 11) in the cid parameter (Rate Service Classic and Rate Service Connect) or the CID tag (ISO).
  3. If the card remains unrecognized after verifying the BIN, process the transaction in the merchant’s base currency. Not all card issuers are supported for DCC, and cards excluded under card scheme rules are not eligible.
The ISO API returns response code 8, or Rate Service Connect returns error code 8.

Why this happens

The card scheme is not supported for DCC. DCC is available only for Visa, Mastercard, and Maestro payment cards.

How to fix

No corrective action is needed. Process the transaction in the merchant’s base currency. Cards from other schemes (for example, AMEX, Diners, JCB) are not eligible for DCC.
The ISO API returns response code 97, or Rate Service Connect returns error code 97.

Why this happens

The transaction amount is at or below the contactless Transaction Lower Limit (TLL) configured for the merchant. The TLL is an optional per-MID setting that prevents DCC from being offered on low-value contactless transactions. This applies only when the posentrymode value indicates a contactless transaction (PAN capture method 07 or 91).

How to fix

No corrective action is needed for the current transaction. Process it in the merchant’s base currency. If you believe the TLL threshold is set too high for your use case, contact your Fexco project manager to adjust it.
The ISO API returns response code 99, or Rate Service Connect returns error code 99.

Why this happens

DHS recognized the card as a foreign card, but the specific currency of the card is not supported for DCC by the merchant’s configuration.

How to fix

Process the transaction in the merchant’s base currency. If you expect this currency to be supported, verify the merchant’s DCC configuration with your Fexco project manager.

Request fails or returns an error

The Rate Service Classic API returns HTTP 400 with the message “You have to specify ‘baseamount’”.

Why this happens

The dccoffers resource was called without the required baseamount query parameter, or the parameter value is empty. For ISO, the equivalent is response code 10 (Invalid Base Amount).

How to fix

Include baseamount in the query string with a valid numeric value in minor units per ISO 4217. The value must include the decimal point.
The ISO API returns response code 2 or 30. The REFERENCENUMBER in the response may contain Null.

Why this happens

The request message has structural or syntactical errors. XML tags may be missing, misspelled, or in the wrong case.

How to fix

  1. For XML over TCP/IP, verify that all tag names are uppercase (for example, CARDRATEREQUEST, BASEAMOUNT). Tag names are case-sensitive.
  2. Confirm that all mandatory fields are present. REFERENCENUMBER, CARDID, MERCHANTID, and ACQUIRER are mandatory for card rate requests. FGNCURCODE is mandatory for merchant rate requests.
  3. Validate your XML message against the card rate or merchant rate XSD provided by Fexco.
The Rate Service Classic API returns HTTP 404 with the message “No such Merchant”. For ISO, the equivalent is response code 4 (Unknown Acquirer or Merchant).

Common causes

  • The merchant ID is misspelled or incorrectly formatted.
  • The merchant has not been boarded or has been deactivated.
  • The acquirer ID does not match the boarded merchant’s acquirer.

How to fix

  1. Confirm that the $MERCHANT_ID in your request URL matches the Merchant Originator Tag (MID) assigned during boarding. The value is case-sensitive and alphanumeric, up to 16 characters.
  2. Confirm that the $ACQUIRER_ID matches the three-letter code assigned by Fexco. For Rate Service Classic, this is a path segment. For Rate Service Connect, this is the x-acquirer-id header.
  3. Verify that the merchant is active and has not been deactivated. See Reactivate a merchant if the merchant needs to be restored.

Request fails with authentication or connection error

The Rate Service Connect API returns HTTP 401 Unauthorized.

Common causes

  • The JWT token has expired. JWTs have a limited validity window.
  • The x-acquirer-id header does not match the Organisation (O) field in the client certificate.
  • The certificate used to sign the JWT has not been registered with Fexco.
  • The Authorization header format is incorrect. There must be exactly one space after Bearer.

How to fix

  1. Generate a new JWT using your current private key and client certificate. Ensure the token has not expired.
  2. Confirm that the x-acquirer-id header matches the Organisation (O) field in the client certificate you used to sign the JWT.
  3. Confirm that the certificate you are using was signed by Fexco and has not expired. See Certificate and JWT authentication for the full setup process.
The client sends an ISO 8583 rate request over an existing socket but receives no response. The read returns end of stream or fails with a connection reset error, and no DCC offer is presented.

Why this happens

DHS listens on port 8583 for incoming connection requests. Each time a client opens a connection, DHS creates a new socket, managed by a dedicated thread from a pool sized to handle simultaneous connections. The socket remains open and handles requests from the client until one of the following occurs:
  • Connection reset: the client explicitly closes its side of the connection.
  • Socket timeout: the client sends no data within the socket timeout window, and DHS closes the socket.
The socket timeout is set to 5 seconds by default. If your integration keeps a socket open between transactions and the connection is idle for longer than 5 seconds, DHS closes the socket. DHS does not send a response when this happens. The next request written to the closed socket is not processed, and the client receives no response.

How to fix

Use one of the following approaches:
  1. Open a new socket for each request, and close it once the response is received.
  2. Reconnect on failure: if a write or read on an existing socket fails or returns end of stream, open a new socket and resend the request.
  3. Keep the connection alive: send 0800 network management (echo) messages at an interval shorter than the socket timeout, for example every 4 seconds.
In addition:
  • Read the 2-byte length header and the response body in full before parsing. A single read may return only part of the message.
  • Log connection errors rather than discarding them, so that dropped connections can be identified.
  • Verify that your system can reach the DHS host IP address and port. DHS only accepts connections from pre-agreed IP addresses.

Server returns a 500 error or response code 1

The Rate Service Classic API returns HTTP 500, or the ISO API returns response code 1.

Why this happens

An unexpected error occurred on the DHS server. For Rate Service Classic, this can also indicate a malformed URL (for example, double slashes in the path).

How to fix

  1. For Rate Service Classic, verify that the URL does not contain double slashes, missing path segments, or other formatting errors.
  2. If the URL is correct, retry the request after a short delay. A transient server issue may resolve itself.
  3. If the error persists, contact your Fexco project manager with the timestamp and message from the error response (Rate Service Classic) or the REFERENCENUMBER from the response (ISO).

Rate offer expires or becomes unavailable

The cardholder did not respond before the expiry timestamp in the rate offer.

Why this happens

Every DCC rate offer has a limited validity window. The rate is built from the most recently sourced wholesale rate at the time of the request. Once the expiry passes, the offer must not be used.

How to fix

Discard the expired offer and send a new rate request with the same parameters. Present the new offer to the cardholder. See Handle rate expiry for detailed guidance.
The Rate Service Connect API returns HTTP 409 Conflict.

Why this happens

The underlying exchange rates are being refreshed, or the external rate service is temporarily unavailable. The rate that was available when the request was made is no longer valid.

How to fix

Wait a short time and retry the request. If the 409 response persists, contact your Fexco project manager.

Still having issues?

If you have worked through the steps above and the issue persists, contact your Fexco project manager with:
  • Your acquirer ID and merchant ID.
  • The API method you are using (Rate Service Classic, Rate Service Connect, XML, or ISO 8583).
  • The environment (production or cert).
  • The request URL or message.
  • The timestamp of the request.
  • The full error response or response code.

Next steps