Versions Compared

Old Version 7

changes.mady.by.user Miles Graves

Saved on

compared with

New Version Current

changes.mady.by.user Miles Graves

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

With credit card transactions, different levels of data submission are critical for businesses engaged in different types of transactions. Referrers and Merchants can receive up to 40-100 basis points of reduced fees on their qualifying business and commercial card transactions.

There are three levels of interchange data submission available:

Level

I

1

Basic transaction data like card number, expiration date, CVV, and transaction amount that is required for standard business-to-consumer (B2C) transactions and provide standard interchange rates.

Level

II

2

More detailed transaction data, like a sales tax and order number, is required for B2B transactions and

provides

can provide lower interchange rates.

Level

III

3

Comprehensive transaction

information

data like line item details and shipping

, is required

for

high-value (large ticket)

B2B transactions

and provides

can qualify for the lowest interchange rates.

Major card brands Visa & MasterCard each have specific requirements that merchants must adhere to to offer them the best interchange rates. American Express and Discover do not accept direct Level II 2 or Level III 3 data submissions for lower interchange rates at this time.

Below is a breakdown of the key data required for Level II and Level III data submission for each card brand.

Info

Note: Each additional level of data submission, Level I to Level II to Level III data, requires all data from the previous level in addition to the new data required.

Example: To submit Level III data, all Level I and Level II data requirements must already be met to qualify for Level III interchange rates.

...

Tip

Tip: While not a requirement, it is recommended to submit the previous level of interchange data when submitting the following level.

Example: When submitting Level 3 data, all Level 1 and Level 2 data requirements are already met to ensure the most visibility for Level 3 interchange rates.

Below is a breakdown of the key data required for Level 2 and Level 3 data submission for each card brand.

...

Level 1 Interchange Data Requirements

All transactions, regardless of card brand, must meet these data requirements to qualify for basic interchange or Level I1:

Merchant & Transaction Information - Basic data provided about the Merchant and Transaction, including:

Merchant Name

The name of the Merchant business selling products or services.

Transaction Date

The date that the transaction took place.

Transaction Amount

The total amount of the transaction charged to the customer.

Customer / Cardholder Information - Essential customer and card data used to pay, including:

Customer Zip Code

The billing zip code on file with the customer’s credit card company.

Customer Billing Address

The full billing address on file with the customer’s credit card company.

Credit Card Number

The 15 (AMEX) or 16-digit credit card number shown on the customer’s card.

Card Expiration Date

The 4-digit, MMYY-format expiration date shown on the customer’s card.

Level II and III Interchange Data Requirements

Each card brand will feature its list of requirements necessary to receive interchange rates by using Level II or Level III data to qualify on its card network. Each major card brand - Visa, MasterCard, American Express, and Discover - has been listed below with individual details to clearly explain their requirements.

Once you are familiar with these requirements, visit <<Submit Level II & III interchange data article>> to learn the different methods available to submit this data.

Tip

Tip: For developers and Portal users, we recommend using Visa’s Level II and Level III requirements as your data submission foundation for Level II and Level II submission for any card brand.

Visa’s stringent standards cover all necessary elements for detailed transaction reporting.

Note

Warning: For all ‘tax’ amount values, ensure the amount always corresponds to your local state or province regulations to ensure tax compliance.

Visa

In addition to the parameter qualifications below, Visa also requires the following conditions to be met from Merchants before they can submit Level II or Level III data for lower interchange rates:

  1. Merchants must process 1 to 6 million Visa transactions per year.

  2. Merchants must process between $20,000 and $1,000,000 in annual e-commerce transactions.

  3. Merchants must submit the following forms to the Visa Verification team:

    1. Annual Attestation of Compliance (AOC)

    2. Annual Self-Assessment Questionnaire (SAQ)

    3. Quarterly Network Scan by an Approved Scan Vendor (ASV2)

Card CVV

The 3 or 4-digit security code shown on the customer’s card.

...

Commodity Codes

The Commodity Code must be submitted in numeric-only formatting to meet requirements. Merchants should utilize the National Institute of Governmental Purchasings' (NIGP) Commodity Codes.

Info

The full code list is available via subscription here.

Info

A partial list of 7-digit NIGP commodity codes is available here:

View file
namenigplist.pdf

...

Level 2 and 3 Interchange Data Requirements

Each card brand will feature its list of requirements necessary to receive interchange rates by using Level 2 or Level 3 data to qualify on its card network. Each major card brand - Visa, MasterCard, American Express, and Discover - has been listed below with individual details to clearly explain their requirements.

Once you are familiar with these requirements, visit Submit Interchange Data with Transactions below to learn the different methods available to submit this data.

Tip

Tip: For developers and Portal users, we recommend using Visa’s Level 2 and Level 3 requirements as your data submission foundation for Level 2 and Level 1 submission for any card brand.

