GuidesAPI ReferenceChangelog
Log In
Guides
  1. Moneris API
  2. Online Payments - Scenarios
  3. Currency & Fee Management

Multi-Currency Pricing (MCP)

Overview

Multi-Currency Pricing (MCP) is a financial service which allows businesses to price goods and services in a variety of foreign currencies, while continuing to receive settlement and reporting in Canadian dollars. MCP allows cardholders to shop, view prices and pay in the currency of their choice.

NOTE: Use MCP only when processing transactions that involve foreign currency exchange; for transactions strictly in Canadian dollars, use the basic financial transaction requests


1. Getting Started with Multi-Currency Pricing (MCP)

To begin processing Multi-Currency Pricing (MCP) transactions on your store, you will need to call Moneris Sales Support to activate this feature on your store.


📘

Moneris Sales Support

Phone: 1-855-465-4980


2. Methods of Processing MCP Transactions

There are two methods of processing MCP transactions via the Moneris API:

  1. Using the Multi-Currency Pricing Rate Lookup API call – this method is used to obtain a foreign exchange rate and locks that specific rate in for a limited time, and is applied in a subsequent transaction
  2. Without using the Multi-Currency Pricing Rate Lookup API call – this method sends a MCP transaction without performing the Rate Lookup request, and the foreign exchange rate is obtained at processing time

3. Multi-Currency Pricing Rate Lookup (Optional)

This API call performs a foreign currency exchange rate look-up, and secures that exchange rate for use in a subsequent MCP financial transaction.


📘

Request

This API performs a POST request on /multi-currency-pricing-rates. Some important request fields to note about this API call include:

  • multiCurrencyPricingTransactionType (Enum)

Specifies the type of transaction for which the rate is being requested. This ensures Moneris applies the correct pricing logic.

Possible values:

  • PAYMENT
  • REFUND

This field is required and determines how the rate is calculated based on transaction type.

  • multiCurrencyPricingRateInformationRequests (Array of Objects)

    This is a required array containing one or more rate lookup requests. Each object in the array must include:

    • amountType (Enum):

      • MERCHANT_SETTLEMENT: The amount is in the merchant's currency. Moneris will calculate the equivalent cardholder amount.

      • CARDHOLDER_AMOUNT: The amount is in the cardholder's currency. Moneris will calculate the equivalent merchant amount.

    • amount (Object):

      • amount: Integer value in cents (e.g., $10.59 → 1059)

      • currency: ISO currency code (e.g., CAD, USD)

    • cardholderCurrency (Required only if amountType is MERCHANT_SETTLEMENT):

      • The ISO currency code representing the cardholder’s preferred currency (e.g., USD, EUR)

📘

Response

In the response of a Multi-Currency Pricing Rate Lookup request, you will receive:

  • multiCurrencyPricingRateLookupId:

A unique identifier for the rate lookup request. This will be passed to use the retrieved rate in the corresponding MCP transaction.

  • multiCurrencyPricingTransactionType:

Echoes the transaction type used in the request.

  • rateValidityEndTime :

Timestamp indicating when the returned rate expires.

  • rateConversions (Array of Objects):

Contains conversion details for each request:

  • cardholderAmount: Amount in the cardholder's currency.
  • merchantSettlementAmount: Amount in the merchant's currency.
  • multiCurrencyPricingExchangeRate: The exchange rate used.
  • multiCurrencyPricingStatusCode: Status code indicating success or failure.
  • multiCurrencyPricingStatusMessage: Human-readable message describing the result.

4. Create Payment with MCP

MCP Purchases and Pre-Authorizations can be performed using the Create Payment API request. Some key things to note about an MCP transaction include:

  • amount (Object)

This is a required object.

  • amount (integer): Specifies the amount of the transaction in the cardholder's currency.
  • currency (string): Specifies the cardholder's currency
  • multiCurrencyPricing (Object)

This enables you to specify information pertaining to your MCP transactions.

  • multiCurrencyPricingOptIn (enum - required)

    • OPT_IN: Indicates that the transaction will be performing with MCP.

  • multiCurrencyPricingRateLookupId (string)

    • Enables you to use the rate from a Multi-Currency Pricing Rate Lookup request.

{
  "idempotencyKey": "5d8f812e-9969-4885-85bb-d03948eccac1",
  "orderId": "1q2w3e4r5t6t78",
  "amount": {
    "amount": 100,
    "currency": "USD"
  },
  "paymentMethod": {
    "paymentMethodData": {
      "paymentMethodSource": "CARD",
      "card": {
        "cardNumber": "4242424242424242",
        "expiryMonth": 11,
        "expiryYear": 2029,
        "cardSecurityCode": 123
      }
    }
  },
  "multiCurrencyPricing": {
    "multiCurrencyPricingOptIn": "OPT_IN",
    "multiCurrencyPricingRateLookupId": "mc0105ARZ3NDEKTSV4RRFFQ69G5FAV"      
  },    
  "ecommerceIndicator": "SSL_MERCHANT",
  "automaticCapture": true
}

5. Follow-On Transactions with MCP

Similarly to conventional Payment transactions, you can perform follow-on transactions for MCP Payments. Such follow-on transactions include:

  1. Cancel Payment: Void an MCP transaction.
  2. Complete Payment: Complete an MCP Pre-Authorization (Create Payment with automaticCapture = false).
  3. Create Refund: Perform a Matching Refund on an MCP transaction or perform an Independent Refund using MCP.

For Complete Payments and Create Refunds with MCP, you can perform a Multi-Currency Pricing Rate Lookup to secure an exchange rate prior to your follow-on transaction.


Additional Information

📘

Learn more with the API Definitions

Peruse the endpoints, request/response formats, and authentication methods covered in this scenario.

API References

Updated 14 days ago