Skip to main content
Skip table of contents

Level 2 / Level 3 Data Submission via API - Canada

Use the Payrix API to submit Level 2/3 qualifying transactions.

Introduction

This document will guide you through the requirements and the process of Level 2/3 transactional data submission and qualifying interchange rates.

If any of the required data is missing with a payment submission, the transaction may be downgraded and lack qualification for Level 2/3 data interchange rates as a result.

Fields and Data Requirements

Use these links to view the general API reference for transaction submission:

Overall Level 2 Data Requirements

Tax Amount is required for both Visa and MasterCard transactions. For Visa, the tax amount must be between 0.1% - 22% of the payment total, and between 0.1% - 30% for MasterCard transactions. This value is sent via the txns.tax field when submitting either a Sale or a Capture transaction type (note: txns.tax value for authorization is not used)

Order Number (or Custom Code) is required for MasterCard payments only (also see specific Visa requirements for Large Ticket further down on the page). This field cannot be blank for a Sale or capture request to meet MasterCard’s Level 2 qualifications and should be sent in txns.order field.

Overall Level 3 Data Requirements

Below are the non-line item data fields required for Level 3 transaction submission (in addition to the above Level 2 requirements).

Note: Any field with no desired value or 0 must be submitted with a valid value of 0.

  • Field values with null or that are left blank will not be accepted.

To avoid confusion, please note: Order Number (Custom Code) and Invoice are interchangeable terms for Level 3 processing fields.

txns.discount
txns.shipping
txns.duty

Below are line item data fields required for Level 3

  • These are the fields required by both Visa and Mastercard:
    items[].productCode
    items[].item
    items[].description
    items[].quantity
    items[].um
    items[].total

  • These fields are required by Visa in addition to the above fields:
    items[].discount
    items[].commodityCode
    items[].price

Sample Data

JSON
{
   "merchant":"t1_mer_12345",
   "payment":{
      "number":"4111111111111111",
      "cvv":"123"
   }
   "expiration":"1224",
   "type":2,
   "order":"INVOICE#1",
   "total":7799,
   "tax":100,
   "items":[
      {
         "item":"Line Item #1",
         "description":"red ball"
         "quantity":1,
         "price":7799,
         "um":"EACH",
         "commodityCode":"11119999",
         "total":5799,
         "discount":-2000,
         "productCode":"UPC12345"
      },
      {
         "item":"Line Item #2",
         "description":"green ball"
         "quantity":2,
         "price":1000,
         "um":"EACH",
         "commodityCode":"11119999",
         "total":2000,
         "discount":0,
         "productCode":"UPC12345"
      }
   ]
}

Level 2/3 Data Format Requirements

Field

Length

Brand

Format Restrictions

txns.tax

12

Visa, MC

Numeric in pennies (Also see exceptions in MasterCard MCC exclusions)

txns.order

15

MC

Must not be all spaces (Also see Visa Large Ticket requirements)

txns.discount

12

Visa

Numeric in pennies

txns.shipping

12

Visa

Numeric in pennies

txns.duty

12

Visa

Numeric in pennies

items[].productCode

12

Visa, MC

Text, must not be all spaces or all 0's

items[].item

26

Visa, MC

Text, Must not be all spaces or all 0’s

items[].description

26

Visa, MC

Text, must not be all space or all 0’s

items[].quantity

12

Visa, MC

Numeric, floating-point up to 4 decimals

items[].um

12

Visa, MC

Text, must not be all space or all 0’s

items[].total

12

Visa, MC

Numeric in pennies

items[].price

12

Visa

Numeric, floating-point up to 4 decimals in pennies

items[].discount

12

Visa

Numeric in pennies

items[].commodityCode

12

Visa

Numeric only. Must not be all spaces or all 0’s. Additional details below

Commodity Code Requirements

The Commodity Code must be submitted in numeric only formatting to meet requirements. Payrix recommends utilizing the NIGP codes, and the full code list is available via subscription here.

Attached is a partial list of available 7-digit codes.

nigplist.pdf

Visa Specific Requirements

Visa shows card type..

  1. This data can be located in the Portal by clicking on a transaction from the Payments History page to reveal the Transaction Details window.

  2. The BIN field within will display the card type.

Visa Level 2 Requirements

Click to expand list of Visa Level 2 Data Submission Requirements
  • The transaction must be CPS qualified:

    • The transaction Capture request must be within 1 business day of the original Authorization (i.e. no more than 24 hours between Auth and Capture). Some eligible large ticket payments can be Captured up to 7 business days after Authorization when using a corporate/purchasing cards.

    • Ineligible MCCs (High Risk)
      5962 Direct Marketing – Travel Related Arrangements Services
      5966 Direct Marketing- Outbound Telemarketing Merchant
      5967 Direct Marketing – Inbound Teleservices Merchant

    • These payments cannot be Authorized via a cardholder activated terminal device

    • Transaction MUST include a non-zero tax amount

    • AVS required for CNP transactions (except Corporate Card and Purchasing Card, which are always exempt from AVS)

  • Card Type Qualifications for Level 2

    • Business Card

    • Corporate Card

    • Purchasing Card

  • MCC Qualifications

    • All MCCs are eligible except:
      3000–3999 Airlines/Car Rental Companies/Hotels
      4112 Passenger Railways
      4411 Steamship and Cruise Lines
      4511 Airlines and Air Carriers
      4722 Travel Agencies and Tour Operators
      5812 Eating Places and Restaurants
      5814 Fast Food Restaurants
      7011 Lodging—Hotels, Motels, and Resorts
      7512 Automobile Rental Agency
      7513 Truck & Utility Trailer Rentals