Visa’s stringent standards cover all necessary elements for detailed transaction reporting.

Note

Warning: For all ‘tax’ amount values, ensure the amount always corresponds to your local state or province regulations to ensure tax compliance.

Note: If you choose to optionally submit Level 2 data with Level 3 data, the tax rate must be set between 0.1% & 22% of the transaction amount when the tax amount is greater than $0.00.

Visa

Read more information about Visa requirements below:

Expand
titleVisa - Qualifying Card Types for Interchange Data Submission

The following card types can be used for Level II 2 data submission:

  • Corporate Purchasing

  • Business Credit

  • Enhanced Business Credit

  • Signature Business Credit

In addition to the above, the following card types can be used for Level III 3 data submission:

  • Corporate Credit

  • Purchasing Credit

Note

Commercial Prepaid card type is not eligible.

Expand
titleVisa - Level II Data Requirements
title

Level II 2 data must include all Level I 1 data requirements in addition to the requirements listed below.

Sales Tax and Order Information - Sales tax information for each transaction including:

Sales Tax Indicator

Sales Tax Amount

The total amount of sales tax applied to the transaction.

Note

Warning: The tax amount must be between 0.1% - 22% of the payment total to qualify. This is submitted using either a Sale or a Capture transaction type.

Specify whether sales tax is included in the transaction amount or not.

Order Number

A unique identifier used by the merchant to locate the specific transaction information.

Note: “Order Number” and , “Invoice Number”, and “Customer Code” are interchangeable terms for Level II 2 and Level III 3 data submissions.

Merchant Information - Details about the Merchant selling the product or service items including:

Customer Code

The unique identifier assigned to customers or entities within the Merchant’s records.

Merchant Zip Code

The zip code where the Merchant’s business is located.

Merchant TIN

The tax identification number issued to the Merchant by their governmental tax agency.

Expand

Note

Warning: This field cannot be blank, null, or all zeros and must contain a relevant value.

Visa - Additional Qualification
Expand
titleVisa - Level III Data Requirements
title

Level III 3 data must include all Level II 2 data requirements in addition to the requirements listed below.

Order (Line) Item Details - Must provide detailed information for each item listed in a transaction including:

Item

Name or title of the item.

Description

A detailed description of the product or service sold.

Commodity Code

Standardized We recommend using the standardized numerical 7-digit NIGP commodity code used to classify products for customs.

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

View file
namenigplist.pdf

Product Code

Note

Warning: This field cannot be blank, null, or all zeros or spaces and must contain a relevant value.

Product Code

A unique identifier used by the Merchant business to identify the specific product.

Note

Warning: This field cannot be blank, null, or all zeros or spaces and must contain a relevant value.

Item Price

The price per item unit.

Item Discount

Monetary reductions applied to the product or service price for the line item.

Note: This value can be '0' if there is no applicable item discount.

Quantity

The number of units sold.

Unit of Measure

A standardized unit used to quantify the quantity of the product or service.

Item Total

Total transaction
Info

Examples: each, kilogram, pound, month.

Item Total

Total transaction line item cost, calculated with quantity, unit price, discounts, tax, and shipping.

Discount, Shipping & Duty - Must provide shipping, duty, and tax information (if applicable) including:

Shipping Amount

The cost associated with transporting products from Merchant to customer.

Note: This value can be '0' if there is no applicable shipping amount.

Duty Amount

The monetary value of customs duties or taxes related to product import and export.

Note: This value can be '0' if there is no applicable duty amount.

Order Discount

Monetary reductions applied to the transaction total.

Expand

Note: This value can be '0' if there is no applicable order discount.

Tax

Note: The tax amount can be zero (or the tax field can be omitted entirely). If the Merchant sends a tax amount greater than $0.00, it needs to be between 0.1% & 22% of the transaction amount.

Expand
titleVisa - Additional Qualification Requirements

In addition to the interchange data requirements above, the Visa card network has specific additional requirements to qualify:

  • The transaction must be compliant with the Visa Custom Payment Service (CPS).

  • A ‘capture’ request must follow the ‘authorization’ request:

    • Within 1 business day (no more than 24 hours between auth and capture) or;

    • Within 7 days (for eligible large ticket transactions using corporate/purchasing cards).

  • Transaction must be authorized online and cannot be a cardholder-activated terminal (CAT) location.The transaction must always include a non-zero tax amount

  • Business Card type transactions must always include an Address Verification System (AVS) reference.

Expand
titleVisa - Large Ticket Requirements

Large Ticket transactions refer to transactions with a larger total dollar amount.

Based Your interchange rate may change based on the transaction amount , your interchange rate may change to offer better pricing from Visa’s large ticket program for high-dollar-value transactions.

In addition to the data requirements above, the Visa card network has specific additional requirements to qualify for Large Ticket interchange pricing:

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

  • The transaction amount must meet ticket thresholds: $6,980+

