Dynamic Currency Conversion
Mastercard Gateway offers real-time rate quotes from a Dynamic Currency Conversion (DCC) provider for goods and services priced in your preferred currency. You can present this exchange rate to the payer, allowing them to choose between paying in your preferred currency or the currency of a card. This service benefits cardholders by providing the exact amount they are charged in their currency at the time of purchase.
How does it work
- The payer:
Selects goods or services. The prices are displayed on the merchant's website in the merchant's currency.
- The merchant:
Initiates payment processing in their currency.
- DCC service provider:
Uses the BIN to determine the payer's billing currency.
Provides an exchange rate including a conversion fee.
- Merchant:
Presents the payer with two options:
- The transaction amount in the payer's billing currency.
- The transaction amount in the merchant's currency.
- 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.
- The card scheme:
Settles the transaction to the merchant's acquirer in the payer's currency.
- DCC Service Provider:
Settles with the merchant's acquirer in the merchant's currency.
- The DCC service provider and the merchant:
Shares the conversion fee.
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 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
The prerequisite for rate quotes is:
- Ensure to register yourself with the DCC provider that you want to use.
Mastercard Gateway currently supports FEXCO as a DCC service provider. It supports all ISO currencies for the payer and merchant.
Managing rate quotes through the gateway
When managing rate quotes through the gateway, there are four scenarios for applying DCC:
- No DCC:You cannot apply for DCC because the payer's card currency matches your preferred currency.
- DCC Possible, No Offer:You can apply for DCC, but there is no offer from the DCC provider.
- DCC Offered, Rejected:You can apply for DCC, the DCC provider has made an offer, but the payer rejects it.
- DCC Offered, Accepted:You can apply for DCC, the DCC provider has made an offer, and the payer accepts it.
Request a rate quote
To request a rate quote, provide data for the following fields in the Payment Options Inquiry apiOperation=PAYMENT_OPTIONS_INQUIRY request:
order.amount.order.currency.paymentType. If provided, this must be set toCREDIT.
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND response.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.
{
"order": {
"currency": "USD",
"amount": 100
},
"sourceOfFunds": {
"provided": {
"card": {
"prefix": "5100049999"
}
}
},
"apiOperation": "PAYMENT_OPTIONS_INQUIRY"
}
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 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: (Optional) 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 includescurrencyConversion.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: (Optional) The 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][NVP]
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 OffersOffer text
Visa and Mastercard have specific requirements for displaying DCC information to payers. Ensure to 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.
Fundamental principles of DCC regulations:
- 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
You are provided with the offer text in
paymentTypes.card.currencyConversion.offerText. You can specify the locale for the offer text by settinglocale=<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.offerTextfor 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.localeor 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.requestIdas returned in the response from Mastercard Gateway.currencyConversion.uptake=ACCEPTED.
Provide the payer with the receipt text provided in
paymentTypes.card.currencyConversion.receiptTextin theRETRIEVE_TRANSACTIONresponse. 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.requestIdas 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_BRANDcurrencyConversion.gatewayCode=NOT_ELIGIBLEcurrencyConversion.gatewayCode=ERROR
You must set
currencyConversion.uptake=NOT_AVAILABLEin your transaction request and supply the correctcurrencyConversion.requestId.
This enables the DCC provider to use the data for analysis and reporting purposes.
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.
If you want to use the Authentication API 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.transactionIdthat you provided in the Initiate Authentication and Authenticate Payer operations.
Currency Conversion Input API Reference [REST][NVP]
Capture or Refund DCC transactions
Captures
You must 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][NVP]
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 currencyConversion.uptake=ACCEPTED for the initial transaction:
- 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.
- A rate quote will be requested for the specific refund amount. This will generate a new
- Configuration is
HISTORICAL:- The DCC details provided for the initiating transaction on the order is used to calculate
currencyConversion.payerAmountfor the refund. - For partial refunds or excessive refund amounts, the
currencyConversion.payerAmountfrom 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.
- The DCC details provided for the initiating transaction on the order is used to calculate
For the initial transaction the field currencyConversion.uptake is DECLINED or
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
currencyConversionfields are returned on the refund transaction response or on the Retrieve Transaction operation.
Testing your DCC integration
You can test your DCC integration using your test merchant profile.