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
{
"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 |
---|---|---|---|
| 12 | Visa, MC | Numeric in pennies (Also see exceptions in MasterCard MCC exclusions) |
| 15 | MC | Must not be all spaces (Also see Visa Large Ticket requirements) |
| 12 | Visa | Numeric in pennies |
| 12 | Visa | Numeric in pennies |
| 12 | Visa | Numeric in pennies |
| 12 | Visa, MC | Text, must not be all spaces or all 0's |
| 26 | Visa, MC | Text, Must not be all spaces or all 0’s |
| 26 | Visa, MC | Text, must not be all space or all 0’s |
| 12 | Visa, MC | Numeric, floating-point up to 4 decimals |
| 12 | Visa, MC | Text, must not be all space or all 0’s |
| 12 | Visa, MC | Numeric in pennies |
| 12 | Visa | Numeric, floating-point up to 4 decimals in pennies |
| 12 | Visa | Numeric in pennies |
| 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.
Visa Specific Requirements
Visa shows card type..
This data can be located in the Portal by clicking on a transaction from the Payments History page to reveal the Transaction Details window.
The BIN field within will display the card type.
.png?inst-v=f177c90a-4045-4ce3-9e9a-0206535a67cd)
Visa Level 2 Requirements
Visa Level 3 Requirements
MasterCard Specific Requirements
MasterCard offers card type info in much finer detail.
This data can be located in the Portal by clicking on a transaction from the Payments History page to reveal the Transaction Details window.
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.
%20(1).png?inst-v=f177c90a-4045-4ce3-9e9a-0206535a67cd)