---
title: "Surcharge Lookup"
method: POST
path: "/surcharge-lookups"
tags: ["Surcharge Lookup"]
---

# Surcharge Lookup

`POST /surcharge-lookups`

Performs surcharge lookup and determines if payment method is eligible or not and provides max rate and max amount if eligible.

## Request body

- SurchargeEligibilityRequest
  - `idempotencyKey` string, required — A Unique Identifier that is required for handling idempotent requests. Note: Moneris encourages the use of UUID Version 4 in APIs as an idempotency key."
  - `amount` object, required — This is for surcharge amount.
    - `amount` integer, required — Amount
    - `currency` string, iso-4217, required — Provides the three letter currency code according the ISO 4217 standard. For a complete list of currency codes, visit: https://en.wikipedia.org/wiki/ISO_4217
  - `paymentMethod` union, required — surcharge payment Method details. Note: If defined, this will result in the creation of a Permanent Payment Method as defined in the Payment Method API.
    - PaymentMethodWithId — Use existing unique payment method identifier.
      - `paymentMethodSource` 'PAYMENT_METHOD_ID' | 'CARD' | 'TEMPORARY_TOKEN' | 'PERMANENT_TOKEN' | 'APPLE_PAY_ENCRYPTED' | 'APPLE_PAY_DECRYPTED' | 'GOOGLE_PAY_ENCRYPTED' | 'GOOGLE_PAY_DECRYPTED', required — The source of Payment Method being used. It can be: - The Id of a Payment Method already created. - Permanent Token. - Temporary Token. - Card. - E-Wallet.
      - `paymentMethodId` string, required — Unique Identifier of the payment method.
    - PaymentMethodCard — Payment Method details. Note: If defined, this will result in the creation of Payment Method as defined in the Payment Method API.
      - `card` Card, required — Card details
        - `cardNumber` string, required — Identifies the customer's credit or debit card number (Primary Account Number).
        - `expiryMonth` integer, required — Card expiration month. Format must be MM
        - `expiryYear` integer, required — Displays the card expiration year. Accepted format: YYYY
        - `cardSecurityCode` string, required — CVD value located on credit card. The CVD value (supplied by the cardholder) must only be passed to the payment gateway. Under no circumstances may it be stored for subsequent use or displayed as part of the receipt information.
      - `cardholderInformation` CardholderInformation, nullable — Information about the holder of the card.
        - `cardholderName` string, required — Cardholder name
        - `companyName` string, nullable — Identifies the associated company name
      - `contactDetails` ContactDetails, nullable — Contact details
        - `phoneNumber` string, nullable — Phone number.
        - `email` string, email, nullable — Contains the customer's email address. For standard email protocols, visit: https://www.rfc-editor.org/rfc/rfc5322
      - `billingAddress` object, nullable — The postal address including street, town/city, province, and postal code. Optionally an unit number can be provided.
        - `unitNumber` string, nullable — Unit number
        - `streetNumber` string, nullable — Street number
        - `streetName` string, nullable — Street name
        - `city` string, nullable — Identifies the city.
        - `province` string, iso-3166-2, nullable — Province or state ISO 3166-2 code
        - `postalCode` string, nullable — Postal or zip code
        - `country` string, iso-3166, nullable — Provides the two letter country code according the ISO 3166-1 alpha-2 standard. For a complete list of country codes, visit: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
      - `paymentMethodSource` 'PAYMENT_METHOD_ID' | 'CARD' | 'TEMPORARY_TOKEN' | 'PERMANENT_TOKEN' | 'APPLE_PAY_ENCRYPTED' | 'APPLE_PAY_DECRYPTED' | 'GOOGLE_PAY_ENCRYPTED' | 'GOOGLE_PAY_DECRYPTED', required — The source of Payment Method being used. It can be: - The Id of a Payment Method already created. - Permanent Token. - Temporary Token. - Card. - E-Wallet.
      - `customData` CustomData, nullable — Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.
    - PaymentMethodTemporaryToken — Payment Method details. Note: If defined, this will result in the creation of Payment Method as defined in the Payment Method API.
      - `temporaryToken` string, required — Created when a temporary token is created and returned. This acts as a unique profile identifier, and is a required value for temporary token transactions.
      - `cardholderInformation` CardholderInformation, nullable — Information about the holder of the card.
        - `cardholderName` string, required — Cardholder name
        - `companyName` string, nullable — Identifies the associated company name
      - `contactDetails` ContactDetails, nullable — Contact details
        - `phoneNumber` string, nullable — Phone number.
        - `email` string, email, nullable — Contains the customer's email address. For standard email protocols, visit: https://www.rfc-editor.org/rfc/rfc5322
      - `billingAddress` object, nullable — The postal address including street, town/city, province, and postal code. Optionally an unit number can be provided.
        - `unitNumber` string, nullable — Unit number
        - `streetNumber` string, nullable — Street number
        - `streetName` string, nullable — Street name
        - `city` string, nullable — Identifies the city.
        - `province` string, iso-3166-2, nullable — Province or state ISO 3166-2 code
        - `postalCode` string, nullable — Postal or zip code
        - `country` string, iso-3166, nullable — Provides the two letter country code according the ISO 3166-1 alpha-2 standard. For a complete list of country codes, visit: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
      - `paymentMethodSource` 'PAYMENT_METHOD_ID' | 'CARD' | 'TEMPORARY_TOKEN' | 'PERMANENT_TOKEN' | 'APPLE_PAY_ENCRYPTED' | 'APPLE_PAY_DECRYPTED' | 'GOOGLE_PAY_ENCRYPTED' | 'GOOGLE_PAY_DECRYPTED', required — The source of Payment Method being used. It can be: - The Id of a Payment Method already created. - Permanent Token. - Temporary Token. - Card. - E-Wallet.
      - `customData` CustomData, nullable — Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.
    - PaymentMethodPermanentToken — Payment Method details. Note: If defined, this will result in the creation of Payment Method as defined in the Payment Method API.
      - `permanentToken` string, required — Created when a temporary token is created and returned. This acts as a unique profile identifier, and is a required value for temporary token transactions.
      - `cardholderInformation` CardholderInformation, nullable — Information about the holder of the card.
        - `cardholderName` string, required — Cardholder name
        - `companyName` string, nullable — Identifies the associated company name
      - `contactDetails` ContactDetails, nullable — Contact details
        - `phoneNumber` string, nullable — Phone number.
        - `email` string, email, nullable — Contains the customer's email address. For standard email protocols, visit: https://www.rfc-editor.org/rfc/rfc5322
      - `billingAddress` object, nullable — The postal address including street, town/city, province, and postal code. Optionally an unit number can be provided.
        - `unitNumber` string, nullable — Unit number
        - `streetNumber` string, nullable — Street number
        - `streetName` string, nullable — Street name
        - `city` string, nullable — Identifies the city.
        - `province` string, iso-3166-2, nullable — Province or state ISO 3166-2 code
        - `postalCode` string, nullable — Postal or zip code
        - `country` string, iso-3166, nullable — Provides the two letter country code according the ISO 3166-1 alpha-2 standard. For a complete list of country codes, visit: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
      - `paymentMethodSource` 'PAYMENT_METHOD_ID' | 'CARD' | 'TEMPORARY_TOKEN' | 'PERMANENT_TOKEN' | 'APPLE_PAY_ENCRYPTED' | 'APPLE_PAY_DECRYPTED' | 'GOOGLE_PAY_ENCRYPTED' | 'GOOGLE_PAY_DECRYPTED', required — The source of Payment Method being used. It can be: - The Id of a Payment Method already created. - Permanent Token. - Temporary Token. - Card. - E-Wallet.
      - `customData` CustomData, nullable — Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.

