Overview

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

In addition:

• Keep your product catalog in your home currency.
• Price your goods in multiple customer currencies.
• Let your customer pay in the customer’s home currency.
• Receive your transaction settlements and reporting in your home currency.

For Web SDK and REST API

To integrate MCP into the Web SDK and REST API payment flows:

1. Retrieving MCP Rates

Nuvei updates all currency exchange rates at scheduled intervals (currently once per day). Use the GET /currencies/entities/{processing-entity-id}/rates method to retrieve all the latest MCP currency conversion rates for the currencies that you support (as specified in your MCP agreement with Nuvei).

To receive MCP currency conversion for payouts, the merchant must provide rateType in the GET /currencies/entities/{processing-entity-id}/rates request. If not provided in the request, the MCP rates are returned for payment.

The following example retrieves MCP details for one toCurrency. A more typical scenario is to list all your MCP currencies in the toCurrency array, as follows:
GET /currencies/entities/{processing-entity-id}/rates?from_currency=EUR&to_currencies=EUR,JPY,USD&payment_methods=card

Response example

{
    "rates": [
        {
            "paymentMethod": "card",
            "fromCurrency": "EUR",
            "toCurrency": "USD",
            "rate": 1.218636
        }
    ],
    "rate_type": "payment",
    "result": {
        "status": "success"
    }
}

2. Converting Site Pricing

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

If a visitor enters your site, you must run processes to identify the visitor’s home currency, based on criteria that you determine. For example, you can do any of the following:

• Identify the visitor’s location based on the visitor’s IP address and then look up the local currency.
• Prompt the visitor to select a preferred currency from a list of your MCP currencies.
• 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 GET /currencies/entities/{processing-entity-id}/rates for the specific currency.
• Use the MCP currency conversion rate to convert all the prices displayed on your site into the visitor’s home currency.

3. Accepting a Payment

If a customer presses the Pay button (or equivalent) on the payout page, send a regular /payment request (or an /order request for Web SDK 2.0) using the following details:

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

Example currencyConversion Class

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

• It is recommended to include a currencyConversion class in the payment request, because the request is processed as a Conversion on “Payment” request. In 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 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 of 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 of 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 a Payment

When the Nuvei gateway receives your MCP /payment request (or an /order request for Web SDK), before processing the request the system first validates that the MCP amount (that you calculated) falls within the 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 the customer’s home currency.

The Merchant receives the payout for the transaction in the customer’s home currency.

5. Performing a Payout

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

• Checkout amount (in the customer’s home currency) is the transaction amount.
• MCP currency is the transaction currency.
• Include a currencyConversion class.

Example currencyConversion Class

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

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

Example /payout Request

{
    "processingEntityId": "",
    "amount": 60,
    "currency": "EUR",
    "paymentOption": {
        "card": {
            "cardHolderName": "John Doe",
            "cardNumber": "4444493318246892",
            "expirationMonth": "12",
            "expirationYear": "2025",
            "cvv": "090"
        },
        "store": "buyerToken"
    },
    "currencyConversion": {
        "type": "MCP",
        "originalAmount": "15",
        "originalCurrency": "GBP"
    },
    "buyerDetails": {
        "buyerId": "test1233ssw2",
        "firstName": "John",
        "lastName": "JSmith",
        "companyName": "Nuvei Corp",
        "locale": "bg-BG",
        "dateOfBirth": "1978-01-01",
        "email": "[email protected]",
        "phone": "+1234567889",
        "billingAddress": {
            "state": "TX",
            "city": "Austin",
            "zip": "78652",
            "countryCode": "US"
        },
        "shippingAddress": {
            "sameAsBilling": true
        }
    }
}

Example /payout response

{
  "payoutId": "90c619e830be4ca7b8e5172b49295c24",
  "transactionId": "8110000000009476094",
  "amount": 60,
  "currency": "EUR",
  "authCode": "111607",
  "paymentOption": {
    "card": {
      "cardHolderName": "John Doe",
      "maskedCardNumber": "4****6892",
      "bin": "444449",
      "last4Digits": "6892",
      "expirationMonth": "12",
      "expirationYear": "25",
      "acquirerId": "19",
      "cardType": "Credit",
      "cardBrand": "VISA",
      "paymentTokenId": "15772023aa884be9ae0261ead2521672"
    }
  },
  "result": {
    "status": "approved"
  }
}

6. Handling a Payout

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

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