Multiple Currency Pricing (MCP)

Home    Online Payments    Financial Operations    Currency Conversion: DCC and MCP    Multiple Currency Pricing (MCP)

On this page:

Overview

Nuvei’s MCP service enhances your customer’s payment experience, by allowing you to convert all the prices displayed on your site into the visitor’s home currency, and accept payment in that currency.  You can sell the same item to British customers in Pounds Sterling, to French and German customers in Euros, and to Japanese customers in Yen.

That’s not all:

  • You get to keep your product catalog in your home currency.
  • Price your goods in multiple customer currencies.
  • Let your customer pay in their home currency.
  • While receiving your transaction settlements and reporting in your home currency.

Sign up for the optional MCP service by contacting the Nuvei Integration Team. Registration includes selecting a set of MCP display currencies that your site supports, and setting the exchange rate markup and other fees for those currencies. These are used in MCP currency conversion calculations.

MCP is only supported in the Nuvei Web SDK and REST API integrations.

For Web SDK and REST API

Integrating MCP into the Web SDK and REST API payment flows is relatively simple, because there are only a few additional steps, as described below.

Follow these steps to begin displaying MCP pricing on your site and accepting payments.

1. Retrieving the MCP Rates

Nuvei updates all currency exchange rates at scheduled intervals (currently once per day).

Use the /getMcpRates method to retrieve all the latest MCP currency conversion rates for the currencies that you support (as specified in your MCP agreement with Nuvei).

Nuvei supports MCP currency conversion for payments and payouts.
To receive MCP currency conversion for payouts, the merchant must provide rateType in the /getMcpRates request.
If not provided in the request, the MCP rates are returned for payment.

Example /getMcpRates Request

The following example retrieves MCP details for only one toCurrency. A more typical scenario would be to list all your MCP currencies in the toCurrency array.

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<merchantId>",
  "merchantSiteId":"<merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "rateType": "payout",
  "fromCurrency":"EUR",
  "toCurrency":[
    "USD"
  ],
  "paymentMethods":[
    "cc_card"
  ]
}
Example /getMcpRates Response
{
  "reason":"",
  "merchantId":"<merchantId>",
  "merchantSiteId":"<merchantSiteId>",
  "clientUniqueId":"695701003",
  "errCode":0,
  "clientRequestId":"YWSWQUTBV",
  "rates":[
    {
      "ratesByCurrencies":[
        {
          "rate":"1.195345",
          "currency":"USD"
        }
      ],
      "paymentMethod":"cc_card"
    }
  ],
  "sessionToken":"616beb03-df6a-43d6-abef-fbc081c93e08",
  "internalRequestId":14776101,
  "mcpTimestamp":"Mon Oct 26 14:53:30 EET 2020",
  "version":"1.0",
  "status":"SUCCESS"
}

2. Converting Your Site Pricing

Identify the visitor’s home currency, and display all the prices on your site to that visitor in their home currency.

  1. As soon as a visitor enters your site, you need to run processes to identify their home currency, based on some criteria that is entirely up to you.
    For example:
    • You can identify their location based on their IP address, and then look up the local currency.
    • You could prompt the visitor to select their preferred currency from a list of your MCP currencies.
  2. If the visitor’s home currency is one of your registered MCP currencies, then retrieve the MCP currency conversion rate from the response to your scheduled /getMcpRates request for that specific currency.
  3. Use the MCP currency conversionrate to convert all the prices displayed on your site into your visitor’s home currency.

    The MCP currency conversion rate has the exchange rate markup and fees built into it.

3. Accepting a Payment

When the customer presses the Pay button (or equivalent) on the payout page, send a regular /payment request (or an /openOrder request for Web SDK):

  • The checkout amount (in the customer’s home currency) as the transaction amount.
  • The MCP currency as the transaction currency.
  • Include a currencyConversion class:
    Example currencyConversion Class
    "currencyConversion": {
    "type": "MCP",
    "originalAmount": "15",
    "originalCurrency": "GBP"
}

The following /payment request example sends an MCP payment in EUR:

