Moneris Multi-Currency Pricing Rate Lookup API

openapi: 3.2.0
info:
  version: 2.6.1
  title: Moneris Multi-Currency Pricing Rate Lookup API
  description: 'Moneris API Platform



    [<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height:32px;">](https://god.gw.postman.com/run-collection/25575461-f04750a0-88e9-4c83-8b58-a3aff15eeea8?action=collection%2Ffork&collection-url=entityId%3D25575461-f04750a0-88e9-4c83-8b58-a3aff15eeea8%26entityType%3Dcollection%26workspaceId%3D5d2a9a0f-57a7-441c-b2af-fe6315e80a08)'
  termsOfService: https://www.moneris.com/en/legal/terms-of-use
  contact:
    url: https://api-developer.moneris.com
    email: UnifiedAPI@moneris.com
  license:
    name: Moneris
    url: https://developer.moneris.com/Agreements/Terms%20of%20Use
  x-audience: external-public
servers:
- url: https://api.sb.moneris.io
  description: Sandbox server (uses test data)
  x-internal: false
- url: https://api.moneris.io
  description: Production server (uses live data)
  x-internal: false
tags:
- name: Multi-Currency Pricing Rate Lookup
  description: Retrieve Multi-Currency Pricing Rate Lookups
paths:
  /multi-currency-pricing-rates:
    parameters:
    - $ref: '#/components/parameters/apiVersion'
    - $ref: '#/components/parameters/correlationId'
    - $ref: '#/components/parameters/merchantId'
    post:
      summary: Multi-Currency Pricing Rate Lookup
      description: "Performs a foreign currency exchange rate look-up, and secures that exchange rate for use in a subsequent Multi-Currency Pricing financial transaction. \nThe exchange rate retrieved by this transaction request is represented in the response as the multiCurrencyPricingRateLookupId, and the underlying exchange rate is locked in for a limited time period.\n"
      operationId: mcpRate
      security:
      - OAuth2:
        - payment.write
      - ApiKeyAuth: []
      tags:
      - Multi-Currency Pricing Rate Lookup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/multiCurrencyPricingRateLookupRequest'
      responses:
        '207':
          $ref: '#/components/responses/multiCurrencyPricingRateLookup'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '422':
          $ref: '#/components/responses/unprocessableContent'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServer'
        '503':
          $ref: '#/components/responses/serviceUnavailable'
  /multi-currency-pricing-rates/{multi-currency-pricing-rate-lookup-id}:
    parameters:
    - $ref: '#/components/parameters/apiVersion'
    - $ref: '#/components/parameters/correlationId'
    - $ref: '#/components/parameters/multiCurrencyPricingRateLookupId'
    - $ref: '#/components/parameters/merchantId'
    get:
      summary: Retrieve Multi-Currency Pricing Rate by Id.
      description: Retrieve Multi-Currency Pricing Rate results by Id.
      operationId: getMultiCurrencyPricingRateById
      security:
      - OAuth2:
        - payment.read
      - OAuth2:
        - payment.write
      - ApiKeyAuth: []
      tags:
      - Multi-Currency Pricing Rate Lookup
      responses:
        '200':
          $ref: '#/components/responses/multiCurrencyPricingRateLookup'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServer'
        '503':
          $ref: '#/components/responses/serviceUnavailable'
components:
  schemas:
    multiCurrencyPricingRateMerchantSettlementInformation:
      type: object
      description: Multi-Currency Pricing (MCP) Rate Merchant Settlement Information Object
      properties:
        amountType:
          type: string
          description: The type of rate lookup to perform.
          enum:
          - MERCHANT_SETTLEMENT
          example: MERCHANT_SETTLEMENT
        amount:
          $ref: '#/components/schemas/money'
        cardholderCurrency:
          $ref: '#/components/schemas/currency'
      required:
      - amount
      - amountType
      - cardholderCurrency
    currency:
      type: string
      description: "Provides the three letter currency code according the ISO 4217 standard. \n\nFor a complete list of currency codes, visit: https://en.wikipedia.org/wiki/ISO_4217\n"
      minLength: 3
      maxLength: 4
      example: CAD
      format: iso-4217
    multiCurrencyPricingRateConversion:
      type: object
      description: Exchange rate for use in a subsequent MCP financial transaction
      properties:
        cardholderAmount:
          $ref: '#/components/schemas/money'
        merchantSettlementAmount:
          description: The amount that will be paid to the merchant, in settlement currency
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/amount'
            currency:
              $ref: '#/components/schemas/currency'
          required:
          - amount
          - currency
          example:
            amount: 16000
            currency: CAD
        multiCurrencyPricingExchangeRate:
          description: The foreign exchange rate (foreign currency to CAD) that will be used for the transaction
          type: number
          format: decimal
          example: 1.2346
        multiCurrencyPricingStatusCode:
          description: HTTP Status code of the MCP transaction
          type: integer
          format: int32
          minimum: 100
          maximum: 9999
          example: 200
        multiCurrencyPricingStatusMessage:
          description: Message corresponding to the MCP Status Code
          type: string
      required:
      - cardholderAmount
      - merchantSettlementAmount
      - multiCurrencyPricingExchangeRate
      - multiCurrencyPricingStatusCode
      - multiCurrencyPricingStatusMessage
      example:
        cardholderAmount:
          currency: USD
          amount: 30000
        merchantSettlementAmount:
          currency: CAD
          amount: 25000
        multiCurrencyPricingRate: 1.2345
        multiCurrencyPricingStatusCode: 200
        multiCurrencyPricingStatusMessage: OK
    multiCurrencyPricingRateLookupRequest:
      title: Multi-Currency Pricing (MCP) Rate Request
      type: object
      properties:
        multiCurrencyPricingTransactionType:
          $ref: '#/components/schemas/multiCurrencyPricingTransactionType'
        multiCurrencyPricingRateInformationRequests:
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/multiCurrencyPricingRateInformationRequest'
          example:
          - amount:
              currency: USD
              amount: 3000
            amountType: CARDHOLDER
          - amount:
              currency: USD
              amount: 4015
            cardholderCurrency: USD
            amountType: MERCHANT_SETTLEMENT
        customData:
          $ref: '#/components/schemas/customData'
      required:
      - multiCurrencyPricingTransactionType
      - multiCurrencyPricingRateInformationRequests
    dateTime:
      type: string
      format: date-time
      example: '2019-07-30T06:43:40.252Z'
      description: Date & Time
    customData:
      description: Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.
      type:
      - object
      - 'null'
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 50
      maxProperties: 10
    multiCurrencyPricingRateCardholderInformation:
      type: object
      description: Multi-Currency Pricing (MCP) Rate Information Object
      properties:
        amountType:
          type: string
          description: The type of rate lookup to perform.
          enum:
          - CARDHOLDER
          example: CARDHOLDER
        amount:
          $ref: '#/components/schemas/money'
      required:
      - amount
      - amountType
    parameterError:
      title: Parameter error
      description: Request property or header related error.
      type: object
      properties:
        parameterName:
          type: string
          description: Property or header name. Can contain nested path separated by '.'
          example: address.postalCode
        parameterValue:
          type:
          - string
          - 'null'
          description: Property or header value string representation.
          example: MAP3J8
        reasonCode:
          type: string
          description: Reason that triggered the error.
          enum:
          - INVALID_FORMAT
          - REQUIRED_FIELD
          - INVALID_VALUE
          example: INVALID_FORMAT
        errorMessage:
          type:
          - string
          - 'null'
          description: Human readable description of the error.
          example: String 'MAP3J8' does not match the postal code pattern.
      required:
      - parameterName
      - reasonCode
    multiCurrencyPricingRateLookup:
      title: Multi-Currency Pricing (MCP) Rate Response
      type: object
      properties:
        multiCurrencyPricingRateLookupId:
          $ref: '#/components/schemas/resourceId'
        multiCurrencyPricingTransactionType:
          $ref: '#/components/schemas/multiCurrencyPricingTransactionType'
        rateValidityEndTime:
          $ref: '#/components/schemas/dateTime'
        rateConversions:
          type: array
          items:
            $ref: '#/components/schemas/multiCurrencyPricingRateConversion'
          example:
          - cardholderAmount:
              amount: 3000
              currency: USD
            merchantSettlementAmount:
              amount: 4024
              currency: CAD
            multiCurrencyPricingExchangeRate: 1.3413
            multiCurrencyPricingStatusCode: 200
            multiCurrencyPricingStatusMessage: ''
          - cardholderAmount:
              amount: 2993
              currency: USD
            merchantSettlementAmount:
              amount: 4015
              currency: CAD
            multiCurrencyPricingExchangeRate: 1.3413
            multiCurrencyPricingStatusCode: 200
            multiCurrencyPricingStatusMessage: ''
        customData:
          description: Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 50
          maxProperties: 10
        createdAt:
          $ref: '#/components/schemas/createdAt'
      required:
      - multiCurrencyPricingRateLookupId
      - multiCurrencyPricingTransactionType
      - rateValidityEndTime
      - rateConversions
      - createdAt
    multiCurrencyPricingRateInformationRequest:
      description: Multi-Currency Pricing (MCP) Rate Information Request Object
      oneOf:
      - $ref: '#/components/schemas/multiCurrencyPricingRateCardholderInformation'
      - $ref: '#/components/schemas/multiCurrencyPricingRateMerchantSettlementInformation'
      discriminator:
        propertyName: amountType
        mapping:
          CARDHOLDER: '#/components/schemas/multiCurrencyPricingRateCardholderInformation'
          MERCHANT_SETTLEMENT: '#/components/schemas/multiCurrencyPricingRateMerchantSettlementInformation'
    createdAt:
      description: Time at which the object was created
      type: string
      format: date-time
      example: '2019-07-30T06:43:40.252Z'
    error:
      description: Error response details.
      properties:
        type:
          description: 'A URI reference that identifies the problem type.  Ideally it should be a stable URL to the documentation of the details about this type of error but it also can be a URN.  If nothing can be provided, a "about:blank" value is returned.

            '
          type: string
          format: uri
          example: https://api-developer.moneris.com/responsehandling
        title:
          description: 'A short, human-readable summary of the problem type.   It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization

            '
          type:
          - string
          - 'null'
          example: INSUFFICIENT_FUNDS
        status:
          description: 'it conveys the HTTP status code used for the convenience of the consumer.

            '
          type:
          - integer
          - 'null'
          format: int32
          minimum: 100
          maximum: 505
        detail:
          description: 'A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

            '
          type:
          - string
          - 'null'
          example: Funds are insufficient to execute the operation.
        instance:
          description: 'A URI reference that identifies the specific occurrence of the problem. Typically, this resolves to a resource that might include more details about the problem.

            '
          type:
          - string
          - 'null'
          example: /payments/12f3e0a8-1d68-2b86-dd30-4ca51bb66e10
          format: uri-reference
        category:
          description: "The type of error returned. \n - `API_ERROR`: This occurs due to an intermittent issue.  \n - `IDEMPOTENCY_ERROR`: The idempotency key has already been used.\n - `INVALID_REQUEST_ERROR`: The data provided in the request is invalid.\n - `DECLINED_ERROR`: Transaction was declined by the issuer.\n - `UNAUTHORIZED_ERROR`: Caller not authenticated, or not allowed to execute the current operation.\n - `INTERNAL_SERVER_ERROR`: An internal issue with our servers has occured.\n"
          enum:
          - API_ERROR
          - IDEMPOTENCY_ERROR
          - INVALID_REQUEST_ERROR
          - DECLINED_ERROR
          - UNAUTHORIZED_ERROR
          - INTERNAL_SERVER_ERROR
          - null
          type:
          - string
          - 'null'
          example: DECLINED_ERROR
        errors:
          type: array
          description: List of validation errors when error category is INVALID_REQUEST_ERROR.
          items:
            type: object
            $ref: '#/components/schemas/parameterError'
          example:
          - parameterName: address.postalCode
            parameterValue: MAP3J8
            errorMessage: address.Postal code does not match regular expression
            reasonCode: INVALID_FORMAT
      title: API Error
      type: object
      required:
      - type
    money:
      type: object
      description: "Monetary amount. \nNote: The value must be in cents. Therefore $10.59 must be sent as 1059.\n"
      properties:
        amount:
          $ref: '#/components/schemas/amount'
        currency:
          $ref: '#/components/schemas/currency'
      required:
      - amount
      - currency
      example:
        amount: 16000
        currency: CAD
    apiVersion:
      description: 'The endpoint''s API Version.  Must be provided through headers.

        '
      type: string
      example: '2025-08-14'
      default: '2025-08-14'
    multiCurrencyPricingTransactionType:
      type: string
      description: Value representing the type of subsequent transaction request that the rate token will be used for
      enum:
      - PAYMENT
      - REFUND
      example: PAYMENT
    merchantId:
      type: string
      description: "Thirteen character long identification provided to merchants by Moneris. \n"
      minLength: 13
      maxLength: 13
      example: 0123456789101
    resourceId:
      type: string
      description: Used to identify API resources which may be required for future follow-on transactions; i.e. Refunds, Corrections, Completions, Reversals, etc.
      pattern: ^[A-Za-z]{2}\d{2}[A-Za-z0-9]{26}$
      minLength: 30
      maxLength: 30
      example: pi0105ARZ3NDEKTSV4RRFFQ69G5FAV
    amount:
      type: integer
      format: int32
      minimum: 0
      maximum: 999999999
      example: 10000
      description: Amount
  parameters:
    multiCurrencyPricingRateLookupId:
      in: path
      name: multi-currency-pricing-rate-lookup-id
      description: The unique identifier of the multiCurrencyPricing Rate Operation
      required: true
      schema:
        $ref: '#/components/schemas/resourceId'
    correlationId:
      in: header
      name: X-Correlation-Id
      example: 06f1e47b-a1b5-4902-be9c-bccc506127c4
      description: "Correlates a series of requests within the same flow.\n\nNote: This ID is generated by Moneris with every request or response, if it doesn't exist. \nMerchants are to echo back the value with every request that is part of the call flow.\"\n"
      required: false
      schema:
        type: string
        example: 06f1e47b-a1b5-4902-be9c-bccc506127c4
    apiVersion:
      in: header
      name: Api-Version
      required: true
      example: '2024-09-17'
      description: "The endpoint's API Version. \n\nMust be provided through the headers section. \n"
      schema:
        $ref: '#/components/schemas/apiVersion'
    merchantId:
      in: header
      name: X-Merchant-Id
      example: 0123456789101
      description: "Thirteen character identification code. \n\nNote: This code is provided by Moneris and is required to identify the Merchant executing the transaction.\"\n"
      required: true
      schema:
        $ref: '#/components/schemas/merchantId'
  responses:
    unauthorized:
      description: Not authorized. The user does not have a valid API Key or Access Token.
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
        WWW-Authenticate:
          schema:
            type: string
            example: Bearer, error="invalid_token"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            type: https://developer.moneris.com/en/More/Testing/Response%20Codes
            title: UNAUTHORIZED_REQUEST
            status: 401
            detail: null
            instance: null
            category: UNAUTHORIZED_ERROR
            errors: []
    serviceUnavailable:
      description: Service Temporarily Unavailable
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        Retry-After:
          $ref: '#/components/headers/retryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            type: https://api-developer.moneris.com/responsehandling/
            title: SERVICE_UNAVAILABLE
            status: 503
            detail: null
            instance: null
            category: INTERNAL_SERVER_ERROR
            errors: []
    forbidden:
      description: Forbidden. The user does not have permission to access the requested resource.
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
        WWW-Authenticate:
          schema:
            type: string
            example: Bearer, error="insufficient_scope"
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            type: https://developer.moneris.com/en/More/Testing/Response%20Codes
            title: FORBIDDEN_REQUEST
            status: 403
            detail: null
            instance: null
            category: UNAUTHORIZED_ERROR
            errors: []
    multiCurrencyPricingRateLookup:
      description: Multi-Currency Pricing (MCP) Rate lookup Response
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/multiCurrencyPricingRateLookup'
    internalServer:
      description: Unexpected error.
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            type: https://api-developer.moneris.com/responsehandling/
            title: INTERNAL_SERVER_ERROR
            status: 500
            detail: null
            instance: null
            category: INTERNAL_SERVER_ERROR
            errors: []
    tooManyRequests:
      description: Too Many Requests
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/rateLimitReset'
        Retry-After:
          $ref: '#/components/headers/rateLimitReset'
    badRequest:
      description: Bad Request.
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
    unprocessableContent:
      description: "The API cannot complete the requested action due to semantic or business validation errors. \n"
      headers:
        Api-Version:
          $ref: '#/components/headers/apiVersion'
        X-Correlation-Id:
          $ref: '#/components/headers/correlationId'
        Sunset:
          $ref: '#/components/headers/sunset'
        X-RateLimit-Limit:
          $ref: '#/components/headers/rateLimitCount'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/rateLimitRemaining'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'An API key is a token that a client provides when making API calls.


        API keys are supposed to be a secret that only the client and server know about.

        '
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.


        OAuth relies on authentication scenarios, that allows the resource owner (user) to share the protected content from the server, hosting the resource, without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner.


        Moneris recommends the use of OAuth 2.0 as it provides fine grained authorization levels.

        '
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            payment.read: Grants read access to payment related APIs
            payment.write: Grants read & write access to payment related APIs
            refund.read: Grants read access to refunds
            refund.write: Grants read & write access to refunds
            customer.read: Grants read access to customer data
            customer.write: Grants read & write access to customer data
            kount.read: Grants read access to Kount inquiries
            kount.write: Grants read & write access to Kount inquiries
            onboarding.merchant.read: Grants read access to merchant onboarding related APIs
            onboarding.merchant.write: Grants read & write access to merchant onboarding related APIs
            onboarding.order.read: Grants read access to onboarding orders related APIs
            onboarding.order.write: Grants read & write access to onboarding orders related APIs
            dispute.read: Grants read access to disputes
            dispute.write: Grants read & write access to disputes