# Dynamic Currency Conversion
source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/dynamic-currency-conversion/index.md

## Overview {#overview}

Mastercard Gateway offers real-time rate quotes from a Dynamic Currency Conversion (DCC) provider. If your prices are in a different currency than the customer's card, you can give them the option to:

* Pay in your currency, or
* Pay in their own card's currency.

This service benefits cardholder by providing the exact amount they are charged in their currency at the time of purchase.

## How does it work {#how-does-it-work}

1. **The payer** :  

   Selects goods or services. The prices are displayed on the merchant's website in the merchant's currency.

2. **The merchant** :  

   Initiates payment processing in their currency.

3. **DCC service provider** :  

   Uses the BIN to determine the payer's billing currency.  

   Provides an exchange rate including a conversion fee.

4. **Merchant** :  

   Presents the payer with two options:

   * The transaction amount in the payer's billing currency.
   * The transaction amount in the merchant's currency.
5. **The payer** :  

   * Chooses either the DCC offer or the merchant's currency.
   * If the payer chooses DCC, the transaction is processed in the payer's currency.
6. **The card scheme** :  

   Settles the transaction to the merchant's acquirer in the payer's currency.

7. **DCC Service Provider** :  

   Settles with the merchant's acquirer in the merchant's currency.

8. **The DCC service provider and the merchant** :  

   Share the conversion fee.

## Key benefits {#key-benefits}

The following are the key benefits of DCC:

* Payers can pay for goods or services in their preferred currency at the point of sale.
* You receive a share of the currency conversion fee.
* The order is processed in your currency.
* Payers can see the order amount in their currency on their card statement.
* Payers do not see a separate currency conversion charge on their card statement, as it is included in the provided rate quote.

## Prerequisites {#prerequisites}

The prerequisite for rate quotes is:

* Ensure to register yourself with the DCC provider that you want to use. Warning: Mastercard Gateway currently supports FEXCO as a DCC service provider which handles all ISO currencies for the payer and merchant.

## Managing rate quotes through the gateway {#managing-rate-quotes-through-the-gateway}

When managing rate quotes through the gateway, there are four scenarios for applying DCC:

1. **No DCC**: You cannot apply for DCC because the payer's card currency matches your preferred currency.
2. **DCC Possible, No Offer**: You can apply for DCC, but there is no offer from the DCC provider.
3. **DCC Offered, Rejected**: You can apply for DCC, the DCC provider has made an offer, but the payer rejects it.
4. **DCC Offered, Accepted**: You can apply for DCC, the DCC provider has made an offer, and the payer accepts it.

### Request a rate quote {#request-a-rate-quote}

To request a rate quote, provide data for the following fields in the [Payment Options Inquiry](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/integrate-gateway-features/payment-options-inquiry/index.md) `apiOperation`=PAYMENT_OPTIONS_INQUIRY request:

* `order.amount`
* `order.currency`
* `paymentType` If provided, this must be set to CREDIT.

Alert: DCC only supports transactions using Visa, Mastercard, or Maestro card types. If you request DCC for any other card type, it returns a currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND response. Warning: When invoking the Payment Options Inquiry operation, ensure that all the required request parameters are included in the PAYMENT_OPTIONS_INQUIRY request body. The following is a sample JSON request for a DCC rate quote.

```json
{
  "order": {
    "currency": "USD",
    "amount": 100
  },
  "sourceOfFunds": {
    "provided": {
      "card": {
        "prefix": "5100049999"
      }
    }
  },
  "apiOperation": "PAYMENT_OPTIONS_INQUIRY"
}
```

### Rate quote status responses {#rate-quote-status-responses}

Mastercard Gateway provides information about the DCC offer. The information related to the DCC offer is displayed to the payer on your payment page or PIN Entry Device (PED) terminal, following the scheme and legislative requirements.