Example /payment Request
{
    "sessionToken": "<received from getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>",
    "amount": "18.551085208425",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "EUR",
    "paymentOption": {
        "alternativePaymentMethod": {
            "paymentMethod": "apmgw_Neteller",
            "nettelerAccount": "453313818311",
            "nettelerSecureId": "173419"
        }
    },
    "currencyConversion": {
        "type": "MCP",
        "originalAmount": "15",
        "originalCurrency": "GBP"
    },
    "billingAddress": {
        "email": "[email protected]",
        "country": "DE"
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    },
    "urlDetails": {
        "notificationUrl": "<URL to which DMNs are sent>"
    }
}
  • It is recommended to include a currencyConversion class in the payment request, because the request is processed as a Conversion on “Payment” request. It such a case, all the MCP currency conversions for the transaction are performed at the “time of payment” (when the customer presses the Pay button), using the ruling exchange rate.
  • If for some reason you do not include a currencyConversion class, then the request is processed as a Conversion on “Settlement” request, where two different MCP currency conversions are performed for the transaction:
    • The currency conversion for the customer’s payment is performed at the “time of payment” (when the customer presses the Pay button), using the ruling exchange rate.
    • The currency conversion for the merchant’s settlement payout is performed at the “time of settlement” (when the issuer pays out the merchant), using the ruling exchange rate.

4. Handling the Payment

When the Nuvei gateway receives your MCP /payment request (or an /openOrder request for Web SDK), before processing it, it first validates that the MCP amount (that you calculated) falls within an acceptable “tolerate”. This is to accommodate small discrepancies caused by rounding and exchange rate variances.

If the MCP payment is successful, then the customer is charged for the converted MCP amount in their home currency.

The MCP amount includes the additional exchange markup and other fees (which were “built into” the item prices). These fees are not shown as separate values anywhere in the transaction.

In due course, the Merchant receives the payout for the transaction in their home currency.

5. Performing a Payout

When the customer presses the Pay button (or equivalent) on the payment page, send a regular /payout request:

  • The checkout amount (in the customer’s home currency) as the transaction amount.
  • The MCP currency as the transaction currency.
  • Include a currencyConversion class:

    Currency conversion for payouts is only supported for credit cards.

    Example currencyConversion Class
    "currencyConversion": {
    "type": "MCP",
    "originalAmount": "15",
    "originalCurrency": "GBP"
}

The following /payout request example sends an MCP payment in EUR:

Example /payout Request
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "currencyConversion":{
    "type":"MCP",
    "originalAmount":"100",
    "originalCurrency":"EUR"
  },
  "userPaymentOption": {
    "cardData":{
      "cardNumber": "4000027891380961",
      "cardHolderName": "CL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "2025"
    }
  },  
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "urlDetails": {
    "notificationUrl": "<URL to which DMNs are sent>"
  }
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payout Request
{
  "cardData":{
    "acquirerId":"18",
    "visaDirect":"NO"
  },
  "reason":"",
  "transactionStatus":"APPROVED",
  "clientRequestId":"W3K51WL1A",
  "customData":"test",
  "internalRequestId":25184981,
  "merchantDetails":{
    "customField1":"customField1-value",
    "customField2":"customField2-value"
  },
  "version":"1.0",
  "transactionId":"2110000000008788114",
  "merchantSiteId":"126006",
  "gwExtendedErrorCode":0,
  "gwErrorCode":0,
  "merchantId":"2502136204546424962",
  "clientUniqueId":"695701003",
  "errCode":0,
  "userPaymentOptionId":"2152833001",
  "userTokenId":"L5T6XE6C7GVA",
  "externalTransactionId":"",
  "status":"SUCCESS"
}

6. Handling the Payout

When the Nuvei gateway receives your MCP /payout request, before processing it, it first validates that the MCP amount (that you calculated) falls within an acceptable “tolerate”. This is to accommodate small discrepancies caused by rounding and exchange rate variances.

If the MCP payout is successful, then the customer receives the payout in their home currency.

The MCP amount includes the additional exchange markup and other fees (which were “built into” the item prices). These fees are not shown as separate values anywhere in the transaction.

Last update iconLast modified September 2024