The
Expand
titleVisa - Prohibited Merchant Business Types (MCCs)
Note

Warning: Any of the following Merchant Commercial Code (MCC) types are disqualified from Level

II

2 or Level

III

3 data submission for interchange rate improvements

:

.

Visa

Non-Compliant MCCs

List:
Expand
titleMasterCard - Qualifying Card Types for Interchange Data Submission

The following card types can be used for Level II data submission:

  • Corporate Purchasing

  • Business Credit

  • Enhanced Business Credit

  • Signature Business Credit

In addition to the above, the following card types can be used for Level III data submission:

  • Corporate Credit

  • Purchasing Credit

Note

Commercial Prepaid card type is not eligible.

Note

Warning: The following card types are ineligible for Level III data submission with MasterCard:

  • MBS - Mastercard B2B Product 1

  • MEF - Mastercard Electronic Payment Account

Non-Compliant MCCs

Description of Merchant Business Type

3000–39993000–3299

Airlines/

3501-3999

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

5962

Direct Marketing – Travel Related Arrangements Services (High Risk)

5966

Direct Marketing – Outbound Telemarketing Merchant (High Risk)

5967

Direct Marketing – Inbound Teleservices Merchant (High Risk)

7011

Lodging – Hotels, Motels, and Resorts

7512

Automobile Rental Agency

7513

Truck & Utility Trailer Rentals

7519

MasterCard

In addition to the parameter qualifications below, MasterCard also requires the following conditions to be met from Merchants before they can submit Level II or Level III data for lower interchange rates:

  1. Merchants must process a combined total of 1 to 6 million MasterCard & Maestro transactions per year.

  2. Merchants must process between $20,000 and $1,000,000 in annual e-commerce transactions.

  3. Merchants must submit the following forms to the MasterCard:

    1. Annual Attestation of Compliance (AOC)

    2. Annual Self-Assessment Questionnaire (SAQ)

    3. Quarterly Network Scan by an Approved Scan Vendor (ASV2)

Read more information about MasterCard requirements below:

Motor Home and Recreational Vehicle Rentals

...

MasterCard

Read more information about MasterCard requirements below:

Expand
titleMasterCard - Qualifying Card Types for Interchange Data Submission

The following card types can be used for Level 2 data submission:

  • Corporate Purchasing

  • Business Credit

  • Enhanced Business Credit

  • Signature Business Credit

Note: MasterCard uses the term “Data Rate 2 and 3” to refer to Level 2 and Level 3 interchange data when referring to corporate/business purchases and cards.

In addition to the above, the following card types can be used for Level 3 data submission:

  • Corporate Credit

  • Purchasing Credit

Note

Commercial Prepaid card type is not eligible.

Note

Warning: The following card types are ineligible for Level 3 data submission with MasterCard:

  • MBS - Mastercard B2B Product 1

  • MEF - Mastercard Electronic Payment Account

Expand
titleMasterCard - Level II Data Requirements

Level 2 data must include all Level 1 data requirements in addition to the requirements listed below.

Sales Tax Information - Sales tax information for each transaction including:

Sales Tax Amount

The total amount of sales tax applied to the transaction.

Note

Warning: The tax amount must be between 0.1% - 30% of the payment total to qualify. This is submitted using either a Sale or a Capture transaction type.

Order Number

A unique identifier used by the merchant to locate the specific transaction information.

Note: “Order Number”, “Invoice Number”, and “Customer Code” are interchangeable terms for Level 2 and Level 3 data submissions.

Note

Warning: This field cannot be blank, null, or all zeros and must contain a relevant value.

Order Number
Expand
titleMasterCard - Level II III Data Requirements

Level II 3 data must include all Level I 2 data requirements in addition to the requirements listed below.

Sales Tax Information - Sales tax Item Details - Must provide detailed information for each item listed in a transaction including:

Sales Tax Amount

The total amount of sales tax applied to the transaction.

Note

Warning: The tax amount must be between 0.1% - 30% of the payment total to qualify. This is submitted using either a Sale or a Capture transaction type.

Sales Tax Indicator

Specify whether sales tax is included in the transaction amount or not.

Item

Name or title of the item.

Description

A detailed description of the product or service sold.

Note

Warning: This field cannot be blank, null, or all zeros or spaces and must contain a relevant value.

Line Item Total

Total transaction line item cost, calculated with quantity, unit price, discounts, tax, and shipping.

Product Code

A unique identifier used by the

merchant

Merchant business to

locate

identify the specific

transaction information

product.

Note: “Order Number” and “Invoice Number” are interchangeable terms for Level II and Level III data submissions.

Merchant Information - Details about the Merchant selling the product or service items including:

Customer Code

The unique identifier assigned to customers or entities within the Merchant’s records.

Merchant TIN

The tax identification number issued to the Merchant by their governmental tax agency.

