Dynamic Currency Conversion
The Mastercard Gateway can provide you with a real-time rate quote from a DCC provider on goods and services priced in your preferred currency. You can offer this exchange rate to the payer, who can then choose either to pay in your preferred currency or in the currency of the card. Cardholders benefit from this service, knowing at the time of purchase exactly how much they will be charged in their own currency.
Key benefits
- Payers can pay for goods or services in their billing currency at the point of sale.
- You receive a share of the currency conversion fee.
- The order is processed in your currency for the order.
- Payers see the order amount in their currency on the card statement.
- Payers do not see a currency conversion charge on the card statement (as this is included in the provided rate quote).
Prerequisites for rate quotes
- You must be registered with the DCC provider you wish to use.
The Mastercard Gateway currently supports:
- FEXCO.
Managing rate quotes through the gateway
There are four basic, mutually exclusive, scenarios for applying DCC to a transaction:
- You do not wish to apply DCC on the transaction; for example if the currency of the payer's card matches your preferred currency.
- You would like to do DCC if an offer were on the table, but there is no such offer.
- You would like to do DCC. The DCC provider has made an offer. You have provided this to the payer, who has rejected it.
- You would like to do DCC. The DCC provider has made an offer. You have provided this to the payer, who has accepted it.
Request a rate quote
You can request a rate quote by providing 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.When calling the Payment Options Inquiry operation using the REST protocol, ensure that the request parameters are included in the URI (as query parameters) and not in a JSON body. Below is a sample REST request in curl for a DCC rate quote.
curl --user merchant.TESTMERCHANT-DCC:<PASSWORD>"https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/72/merchant/TESTMERCHANT-DCC/paymentOptionsInquiry?order.amount=123.34&order.currency=USD&sourceOfFunds.provided.card.prefix=531335999"
Rate quote status responses
The Mastercard Gateway returns the following information about the DCC offer. Some of this will be included in the information you display to the payer on your payment page or PED terminal, in line with scheme and legislative requirements.
currencyConversion.gatewayCode:QUOTE_PROVIDED: Quote provided.NOT_ELIGIBLE: DCC not available for this card and/or currency.UNSUPPORTED_CARD_BRAND: Card brand not supported.INSUFFICIENT_INFORMATION: Required fields missing in request.ERROR: DCC provider unable to process this operation.
currencyConversion.provider: Name of DCC quote provider.currencyConversion.providerCode: Generated by DCC provider, summarizing the success or otherwise of the DCC quote request.currencyConversion.providerReceipt: Unique DCC provider's reference for the rate quote.(Not always provided.)currencyConversion.exchangeRateSource: The financial data agency 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 currency of the DCC rate quote provided by DCC provider.currencyConversion.marginPercentage: The foreign exchange markup applied as a percentage to the transaction amount for providing the conversion service.currencyConversion.exchangeRateTime: The timestamp of when the conversion rate is effective.currencyConversion.quoteExpiry: The timestamp indicating when the DCC quote offer expires. (Not always provided.)currencyConversion.offerText: An HTML fragment containing a input form for the DCC Offer. This 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 the display of DCC information to payers to ensure that the payer is presented with the information required to make an informed choice. This includes details of fees and charges in the DCC offer and the transaction receipt (if the payer accepts the offer).
Fundamental principles of DCC regulations:
- The cardholder has a choice to pay in the merchant's currency or their home currency with full transparency of transaction details.
- The cardholder is given the choice to accept or decline the DCC offer.
- The terms and conditions associated with DCC are fully disclosed to the cardholder.
Offer presentation
You will be 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>(e.g.enfor English,pt-BRfor Brazilian Portuguese,es-MXfor 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, the Mastercard Gateway will provide 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, the Mastercard Gateway will attempt to use your configured default locale. If that locale and base language is not supported, the offer will be presented inen_US.
The payer may then:-
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 the 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 the 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 of 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, you can proceed with the payment on the same order with an Authorize or Pay operation and provide the authentication.transactionId that you provided in the Initiate Authentication and Authenticate Payer operations. You do not need to pass the DCC fields again in your financial transaction because they are carried over from the referenced payer authentication transaction.
Currency Conversion Input API Reference [REST][NVP]
Capture or Refund DCC transactions
Captures
DCC details must be provided in the Authorize transaction request. DCC details apply to captures on the order.
For a full capture, the DCC details from the Authorize request will be used.
For partial or excessive captures the Mastercard Gateway computes the amount as a pro rata of the percentage.
Currency Conversion for Captures API Reference [REST][NVP]
Refunds
If you are configured by your MSO for DCC in the Mastercard Gateway, this configuration is applied to subsequent refunds.
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 will be used to calculate
currencyConversion.payerAmountfor the refund. - For partial refunds or excessive refund amounts,
currencyConversion.payerAmountfrom the initial transaction will be provided on a pro-rata basis as a percentage of merchant amount. Where pro-rata is applied, standard rounding is used. - If you use partial refunds to fully refund a captured amount, the last partial refund will contain 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 will be no validation on payer amounts (e.g. on excessive refunds).
- The transaction response returns
currencyConversion.uptake=ACCEPTED.
- The DCC details provided for the initiating transaction on the order will be used to calculate
If currencyConversion.uptake=DECLINED or NOT_AVAILABLE or NOT_REQUIRED for the initial transaction:
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.