## Response `200`

surcharge eligible response

- SurchargeEligibility
  - `merchantId` string, required — Thirteen character long identification provided to merchants by Moneris.
  - `amount` object, required — Represents the surcharge amount
    - `amount` integer, required — Amount
    - `currency` string, iso-4217, required — Provides the three letter currency code according the ISO 4217 standard. For a complete list of currency codes, visit: https://en.wikipedia.org/wiki/ISO_4217
  - `surchargeMessage` string, required — Message indicating surcharge eligibility status
  - `maximumSurchargeRate` number, double, required — Maximum surcharge rate applicable
  - `maximumSurchargeAmount` Money, required — Monetary amount. Note: The value must be in cents. Therefore $10.59 must be sent as 1059.
    - `amount` integer, required — Amount
    - `currency` string, iso-4217, required — Provides the three letter currency code according the ISO 4217 standard. For a complete list of currency codes, visit: https://en.wikipedia.org/wiki/ISO_4217
  - `paymentMethod` PaymentMethod, required — Payment method response object
    - `paymentMethodId` string, required — Unique Identifier of the payment method.
    - `merchantId` string, required — Thirteen character long identification provided to merchants by Moneris.
    - `cardholderInformation` CardholderInformation, nullable — Information about the holder of the card.
      - `cardholderName` string, required — Cardholder name
      - `companyName` string, nullable — Identifies the associated company name
    - `contactDetails` ContactDetails, nullable — Contact details
      - `phoneNumber` string, nullable — Phone number.
      - `email` string, email, nullable — Contains the customer's email address. For standard email protocols, visit: https://www.rfc-editor.org/rfc/rfc5322
    - `billingAddress` object, nullable — The postal address including street, town/city, province, and postal code. Optionally an unit number can be provided.
      - `unitNumber` string, nullable — Unit number
      - `streetNumber` string, nullable — Street number
      - `streetName` string, nullable — Street name
      - `city` string, nullable — Identifies the city.
      - `province` string, iso-3166-2, nullable — Province or state ISO 3166-2 code
      - `postalCode` string, nullable — Postal or zip code
      - `country` string, iso-3166, nullable — Provides the two letter country code according the ISO 3166-1 alpha-2 standard. For a complete list of country codes, visit: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
    - `paymentMethodInformation` CardPaymentMethodInformation, required — Details about the card used in the payment method.
      - `paymentMethodType` 'CARD', required — The type of Payment Method being used. It can be: - Card.
      - `paymentMethodSource` 'CARD' | 'TEMPORARY_TOKEN' | 'PERMANENT_TOKEN' | 'APPLE_PAY_ENCRYPTED' | 'APPLE_PAY_DECRYPTED' | 'GOOGLE_PAY_ENCRYPTED' | 'GOOGLE_PAY_DECRYPTED', required — The source of Payment Method being used. It can be: - The Id of a Payment Method already created. - Permanent Token. - Temporary Token. - Card. - E-Wallet.
      - `cardInformation` CardInformation, required — Information about the card being used for the transaction
        - `bankIdentificationNumber` string, nullable — **BIN**: Bank Identification Number Consists of the first six to eight digits of the Primary Account Number (PAN) and identifies the relevant payment network and the specific payment issuing institution.
        - `lastFour` string, nullable — Last 4 digits of the card.
        - `expiryMonth` integer — Card expiration month. Format must be MM
        - `expiryYear` integer — Displays the card expiration year. Accepted format: YYYY
        - `cardBrand` 'MASTERCARD' | 'VISA' | 'AMERICAN_EXPRESS' | 'JCB' | 'DISCOVER' | 'INTERAC' | 'UNIONPAY' | 'GIFT_MONERIS' | 'GIFT_DATACANDY' | 'GIFT_GIVEX' | 'null', nullable — Displays the card brand name associated with the card type.
        - `cardType` 'CREDIT' | 'DEBIT' | 'DOMESTIC_DEBIT' | 'PREPAID_RELOADABLE' | 'PREPAID_NON_RELOADABLE' | 'UNKNOWN' | 'GIFT' | 'LOYALTY' | 'FLEET' | 'CORPORATE', nullable — Specifies the intended card use; i.e. debit or credit.
        - `cardFingerprint` string, nullable — Unique card identifier. Fingerprinting randomly assigns identfiers for cards that share the same Primary Account Number (PAN) to easily identify when multiple payments methods are attached to the same underlying card, and assists merchants identify individual customers across various channels; i.e. loyalty programs.
        - `issuer` string, nullable — Card issuer.
      - `paymentAccountReference` string, nullable — Used to link Primary Account Number (PAN) based transactions and transactions on associated payment tokens without using the PAN as the linking mechanism.
      - `storePaymentMethod` 'DO_NOT_STORE' | 'CARDHOLDER_INITIATED' | 'MERCHANT_INITIATED', required — Store this payment method created through this payment for future use. - DO_NOT_STORE: Payment method will not be stored. - CARDHOLDER_INITIATED: Payment method to be stored and can only re-used with cardholder's consent. Limited to store, pre-authorisation, and card validations." - MERCHANT_INITIATED: Payment method to be stored and can be reused without the cardholder's consent. For example, subscriptions.
    - `createdAt` string, date-time, required — Time at which the object was created
    - `modifiedAt` string, date-time, nullable — Time at which the object was modified
    - `customData` CustomData, nullable — Merchant can send custom meta data with the transaction in this object. Moneris will echo these values back in response.

## Other responses

- `400` — Bad Request.
- `401` — Not authorized. The user does not have a valid API Key or Access Token.
- `403` — Forbidden. The user does not have permission to access the requested resource.
- `409` — Request could not be completed due to a conflict with resource state or existing idempotency key.
- `422` — The API cannot complete the requested action due to semantic or business validation errors.
- `429` — Too Many Requests
- `500` — Unexpected error.
- `503` — Service Temporarily Unavailable

---

[API](https://skmtc.net/moneris/apis/moneris-api.md) · [All operations](https://skmtc.net/moneris/apis/moneris-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/moneris/moneris-api/versions/edefcc925b74/schema)