Visa Level 3 Requirements

Click to expand list of Visa Level 3 Data Submission Requirements
  • Level 2 data is not required to achieve level 3 rates

  • The tax amount can be $0.00 as well as long as the tax exempt flag is set

  • If tax amount is sent that is greater than $0.00, it needs to be between 0.01% & 0.30% of the transaction amount.

Card Type Qualifications for Level 3:

  • Corporate Card

  • Purchasing Card

Large Ticket Requirements

For a transaction to qualify as Large Ticket, all Level 3 restrictions must be met. In addition:

  • Customer Code (Invoice #) must be submitted with the transaction

  • Purchasing Card and Non-GSA Corporate Card only

MasterCard Specific Requirements

MasterCard offers card type info in much finer detail.

  1. This data can be located in the Portal by clicking on a transaction from the Payments History page to reveal the Transaction Details window.

  2. By clicking on the Platform IDs tab, an Auth and Retreival number relevant to the transaction.

The first 3 characters of Auth or Capture ID for MasterCard contains the card type detail.

Note: MasterCard interchange terms for Level 2/3 is “Data Rate 2/3” which applies only to corporate/business interchange categories.

MasterCard Level 2 Requirements

Click to expand list of MasterCard Level 2 Data Submission Requirements
  • Data Rate 1/2/3 Requirements

    • Clearing must follow authorization within 3 business days (no more than 2 days between auth and capture)

  • Card Type Qualifications for Data Rate I/2

    • MAC Mastercard Corporate World Elite

    • MAP Mastercard Commercial Payments Account product

    • MAQ Mastercard Prepaid Commercial Payments Account

    • MBD Deferred Debit Mastercard BusinessCard

    • MBS Mastercard Corporate Card (GB)

    • MCB Mastercard BusinessCard

    • MCF Mastercard Electronic Fleet Card

    • MCO Mastercard Corporate

    • MCP Mastercard Corporate Purchasing Card

    • MDB Debit Mastercard BusinessCard

    • MDL Business Debit Other Embossed

    • MEB Mastercard Executive BusinessCard

    • MEF Mastercard Electronic Payment Account

    • MEO Mastercard Corporate Executive Card

    • MGF Mastercard Government Commercial Card

    • MNF Mastercard Public Sector Commercial Card

    • MPK Prepaid Mastercard Government Commercial Card

    • MPW Prepaid Mastercard Corporate Card

    • MWO Mastercard Corporate World

    • MWB World Mastercard for Business

    • MAB World Elite Mastercard for Business

  • MCC Qualifications

    • All MCCs except below
      3000–3299 or 4511 (Airline)
      3351–3500, 7512, 7513, or 7519 (Automobile/Vehicle Rental)
      3501–3999 or 7011 (Hotel/Motel)
      4112 (Passenger Railways)
      5812 (Eating Places, Restaurants)

    • Some MCCs DO NOT require tax amount to be submitted (Data Rate I/2 only)
      4468, 5541, 5542, 5499, 5983 (Fuel)
      4111, 4131,4215, 4784 (Transportation)
      8211, 8220, 8398, 8661 (Non-Profit)
      9211, 9222, 9311, 9399, 9402 (Government)

  • Additional requirements for Shipping/Courier MCCs such as package weight, tracking number, pickup date, etc (not listed). Additional requirements for Fuel MCCs (not listed)

MasterCard Level 3 Requirements

Click to expand list of MasterCard Level 3 Data Submission Requirements
  • Level 2 data is required to achieve level 3 rates (except there are no exclusions for MCC when submitting tax amount (i.e., tax amount is required for all eligible MCCs))

  • If the merchant does send over level 2 data, and the tax amount is greater than $0.00 the tax amount must be a percent between 0.01% & 0.22% of the transaction.

  • The tax amount can be $0.00 as long as the tax exempt flag is sent.

  • A minimum of one valid Level 3 data line-item

  • Card Type Qualifications for Data Rate 3

    • MBS, MEF card types are not eligible for Data Rate 3

Large Ticket Requirements

For a transaction to qualify as Large Ticket, all Level 3 restrictions must be met. In addition:

  • Submission Requirements

    • Clearing must follow authorization within 2 business days (no more than 1 day between auth and capture)

  • Card Type Qualifications for Large Ticket

    • MAP, MAQ, MEF card types are not eligible for Large Ticket

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.