Dynamic Currency Conversion

The Mastercard Payment 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 Payment Gateway currently supports:

    • FEXCO.

Managing rate quotes through the gateway

There are four basic, mutually exclusive, scenarios for applying DCC to a transaction:

  1. You do not wish to apply DCC on the transaction; for example if the currency of the payer's card matches your preferred currency.
  2. You would like to do DCC if an offer were on the table, but there is no such offer.
  3. You would like to do DCC. The DCC provider has made an offer. You have provided this to the payer, who has rejected it.
  4. 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 to CREDIT.
DCC is only supported on transactions using Visa, Mastercard, or Maestro card types. Requesting DCC for any other card type will return 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://na.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 Payment 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 includes currencyConversion.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 Offers

    Offer 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 setting locale=<Valid language identifier or IETF language tag of payer's locale> (e.g. en for English, pt-BR for Brazilian Portuguese, 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, the Mastercard Payment 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.locale or if the provided locale and base language are unsupported, the Mastercard Payment Gateway will attempt to use your configured default locale. If that locale and base language is not supported, the offer will be presented in en_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.requestId as returned in the response from the Mastercard Payment 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 the Mastercard Payment 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.

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/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 Payment 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 Payment 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.

  • Configuration is HISTORICAL:

    • The DCC details provided for the initiating transaction on the order will be used to calculate currencyConversion.payerAmount for the refund.
    • For partial refunds or excessive refund amounts, currencyConversion.payerAmount from 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.

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 currencyConversion fields 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.

Copyright © 2023 Mastercard