Expand
titleMasterCard - Level III Data Requirements

Level III data must include all Level II data requirements in addition to the requirements listed below.

Line Item Details - Must provide detailed information for each item listed in a transaction including:

Discount Amount

Monetary reductions applied to the transaction total.

Discount Per Line Item

Monetary reductions applied to the product or service price for the line item.

Item Description

A detailed description of the product or service sold.

Line Item Total

Total transaction line item cost, calculated with quantity, unit price, discounts, tax, and shipping.

Product Code

A unique identifier used by the Merchant business to identify the specific product.

Quantity

The number of units sold.

Unit of Measure

A standardized unit used to quantify the quantity of the product or service.

Note

Warning: The following card types are ineligible for Level III interchange with MasterCard:

  • MBS - Mastercard B2B Product 1

  • MEF - Mastercard Electronic Payment Account

Expand
titleMasterCard - Additional Qualification Requirements

In addition to the interchange data requirements above, the MasterCard card network has specific additional requirements to qualify:

  • Clearing must follow an authorization request within 3 business days (no more than 2 days between Authorization and Capture).

Expand
titleMasterCard - Large Ticket Requirements

Large Ticket transactions refer to transactions with a larger total dollar amount. Your interchange rate may change based on the transaction amount to offer better pricing from MasterCard’s large ticket program for high-dollar-value transactions.

In addition to the data requirements above, the MasterCard network has specific additional requirements to qualify for Large Ticket interchange pricing:

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

Note

Warning: The following card types are ineligible for MasterCard’s large ticket program:

  • MAP - Mastercard Commercial Payments Account

  • MAQ - Mastercard Prepaid Commercial Payments Account

  • MEF - Mastercard Electronic Payment Account

Expand
titleMasterCard - Prohibited Merchant Business Types (MCCs)

The following Merchant Commercial Code (MCC) types are disqualified from Level II or Level III data submission for interchange rate improvements:

MasterCard Non-Compliant MCCs List:

Non-Compliant MCCs

Description of Merchant Business Type

3000–3999

Airlines/Car Rental Companies/Hotels

4112

Note

Warning: This field cannot be blank, null, or all zeros or spaces and must contain a relevant value.

Quantity

The number of units sold.

Unit of Measure

A standardized unit used to quantify the quantity of the product or service.

Note: When submitting a Level 3 transaction, the tax amount must be a percent between 0.1% & 30% of the transaction; it cannot be zero unless tax-exempt status is enabled by the Facilitator.

Note

Warning: The following card types are ineligible for Level 3 interchange with MasterCard:

  • MBS - Mastercard B2B Product 1

  • MEF - Mastercard Electronic Payment Account

Expand
titleMasterCard - Additional Qualification Requirements

In addition to the interchange data requirements above, the MasterCard card network has specific additional requirements to qualify:

  • Clearing must follow an authorization request within 3 business days (no more than 2 days between Authorization and Capture).

Expand
titleMasterCard - Large Ticket Requirements

Large Ticket transactions refer to transactions with a larger total dollar amount. Your interchange rate may change based on the transaction amount to offer better pricing from MasterCard’s large ticket program for high-dollar-value transactions.

In addition to the data requirements above, the MasterCard network has specific additional requirements to qualify for Large Ticket interchange pricing:

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

  • The transaction amount must meet ticket thresholds: $7,255+

Note

Warning: The following card types are ineligible for MasterCard’s large ticket program:

  • MAP - Mastercard Commercial Payments Account

  • MAQ - Mastercard Prepaid Commercial Payments Account

  • MEF - Mastercard Electronic Payment Account

Expand
titleMasterCard - Prohibited Merchant Business Types (MCCs)
Note

Warning: Any of the following Merchant Commercial Code (MCC) types are disqualified from Level 2 or Level 3 data submission for interchange rate improvements.

MasterCard Non-Compliant MCCs List:

Non-Profit and Governmental entities that qualify for tax-exempt status can apply this setting to their platform entity. This provides the proper mapping for Level II data submission when tax amounts are set to 0%.

Tip

Warning: To enable the /parameters endpoint and autoTaxExemptEnabled parameter for your Group(s), contact your Payrix representative.

To apply tax-exempt status to non-profit entity groups using the /parameters Payrix API endpoint, send the following request:

Code Block
POST https://test-api.payrix.com/parameters
Code Block
languagejson
{
  "login": "{{yourLoginID}}",
  "org":"{{merchantsOrg/GroupID}}",
  "autoTaxExemptEnabled":"1",
  "inactive":"0",
  "frozen":"0",
  }
Warning

Error: If you do not first contact Payrix to enable access to the /parameters endpoint, you will receive the error below:

Code Block
languagejson
{
    "errors": [
        {
            "code": 23,
            "severity": 2,
            "msg": "Invalid request for this type of user authentication"
        }
    ]
}