* `currencyConversion.gatewayCode:`
  * `QUOTE_PROVIDED`: Indicates that quote is provided.
  * `NOT_ELIGIBLE`: Indicates that the DCC is not available for this card or currency.
  * `UNSUPPORTED_CARD_BRAND`: Indicates that the card brand is not supported.
  * `INSUFFICIENT_INFORMATION`: Indicates required fields missing in the request.
  * `ERROR`: Indicates that the DCC provider is unable to process this operation.
* `currencyConversion.provider`: Name of DCC quote provider.
* `currencyConversion.providerCode`: The DCC provider generates a summary of the success or failure of the DCC quote request.
* `currencyConversion.providerReceipt`: This is an optional field. Unique DCC provider's reference for the rate quote.
* `currencyConversion.exchangeRateSource`: The financial data agency is used as a source for the exchange rate.
* `currencyConversion.payerExchangeRate`: The exchange rate used to convert the transaction amount into the payer's currency. This includes `currencyConversion.marginPercentage`.
* `currencyConversion.payerAmount`: The total amount of the transaction in the payer's currency.
* `currencyConversion.payerCurrency`: The DCC provider provides the currency of the DCC rate quotes.
* `currencyConversion.marginPercentage`: The foreign exchange markup is applied as a percentage of the transaction amount for providing the conversion service.
* `currencyConversion.exchangeRateTime`: The timestamp of when the conversion rate is effective.
* `currencyConversion.quoteExpiry`: This is an optional timestamp indicating when the DCC quote offer expires.
* `currencyConversion.offerText`: An HTML fragment containing an input form for the DCC offer must be presented to the payer to collect their choice.
* `currencyConversion.requestId`: The unique identifier for your DCC quote request as returned in the `PAYMENT_OPTIONS_INQUIRY` response.

**Payment Options Inquiry API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#gateway)

### Using the rate quote for a transaction {#using-the-rate-quote-for-a-transaction}

* If you obtain a rate quote from the DCC provider, `currencyConversion.gatewayCode=QUOTE_PROVIDED`, you can make a currency conversion offer to the payer.

#### Rate quote offers {#rate-quote-offers}

##### Offer text {#offer-text}

Visa and Mastercard have specific requirements for displaying DCC information to payers. Ensure you have the necessary details to make an informed choice. This includes information on fees in the DCC offer and the transaction receipt if the payer accepts the offer.
The fundamental principles of DCC regulations are:

* The cardholder can choose to pay in either the merchant's currency or their home currency, with full transparency of transaction details.
* The cardholder is given the option to accept or decline the DCC offer.
* The terms and conditions associated with DCC are fully disclosed to the cardholder.

##### Offer presentation {#offer-presentation}

You are provided with the offer text in `paymentTypes.card.currencyConversion.offerText`. You can specify the locale for the offer text by setting `locale=<Valid language identifier or IETF language tag of payer's locale>`.

For example, "en" for English, "pt-BR" for Brazilian Portuguese, and "es-MX" for Mexican Spanish.

A locale-specific HTML-formatted DCC offer text is returned in `paymentTypes.card.currencyConversion.offerText` for the following supported locales:

* French (fr_FR)
* German (de_DE)
* Spanish for Mexico (es_MX)
* Chinese:
  * Simplified Chinese (zh_CN)
  * Hong Kong Chinese (zh_HK)
* Portuguese for Brazil (pt_BR)
* Japanese (ja_JP)
* Indonesian (id_ID)
* English:
  * United States (en_US)
  * United Kingdom (en_UK)
  * Australia (en_AU)  

If the locale is not supported, Mastercard Gateway provides an offer text according to the following scheme:

* The language code is matched to the closest supported locale, if available.
* If you do not set interaction.locale or if the provided locale and base language are unsupported, Mastercard Gateway attempts to use your configured default locale. If that locale and base language are not supported, the offer is presented in "en_US".

The payer:

* Accept the DCC offer and choose to pay in the card currency. In this case, initiate a transaction request with the following parameters:
  * `currencyConversion.requestId` as returned in the response from Mastercard Gateway.
  * `currencyConversion.uptake=ACCEPTED`. Provide the payer with the receipt text provided in `paymentTypes.card.currencyConversion.receiptText` in the `RETRIEVE_TRANSACTION` response. This uses the same locale as the offer text.
