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.
The Mastercard Payment Gateway currently supports:
There are four basic, mutually exclusive, scenarios for applying DCC to a transaction:
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
.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://evopaymentsmexico.gateway.mastercard.com/api/rest/version/72/merchant/TESTMERCHANT-DCC/paymentOptionsInquiry?order.amount=123.34&order.currency=USD&sourceOfFunds.provided.card.prefix=531335999"
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.If you obtain a rate quote from the DCC provider (currencyConversion.gatewayCode=QUOTE_PROVIDED
), you can make a currency conversion offer to the payer.
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:
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:
If the locale is not supported, the Mastercard Payment Gateway will provide an offer text according to the following scheme:
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 Mastercard Payment Gateway, you must explicitly provide the DCC details returned in the transaction request to you by the DCC provider.
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.
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:
CURRENT
:
currencyConversion.requestId
. The new rate quote will be applied to the refund. currencyConversion.uptake=ACCEPTED
.HISTORICAL
:
currencyConversion.payerAmount
for the refund.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.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:
currencyConversion
fields are returned on the refund transaction response or on the Retrieve Transaction operation.You can test your DCC integration using your test merchant profile.
Copyright © 2022 Mastercard