Your successful response should look like the following:

Code Block
languagejson
{
    
    "id": "t1_par_1abc2d34ef5g6h7ij89kl01",
    "created": "2023-10-05T13:00:33.442Z",
    "modified": "2023-10-05T13:00:33.442Z",
    "creator": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "modifier": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "login": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "org": "t1_org_1abc2d34ef5g6h7ij89kl01",
    "division": "t1_div_1abc2d34ef5g6h7ij89kl01",
    "partition": "t1__1abc2d34ef5g6h7ij89kl01",
    "autoTaxExemptEnabled": "1",
    "inactive": "0",
    "frozen": "0",
    "minTxnTotal": "null",
    "maxTxnTotal": "null",
    "maxTxnDailyTotal": "null",
    "maxTxnDailyNum": "null",
    "maxTxnMonthlyTotal": "null",
    "maxTxnMonthlyNum": "null",
    "maxSubscriptionFailures": "null",
    "minPayoutCreditTotal": "0001",
    "maxPayoutCreditTotal": "null",
    "minPayoutDebitTotal": "-0001",
    "maxPayoutDebitTotal": "null",
    "minAvailableFunds": "null",
    "minStatementDebitPayoutDelay": "5",
    "minFundsPayoutTotal": "500",
    "minPayoutDelay": "3",
    "minFirstPayoutDelay": "3",
    "payoutDelayIncludeOffDays": "0",
    "payoutIncludePending": "0",
    "amexEnabled": "0",
    "optBlueEnabled": "0",
    "discoverEnabled": "0",
    "discoverAcquiredEnabled": "0",
    "mc3dsEnabled": "0",
    "visa3dsEnabled": "0",
    "amex3dsEnabled": "0",
    "discover3dsEnabled": "0",
    "eCheckEnabled": "0",
    "fundingEnabled": "0",
    "debtRepaymentEnabled": "0",
    "verifyDisabled": "0",
    "verifyForBoardingNotRequired": "0",
    "verifyForPayoutNotRequired": "0",
    "refundReleasesReserve": "0",
    "vendorFeesEnabled": "0",
    "vendorFeesExternal": "0",
    "visaMisuseSettlement": "10",
    "visaMisuseTravelAutoSettlement": "20",
    "visaMisuseCardPresentReversal": "24",
    "visaMisuseCardNotPresentReversal": "168",
    "mcMisuseSettlement": "120",
    "minEcheckCaptureDelay": "0",
    "minDebitProcessingDelay": "5",
    "minBoardingOwnership": "0",
    "boardingExemptionsDisabled": "0",
    "mcMisuseCardPresentReversal": "24",
    "mcMisuseCardNotPresentReversal": "72",
    "mcMisuseTravelAutoReversal": "480",
    "boardingDisabled": "0",
    "autoReboardDays": "60",
    "surchargeEnabled": "0",
    "mcInstantPayoutsEnabled": "0",
    "visaInstantPayoutsEnabled": "0",
    "mcInstantPayoutMin": "0",
    "mcInstantPayoutMax": "7500000",
    "visaInstantPayoutMin": "0",
    "visaInstantPayoutMax": "5000000",
    "sameDayPayoutsEnabled": "0",
    "applePayEnabled": "0",
    "googlePayEnabled": "0",
    "sameDayPayoutsDailyMax": "null",
    "minSameDayPayoutCreditTotal": "null",
    "maxSameDayPayoutCreditTotal": "null",
    "minSameDayPayoutDebitTotal": "null",
    "maxSameDayPayoutDebitTotal": "null",
    "accountUpdaterEnabled": "0",
    "updateAllTokensEnabled": "0",
    "accountUpdaterFrequency": "30",
    "minDebitedAvailableFunds": "0",
    "getParametersEnabled": "0",
    "payoutCutoffTime": "null",
    "declineNotificationEmail": "0",
    "decisionMicroserviceEnabled": "0",
    "holdMessagesDisabled": "0",
    "txnDecisionMicroserviceEnabled": "0",
    "omniTokenEnabled": "0",
    "passTokenEnabled": "0",
    "debitGracePeriod": "null",
    "negativeBalanceLimit": "null",
    "negativeBalanceEmail": "0",
    "positiveBalanceEmail": "0"
}

Note: All other non-applicable response parameters above are set with their default values.

Visit our API Documentation to read more about the other available response fields' descriptions.

See the descriptions below for the applicable response parameters.

...

Parameter

...

Description

...

Notes

...

id

...

The Org parameter configurations ID.

...

Recall this ID if you want to enable, change, or disable any individual org parameter.

...

created

...

The date and time at which this resource was created.

...

modified

...

The date and time at which this resource was modified.

...

creator

...

The identifier of the Login that created this resource.

...

modifier

...

The identifier of the Login that last modified this resource.

...

login

...

