# DCC rate API

Get a Dynamic Currency Conversion (DCC) rate for a transaction.

## Overview

This API allows you to retrieve real-time DCC exchange rates for informational and integration purposes. Use it to obtain exchange rates for your own systems, test and validate your DCC configuration, or verify rate provider connectivity.

This API is for obtaining DCC rates only. We don't currently support processing DCC transactions through e-commerce or other non-POS channels.

To use this API, your organisation must be a merchant of Elavon or AIB. Currently, only Fexco and Elavon are supported as exchange rate providers.

## Get a DCC rate

/v1/dcc/rate

### Request examples

Use the following requests to get a DCC rate.

```json Elavon
{
  "merchant": "MERCHANT-001",
  "site": "SITE-001",
  "exchangeRateProvider": "Elavon",
  "securityLevel": {
    "primaryAccountNumber": "{primaryAccountNumber}"
  },
  "transactionMethod": {
    "entryMode": "Instore",
    "intent": "Authorisation"
  },
  "pointOfInteraction": {
    "entryType": "ChipAndPin",
    "merchantPointOfSaleId": "POS-001"
  },
  "amounts": {
    "localTransaction": 100,
    "localCurrencyCode": "USD",
    "cardHolderCurrencyCode": "EUR"
  }
}
```

```json Fexco
{
  "merchant": "MERCHANT-001",
  "site": "SITE-001",
  "exchangeRateProvider": "Fexco",
  "securityLevel": {
    "primaryAccountNumber": "{primaryAccountNumber}"
  },
  "transactionMethod": {
    "entryMode": "Instore",
    "intent": "Authorisation"
  },
  "pointOfInteraction": {
    "entryType": "ChipAndPin",
    "merchantPointOfSaleId": "POS-001"
  },
  "amounts": {
    "localTransaction": 100,
    "localCurrencyCode": "USD",
    "cardHolderCurrencyCode": "EUR"
  }
}
```

| Parameter  | Description |
|  --- | --- |
| `merchant` string (≤ 20 characters)  | Your unique merchant identifier, as assigned by PXP. |
| `site` string (≤ 20 characters)  | Your unique site identifier, as assigned by PXP. |
| `exchangeRateProvider` string (enum)  | The exchange rate provider to use for the DCC rate calculation.Possible values:`Elavon``Fexco` |
| `securityLevel`object   | Details about the security level of the transaction. |
| `securityLevel.primaryAccountNumber` string (≥ 1 character)   | The primary account number. |
| `securityLevel.encryptedPayload` string (≥ 1 character) | The encrypted payload for P2PE transactions. This is a future enhancement and not currently supported. |
| `transactionMethod` object   | Details about the transaction method. |
| `transactionMethod.entryMode` string (enum)   | The entry mode of the transaction. Possible values: `Instore``Ecom` |
| `transactionMethod.intent`string (enum)  | The intent of the transaction. Possible values:`Purchase``Authorisation``EstimatedAuthorisation``Capture``FinalCapture``Refund``Reversal` |
| `pointOfInteraction`object | Details about the point of interaction. This object is optional for Ecom transactions. |
| `pointOfInteraction.entryType`  string (enum, ≥ 1 character) | The type of entry used to capture the card details. Possible values:`ChipAndPin``CardContactless` |
| `pointOfInteraction.merchantPointOfSaleId` string (≥ 1 character) | The unique identifier for the merchant point of sale. |
| `amounts` object   | Details about the transaction amount. |
| `amounts.localCurrencyCode`string (3 characters)  | The local currency code, in ISO 4217 format. |
| `amounts.localTransaction` number (≥ 0.01)  | The transaction amount in the local currency. |
| `amounts.cardHolderCurrencyCode`string (3 characters) | The cardholder's currency, in ISO 4217 format. |


### Response examples

If your request is successful, you'll receive a `200` response.

```json Elavon
{
  "state": "Available",
  "amounts": {
    "local": {
      "transaction": 100,
      "currencyCode": "USD"
    },
    "cardholder": {
      "transaction": 85.5,
      "currencyCode": "EUR"
    }
  },
  "exchangeRate": {
    "rate": 0.855,
    "exponent": 3,
    "markUpPercentage": 3.5,
    "commissionRate": 0.025,
    "margin": 2.1
  },
  "messaging": {
    "markUpMessage": "Competitive exchange rate with 3.5% markup",
    "disclaimer": "Exchange rate includes markup and may vary"
  },
  "providerResponse": {
    "provider": "Elavon",
    "referenceId": "REF123456789",
    "terminalId": "TERM001"
  }
}
```

```json Fexco
{
  "state": "Available",
  "amounts": {
    "local": {
      "transaction": 100,
      "currencyCode": "USD"
    },
    "cardholder": {
      "transaction": 86.2,
      "currencyCode": "EUR"
    }
  },
  "exchangeRate": {
    "rate": 0.862,
    "exponent": 3,
    "markUpPercentage": 3.2,
    "commissionRate": 0.022,
    "margin": 1.8
  },
  "messaging": {
    "markUpMessage": "Fexco competitive rate with 3.2% markup",
    "disclaimer": "Fexco rate subject to market conditions"
  },
  "providerResponse": {
    "provider": "Fexco",
    "referenceId": "FX987654321",
    "terminalId": "TERM001"
  }
}
```

```json Not available
{
  "state": "NotAvailable",
  "amounts": {
    "local": {
      "transaction": 100,
      "currencyCode": "USD"
    },
    "cardholder": {
      "transaction": 0,
      "currencyCode": "EUR"
    }
  },
  "exchangeRate": {
    "rate": 0,
    "exponent": 0,
    "markUpPercentage": 0,
    "commissionRate": 0,
    "margin": 0
  },
  "messaging": {
    "markUpMessage": "",
    "disclaimer": "DCC service not available for this transaction"
  },
  "providerResponse": {
    "provider": "Elavon",
    "referenceId": "",
    "terminalId": ""
  }
}
```