* Decline the DCC offer and choose to pay in the order currency (`currencyConversion.uptake=DECLINED`). In this case, initiate a transaction request with the following parameters:
  * `currencyConversion.requestId` as returned in the response from Mastercard Gateway.
  * `currencyConversion.uptake=DECLINED`.
* If you receive one of the following in the Payment Options Inquiry response:
  * `currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND`
  * `currencyConversion.gatewayCode=NOT_ELIGIBLE`
  * `currencyConversion.gatewayCode=ERROR` You must set `currencyConversion.uptake=NOT_AVAILABLE` in your transaction request and supply the correct `currencyConversion.requestId`.

This enables the DCC provider to use the data for analysis and reporting purposes.

Alert: If you obtained a rate quote outside the gateway, you must explicitly provide the DCC details returned in the transaction request to you by the DCC provider. Alert: If you want to use the [Authentication API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs) to authenticate the payer before performing the payment, you must pass the DCC fields as described in the Initiate Authentication operation.

Once payer authentication is complete, proceed with the following actions:

* The payment with the same order with an Authorize or Pay operation.
* Provide the `authentication.transactionId` that you provided in the Initiate Authentication and Authenticate Payer Operations.

<br />

**Currency Conversion Input API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction)

## Capture or Refund DCC transactions {#capture-or-refund-dcc-transactions}

#### Captures {#captures}

Provide DCC details in the Authorize transaction request and they apply to captures on the order.

* The DCC details from the Authorize request are used for a full capture.
* For partial or excessive captures, Mastercard Gateway computes the amount on a pro-rata basis as a percentage.

**Currency Conversion for Captures API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction)

#### Refunds {#refunds}

If your MSO configures you for DCC in Mastercard Gateway, this configuration also applies to subsequent refunds.

The following are configuration options:

* `CURRENT`: A new rate quote is requested to provide the actual rate at the refund transaction date.
* `HISTORICAL`: The rate used when the order was created will be applied to the refund.

##### If the currencyConversion.uptake=ACCEPTED for the initial transaction: {#if-the-currencyconversionuptakeaccepted-for-the-initial-transaction}

* The configuration is `CURRENT`:
  * A rate quote will be requested for the specific refund amount. This will generate a new `currencyConversion.requestId`. The new rate quote will be applied to the refund.
  * The transaction response returns `currencyConversion.uptake=ACCEPTED`.
* The configuration is `HISTORICAL`:
  * The DCC details provided for the initiating transaction on the order are used to calculate `currencyConversion.payerAmount` for the refund.
  * For partial refunds or excessive refund amounts, the currencyConversion.payerAmount from the initial transaction is provided on a pro-rata basis as a percentage of the merchant amount. Standard rounding is used where pro-rata is applied.
  * If you use partial refunds to fully refund a captured amount, the last partial refund contains the outstanding captured payer amount. This is done to account for any rounding on partial amounts. Where the total refunded amount does not equal the total captured amount, there is no validation on payer amounts, for example, on excessive refunds.
  * The transaction response returns currencyConversion.uptake=ACCEPTED.

##### For the initial transaction the field currencyConversion.uptake is DECLINED, NOT_AVAILABLE, or NOT_REQUIRED {#for-the-initial-transaction-the-field-currencyconversionuptake-is-declined-not_available-or-not_required}

If the initial authorization and capture are processed successfully as non-DCC transactions and you submit a subsequent refund request then independently of your merchant configuration:

* No rate quote will be requested.
* No currencyConversion fields are returned on the refund transaction response or on the Retrieve Transaction operation.

## Testing your DCC integration {#testing-your-dcc-integration}

You can [test your DCC integration](https://developer.mastercard.com/mastercard-gateway/documentation/test-cards/index.md) using your test merchant profile.