The Login that owns this resource.

...

org

...

The identifier of the Org resource that this Parameter resource is associated with.

...

autoTaxExemptEnabled

...

Whether to assume a transaction is tax-exempt if no tax is set for Level II processing.

...

Valid Values:

  • 0 - Disabled

  • 1 - Enabled

...

titleSubmit Level III data using the Payrix API.

To submit Level III transaction data using the /txns Payrix API endpoint, send the following request:

Code Block
POST https://test-api.payrix.com/txns
Code Block
languagejson
{
   "merchant":"{yourMerchantID}",
   "payment":{
      "number":"{customerCardNumber}",
      "cvv":"{customerCardCVV}"
   }
   "expiration":"MMYY",
   "type":2,
   "order":"INVOICE#1",
   "total":7799,
   "tax":100,
   "items":[
      {
         "item":"Line Item #1",
         "description":"Line Item Description"
         "quantity":1,
         "price":7799,
         "um":"EACH",
         "commodityCode":"1111999",
         "total":5799,
         "discount":-2000,
         "productCode":"UPC12345"
      },
   ]
}

Note: Descriptions for Level II data shown here are available in the Submit Level II data using the Payrix API section above.

...

Required Parameters

...

Type

...

Description

...

Valid Values / Format

...

items

...

array of objects

...

The item or list of items associated with the transaction/order.

...

item

...

string

...

The line item name.

...

description

...

string

...

The line item description.

...

Max length: 500 characters

...

quantity

...

integer

...

The total number of units for the line item.

...

price

...

number

...

The individual line item price.

...

um

...

string

...

The line item units of measure.

Example: “pounds”, “days”, “hours”.

...

Max length: 100 characters

...

commodityCode

...

string

...

The commodity code for this Item.

...

Max length:12 characters

...

total

...

integer

...

The total price for the line item.

...

This field is specified as an integer in cents

...

discount

...

integer

...

The discount for the line item.

...

This field is specified as an integer in cents.

...

productCode

...

string

...

The product code for this Item such as UPC, catalog number, or inventory number.

PayFields

PayFields is a unique offering that seamlessly integrates a payment gateway into your existing HTML website package and eliminates PCI Compliance risk. Submitting Level II

Step 1: Under your <script> tag containing PayFields.fields add the following to add new Tax and Order fields to the PayFields

Expand
titleSubmit Level II data using PayFields.
Code Block
<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"}
    {type: "tax", element: "#tax"}
    {type: "order", element: "#order"}
  ];
</script>

Step 2: Under a new <script> tag, add the API Key, Merchant ID, and Transaction Amount:

Code Block
languagehtml
<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = {Transaction Amount};
  <!---- continued by Step 3 ---->

Step 3: Under the same <script> tag as Step 2, add the Order Field, Tax Field, and Billing Address:

Code Block
languagejs
<!---- preceeded by Step 2 ---->
  PayFields.config.order = {order number};
  PayFields.config.tax = {tax number};
  PayFields.config.billingAddress = {
    address: '123 Madison Street',
    city: 'New York',
    state: 'NY',
    zip: '12345',
    email: '',
    phone: '5555555555',
    address2: 'Suite 555',
    company: 'Essential Co',
    country: 'USA'
  };
  PayFields.config.invoiceResult = {Invoice Object}
</script>

Result: Example HTML File

Code Block
languagehtml
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="text/javascript" src="https://test-api.payrix.com/payFieldsScript"></script>
  <title>PayFields Test</title>
</head>
<body>
<input type="button" id="submit" value="Pay"></input>
  <!-- Button needed for PayFrame -->
<script>
    PayFields.button = {element: "#submit", value: "Pay"};
</script>
<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"},
    {type: "tax", element: "#tax"},
    {type: "order", element: "#order"},
  ];
</script>
<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = 500;
  PayFields.config.order = {orderNumber};
  PayFields.config.tax = {taxNumber};
  PayFields.config.billingAddress = {
    address: '123 Madison Street',
    city: 'New York',
    state: 'NY',
    zip: '12345',
    email: '',
    phone: '5555555555',
    address2: 'Suite 555',
    company: 'Essential Co',
    country: 'USA'
  };
  PayFields.config.invoiceResult = {invoiceObject}
</script>
</body>
</html>
Expand
titleSubmit Level III data using PayFields.

Step 1: Complete Steps 1-3 above.

Step 2: Under your <script> tag containing PayFields.fields add the following to include Discount, Shipping, Duty, and Item [details] Objects fields in your PayField:

Code Block
languagehtml
<script>
  PayFields.fields = [
    {type: "dicount", element: "#dicount"},
    {type: "shipping", element: "#shipping"},
    {type: "duty", element: "#duty"},
    {type: "items", element: "#items"}    
  ];
</script>

Step 3: Under your <script> tag containing PayFields.config add the following:

