> ## 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 for a merchant terminal
> Use this endpoint to request a DCC rate offer for a card-present transaction at a merchant terminal (POS or POI device). Identify the merchant using the Fexco-assigned merchant ID.
For DCC, transaction-specific calls can be made using the amount in the merchant's local currency. If the cardholder's card is eligible for DCC, the response includes the equivalent amount and exchange rate in the cardholder's home currency.
For VISA compliance, transactions that occur for currencies with 3 minor units, such as the Kuwaiti dinar, the transaction amount will be rounded at the second decimal place with the third decimal place always zero.
**Note:** The response may be a single DccRateOffer or a list of DccRateOffer objects.
## OpenAPI
````yaml /openapi/dhs-flex-v3.json get /acquirers/{acquirerId}/merchants/{merchantId}/dccoffers
openapi: 3.0.1
info:
title: DCC - DHS Rest
version: 3.0.0
description: >
## Summary
The DHS REST interface uses HTTPS protocol to obtain rates from DHS. REST is
an acronym for Representational State
Transfer. Whether you are implementing MCP, DCC, or both, you can use the
REST requests interchangeably. Implementing
DHS REST requires the Fexco merchant ID (MID), ATM ID, and the merchant's
acquirer ID as part of all REST requests. The
merchant ID, ATM ID, and acquirer ID will be supplied by your Fexco project
manager.
### About Fexco's Foreign Exchange Rates
Fexco refreshes its foreign exchange rates six times per day every financial
trading day. Your website has the option to
update foreign exchange (FX) rates once per day or several times during the
day. Whether your business requires exchange
rates several times per day or only one set of rates per day is a decision
that entails some consideration.
#### Disclaimer
The rates used here are static and are used for the purposes of executing
API calls.
### About Dynamic Currency Conversion (DCC)
DCC is a payment card service that facilitates the payment of goods and
services in the currency of the cardholder. The
key components of a DCC transaction are identifying the currency of the card
and supplying the equivalent foreign
currency amount. DCC is typically offered to international cardholders when
making a purchase at a point of sale (POS)
or point of interaction (POI) device. Upon entering their credit card on the
POS device, the cardholder is presented
with the choice to pay in either the local currency or the currency in which
the card is issued—referred to as the
cardholder's home currency. Depending on ATM transaction, merchant's POS, or
website configuration, DCC enabled services
will do one of the following:
* Collect exchange rates from DHS once a day. In this scenario, the rates
are stored locally and applied at the POS each
time a valid DCC transaction is carried out.
* Request a rate directly from DHS on a transaction basis. In this scenario,
a request message is sent to DHS and if the
card currency (identified by the BIN and CID) is eligible for DCC, DHS responds with the cardholder's currency amount
and exchange rate
contact:
name: Fexco Drive Development Team
url: https://www.fexco.com
servers:
- url: https://api.example.com/dhsv2
description: Replace with your DHS environment base URL
security: []
paths:
/acquirers/{acquirerId}/merchants/{merchantId}/dccoffers:
get:
tags:
- V2 - Merchant - Dcc Rate offer
summary: Request a DCC offer for a merchant terminal
description: >-
Use this endpoint to request a DCC rate offer for a card-present
transaction at a merchant terminal (POS or POI device). Identify the
merchant using the Fexco-assigned merchant ID.
For DCC, transaction-specific calls can be made using the amount in the
merchant's local currency. If the cardholder's card is eligible for DCC,
the response includes the equivalent amount and exchange rate in the
cardholder's home currency.
For VISA compliance, transactions that occur for currencies with 3 minor
units, such as the Kuwaiti dinar, the transaction amount will be rounded
at the second decimal place with the third decimal place always zero.
**Note:** The response may be a single DccRateOffer or a list of
DccRateOffer objects.
operationId: getDccRateOffer
parameters:
- name: acquirerId
in: path
description: >-
Acquiring bank identification code defined by Fexco to identify the
merchant's acquiring bank or ATM
required: true
schema:
type: string
maxLength: 3
minLength: 3
example: TST
- name: merchantId
in: path
description: >-
The merchant ID is assigned by Fexco. This merchant ID corresponds
to Mercury's Merchant Originator Tag.
An alphanumeric value that identifies the merchant
required: true
schema:
type: string
maxLength: 16
minLength: 1
example: '11111111'
- name: baseamount
in: query
description: >-
Specifies the numeric amount of the transaction in base currency
minor units as per ISO 4217
required: true
schema:
type: number
example: 100
- name: currency
in: query
description: >-
List of foreign ISO4217 currency codes. You can specify any
combination of alphabetic and numeric currency codes.
**Note:** Please do not add spaces before or after the commas that
separate the currency codes
If you want to override the Card foreigner's currency with a custom
currency you can pass the foreign currency in this parameter with
the bin information
**Note:** The base currency is GBP. Please do not use GBP in the
currency field
**Note:** The currency field is only for an MCP Rate Call
required: false
schema:
type: string
example: USD,JPY
- name: bin
in: query
description: >-
This value includes the bank identification number (BIN) which is
represented by leading digits of the payment card number
required: false
schema:
type: string
maxLength: 12
minLength: 6
example: '411111'
- name: cid
in: query
description: >-
This value is an extension of bin allowing for the next 6 digits of
the card number.
This value is the Card Currency Identifier (or Currency ID) which is
used in conjunction with the BIN specified and provides the next 6
digits of the card number, whereby:
* **bin**: specifies only digits 1 to 6 of the BIN
* **cid**: specifies digits 7 to 12 of the card number
A maximum of 6 digits is accepted while 4 is the recommended length.
Note: Only 4 digits of the CID are stored
required: false
schema:
type: string
maxLength: 6
example: '6789'
- name: posentrymode
in: query
description: >-
This is an optional POS Entry Mode used with the Contactless
Transaction Lower Limit (TLL).
The Contactless TLL is an optional configurable limit per MID or ATM
ID on DHS. A contactless transaction with an amount less than or
equal to the TLL will not be eligible for DCC. A contactless
transaction with an amount greater than the TLL will be eligible for
DCC. The optional POS Entry Mode field is used to indicate if the
transaction is contactless or not.
This POS Entry Mode field indicates the method by which the Primary
Account Number (PAN) was captured at the point of service and the
PIN entry capabilities of the POS used
It consists of a two-digit sub-field followed by a one-digit
sub-field. Possible values are as defined by ISO 8583.
**Two-digit sub-field 1**:
* '00' PAN entry mode unknown or unspecified.
* '01' PAN manual entry.
* '02' PAN auto-entry via magnetic stripe – the magnetic stripe has
not been fully read and/or transmitted.
* '03' PAN auto-entry via bar code reader.
* '04' PAN auto-entry entry via optical character reader (OCR).
* '05' PAN auto entry via ICC.
* '07' PAN auto entry via Contactless ICC EMV*
* '80' Fallback from integrated circuit card (ICC) to a magnetic
stripe.
* '90' PAN auto-entry via Magnetic stripe.
* '91' PAN auto-entry via contactless magnetic stripe.
* '95' PAN auto-entry via ICC. CVV may not be checked.
" +
**One-digit sub-field 2**:
* '0' Unspecified or unknown.
* '1' Terminal has PIN entry capability.
* '2' Terminal does not have PIN entry capability.
* '8' Terminal has PIN entry capability but the PIN pad is not
currently operative =
'07' and '91' are the current Contactless values configured for TLL
on the DHS service
required: false
schema:
type: string
maxLength: 3
minLength: 3
example: '018'
- name: basefeeamount
in: query
description: >-
Transaction fee amount in base currency minor units. When supplied
with baseamount and bin, the response includes converted fee and
total amounts.
required: false
schema:
type: number
example: 2.5
- name: x-dcc-dhs-version
in: header
description: >-
Optional DHS response version. Use 3.1 to include exchangeRateType;
3.0 is the default.
required: false
schema:
type: string
enum:
- '3.0'
- '3.1'
default: '3.0'
example: '3.1'
responses:
'200':
description: >-
DCC Rate Offer.
The service can return an Entity or a List of
Entities.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/DccRateOfferResponse'
- type: array
items:
$ref: '#/components/schemas/DccRateOfferResponse'
examples:
merchantOfferWithBin:
summary: Merchant DCC offer resolved from a card BIN
value:
uuid: 29ac6075-5d30-4159-815d-6da233cb3ce7
responseTimestamp: '2026-09-15T10:15:30Z'
referenceNumber: REF-001234
baseAmount: '100.00'
baseFeeAmount: '2.50'
exchangeRate:
uuid: 83ec7885-c72b-4f70-99a5-afe1e1f787c5
baseCurrency:
numericCode: 978
alphaCode: EUR
minorUnits: 2
rate: '1.0922'
foreignCurrency:
numericCode: 840
alphaCode: USD
minorUnits: 2
marginPercentage: '3'
commissionPercentage: '0.010000'
source: REUTERS WHOLESALE INTERBANK
sourceTimestamp: '2026-09-15T08:00:00Z'
expiry: '2026-09-16T08:00:00Z'
foreignAmount: '109.22'
foreignFeeAmount: '2.73'
foreignTotalAmount: '111.95'
bin:
number: 411111*****
currency:
numericCode: 840
alphaCode: USD
minorUnits: 2
schemeCode: 1
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseError'
examples:
invalidAmount:
summary: Invalid transaction amount
value:
timestamp: '2026-09-15T10:15:30Z'
url: >-
/dhsv2/acquirers/TST/merchants/11111111/dccoffers?baseamount=-1
error: BAD_REQUEST
status: 400
message: baseamount must be greater than zero
'404':
description: DCC Rate Offer not found
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseError'
examples:
merchantNotFound:
summary: Merchant is not configured for the acquirer
value:
timestamp: '2026-09-15T10:15:30Z'
url: >-
/dhsv2/acquirers/TST/merchants/99999999/dccoffers?baseamount=100.00
error: NOT_FOUND
status: 404
message: No such Merchant
'500':
description: General Error
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseError'
examples:
serviceError:
summary: DHS could not complete the request
value:
timestamp: '2026-09-15T10:15:30Z'
url: >-
/dhsv2/acquirers/TST/merchants/11111111/dccoffers?baseamount=100.00
error: INTERNAL_SERVER_ERROR
status: 500
message: An unexpected error occurred
components:
schemas:
DccRateOfferResponse:
type: object
description: DccRateOffer
properties:
uuid:
type: string
format: uuid
example: 29ac6075-5d30-4159-815d-6da233cb3ce7
responseTimestamp:
type: string
format: date-time
example: 2026-03-19T10:15:30.000+0000
referenceNumber:
type: string
example: REF-001234
baseAmount:
type: string
example: '100.00'
baseFeeAmount:
type: string
description: Fee amount in base currency, present when basefeeamount is supplied.
example: '2.50'
exchangeRate:
$ref: '#/components/schemas/ExchangeRateResponse'
foreignAmount:
type: string
example: '109.50'
foreignFeeAmount:
type: string
description: >-
Fee amount in foreign currency, present when basefeeamount is
supplied.
example: '2.73'
foreignTotalAmount:
type: string
description: >-
Total amount in foreign currency, present when basefeeamount is
supplied.
example: '111.95'
bin:
$ref: '#/components/schemas/Bin'
ResponseError:
type: object
properties:
timestamp:
type: string
format: date-time
description: >-
The timestamp format is expressed according to ISO8601 with the
combined date and time in coordinated universal time (UTC).
YYYYMMDDTHH:MM:SS.000+0000
example: 20141023T11:43:45.000+0000
url:
type: string
description: Requested URL
example: /dhsv2/acquirers/TST/merchants/11111111/dccoffers
error:
type: string
description: Error title
example: NOT_FOUND
status:
type: number
description: Status code
example: 404
message:
type: string
description: Error message
example: No such Merchant
ExchangeRateResponse:
type: object
properties:
uuid:
type: string
format: uuid
example: 83ec7885-c72b-4f70-99a5-afe1e1f787c5
baseCurrency:
$ref: '#/components/schemas/Currency'
rate:
type: string
example: '1.0922'
foreignCurrency:
$ref: '#/components/schemas/Currency'
marginPercentage:
type: string
example: '3'
commissionPercentage:
type: string
example: '0.010000'
source:
type: string
example: REUTERS WHOLESALE INTERBANK
sourceTimestamp:
type: string
format: date-time
example: 2026-03-19T08:00:00.000+0000
expiry:
type: string
format: date-time
example: 2026-03-20T08:00:00.000+0000
exchangeRateType:
type: string
description: Included when x-dcc-dhs-version is set to 3.1.
example: CARD
Bin:
type: object
properties:
number:
type: string
example: 411111*****
currency:
$ref: '#/components/schemas/Currency'
schemeCode:
type: integer
format: int32
example: 1
Currency:
type: object
properties:
numericCode:
type: integer
format: int32
example: 978
alphaCode:
type: string
example: EUR
minorUnits:
type: integer
format: int32
example: 2
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.