Code Block
<script>
  PayFields.config.dicount = {discount number};
  PayFields.config.shipping = {shipping number};
  PayFields.config.duty = {duty number};
  PayFields.config.items = {items Object}
</script>

Result: Example HTML File

Code Block
languagehtml
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <script type="text/javascript" src="https://test-api.payrix.com/payFieldsScript"></script> <title>PayFields Test</title> </head> <body> <input type="button" id="submit" value="Pay"></input> <!-- Button needed for PayFrame --> <script> PayFields.button = {element: "#submit", value: "Pay"}; </script> <script> PayFields.fields = [ {type: "number", element: "#number"}, {type: "cvv", element: "#cvv"}, {type: "name", element: "#name"}, {type: "address", element: "#address"}, {type: "expiration", element: "#expiration"}, {type: "tax", element: "#tax"}, {type: "order", element: "#order"}, {type: "dicount", element: "#dicount"}, {type: "shipping", element: "#shipping"}, {type: "duty", element: "#duty"}, {type: "items", element: "#items"} ]; </script> <script> PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p"; PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45"; PayFields.config.amount = 500; PayFields.config.order = {orderNumber}; PayFields.config.tax = {taxRatePercent}; PayFields.config.dicount = {discountNumber}; PayFields.config.shipping = {shippingNumber}; PayFields.config.duty = {duty number}; PayFields.config.items = {items Object}; PayFields.config.billingAddress = { address: '123 Madison Street', city: 'New York', state: 'NY', zip: '12345', email: '', phone: '5555555555', address2: 'Suite 555', company: 'Essential Co', country: 'USA' }; PayFields.config.invoiceResult = {invoiceObject} </script> </body> </html>

Non-Compliant MCCs

Description of Merchant Business Type

3000–3299

Airlines

3501-3999

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

5962

Direct Marketing – Travel Related Arrangements Services (High Risk)

5966

Direct Marketing – Outbound Telemarketing Merchant (High Risk)

5967

Direct Marketing – Inbound Teleservices Merchant (High Risk)

7011

Lodging – Hotels, Motels, and Resorts

7512

Automobile Rental Agency

7513

Truck & Utility Trailer Rentals

American Express

Merchants processing American Express transactions are required to obtain pre-approval before initiating Level II data processing. Level II data parameters from Visa or MasterCard would apply here.

To receive approval, Merchants must submit a “Level 2 Merchant’s Validation Documentation” which includes summaries from Quarterly Network Scan and a completed PCI Self Assessment Questionaire. Once granted, American Express accepts both Level I and Level II data, offering Level II interchange rates.

Visit the American Express US Data Security site for more information.

Warning

Unavailable: American Express does not offer discounts or changes in interchange rates for Level III data submissions

Discover

Warning

Unavailable: American Express does not offer any discounts or changes in interchange rates for Level II or Level III data submissions.

Submit Interchange Data with Transactions

To take advantage of lower interchange rates, this Level II and Level III data must be submitted alongside your transaction. This ensures the customer’s card brand network can receive and assess the data to determine which interchange rate the transaction will receive.

Info

Before you begin, we recommend checking each card’s eligibility for Level II and Level III processing as American Express and Discover don’t offer direct data submission options for Level II or III to qualify for lower interchange rates. A simple query shown below will quickly identify the card type:

GET https://test-api.payrix.com/bins

The response will display the method (card brand), type (debit, credit, or both), and card category (personal, corporate card, etc.), which will allow you to know before submitting the additional data if the card brand network supports lower interchange rates or Level II or Level III data submissions.

There are multiple methods to submit Level II or Level III data, read through the basic methods below to find the best workflow for your business:

Portal

The Portal offers a very simple way to manually enter and submit Level II and Level III values with payment transactions. Read the steps below to learn more:

Expand
titleSubmit Level II data using the Portal.

To submit Level II transaction data using the Create Payments page:

  • Step 1: Navigate to the Create Payment page under Payments

  • Step 2: Enter all applicable data. Then, under Customer Details, check “Submit this transaction as LEVEL 2 PROCESSING” to reveal Level II fields.

  • Step 3: Enter the TAX and ORDER NUMBER values.

    • Note: If the entity is tax-exempt, you may enter '0'. See the steps below to enable tax-exempt status.

    • Note: If you are not a tax-exempt entity, you must adhere to Visa, Mastercard, and local government sales tax rates and regulations to receive lower Level II interchange rates.

  • Step 4: (Optional) Follow the steps below to also include Level III data.

Click Process Payment to complete the submission.

Expand
titleEnable Tax Exempt Status using the Portal

Non-Profit and Governmental entities that qualify for a tax-exempt status can apply this setting to their platform entity. This provides the proper mapping for Level II data submission when tax amounts are set to 0%.

Tip

Warning: To display the Parameters tab and Auto Tax Exempt Enabled parameter for your Group(s), contact your Payrix representative to enable visibility.

To apply tax-exempt status to non-profit entity groups from the Groups page:

  • Step 1: Navigate to the Groups page under the Management section.

  • Step 2: Click on the desired group (or Add a new Group if needed) & enter the Group Profile page.

  • Step 3: Click on the Parameters tab, then click the ADD PARAMETERS button.

  • Step 4: Click the edit icon in the upper-right corner, then check “Auto Tax Exempt Enabled” and confirm.

  • Step 5: Return to the Group Profile page, then click the ADD MEMBERS button to Add the Merchant as a Member.

Click Save to complete the Merchant enrollment in the Tax Exempt Group.

Expand
titleSubmit Level III data using the Portal.

To submit Level III transaction data using the Create Payments page:

  • Step 1: Complete steps 1-3 above from the Level II submission step above.

  • Step 2: Check “Submit this transaction as LEVEL 3 PROCESSING (All fields must be completed)” to reveal Level III fields.

  • Step 3: Enter the SHIPPING AMOUNT, DUTY AMOUNT & ORDER DISCOUNT value.

  • Step 4: Under Order Items, enter the DESCRIPTION, COMMODITY CODE, PRODUCT CODE, ITEM PRICE, ITEM DISCOUNT, QUANTITY, UNIT OF MEASURE, and ITEM TOTAL for each item.

  • Step 5: (Optional) Add additional Order Items as needed by clicking Add Item at the bottom of each new item form.

Info

Note: Each additional item must have the all fields above for Level 3 Transaction Processing

Click Process Payment to complete the submission.

API

The Payrix API provides a straightforward method of submitting Level II and Level III data values alongside transactions. Read the information below to learn more.

...

titleSubmit Level II data using the Payrix API.

To submit Level II transaction data using the /txns Payrix API endpoint, send the following request:

Code Block
POST https://test-api.payrix.com/txns
Code Block
languagejson
{
   "merchant":"{yourMerchantID}",
   "payment":{
      "number":"{customerCardNumber}",
      "cvv":"{customerCardCVV}"
   }
   "expiration":"MMYY",
   "type":2,
   "order":"INVOICE#1",
   "total":7799,
   "tax":100,
}
Note

Warning: Tax rate must be set according to status and regulation:

  • If you are a tax-exempt entity, you may enter 0 in the tax field. See the steps below to enable tax-exempt status.

  • If you are not a tax-exempt entity, you must adhere to Visa, Mastercard, and local government sales tax rates and regulations to receive lower Level II interchange rates.

...

Required Parameters

...

Type

...

Description

...

Valid Values / Format

...

merchant

...

string

...

The identifier of the Merchant associated with this Transaction.

...

payment

...

object

...

The payment method associated with this Transaction, including the card details.

...

number

...

number

...

For credit payment method, the card number of the credit card associated with this Transaction.
For the eCheck payment method, the bank account number is associated with this Transaction.

...

cvv

...

integer

...

The Card Verification Value (CVV) number of the credit card associated with this Transaction.

...

This field is expressed as a 3-digit integer.

...

expiration

...

number

...

The expiration date of the credit card associated with this Transaction.

...

This field is stored as a text string in 'MMYY' format, where 'MM' is the number of a month and 'YY' is the last two digits of a year. For example, '0623' for June 2023.

...

type

...

integer

...

The type of Transaction.

...

1 - Credit Card Only: Sale Transaction. Processes a sale and charges the customer.

2 - Credit Card Only: Auth Transaction. Authorizes and holds the requested total on the credit card.

3 - Credit Card Only: Capture Transaction. Finalizes a prior Auth Transaction and charges the customer.

4 - Credit Card Only: Reverse Authorization. Reverses a prior Auth or Sale Transaction and releases the credit hold.

5 - Credit Card Only: Refund Transaction. Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund).

7 - eCheck Only: eCheck Sale Transaction. Sale Transaction for eCheck payment.

8 - eCheck Only: eCheck Refund Transaction. Refund Transaction for prior eCheck Sale Transaction.

11 - eCheck Only: eCheck Redeposit Transaction. Attempt to redeposit a prior failed eCheck Sale Transaction.

12 - eCheck Only: eCheck Account Verification Transaction. Attempt to verify eCheck payment details.

...

total

...

number

...

The total amount of this Transaction.

...

This field is specified as an integer in cents.

...

tax

...

integer

...

The total sum of this Transaction’s tax amount.

...

This field is specified as an integer in cents.

...

titleEnable Tax Exempt Status using the Payrix API

7519

Motor Home and Recreational Vehicle Rentals

...

American Express & Discover

There is no additional work or line item data submission required by American Express or Discover.

Both card brands provide lower interchange rates on their respective networks, calculated and adjusted based exclusively on the cardholder’s card type (e.g. business card, corporate card, etc.).