Skip to content

Submit Level 2 or Level 3 data Beta

Last updated: September 28, 2022

Card processing transactions are categorized into different levels, depending on how much information is captured from the cardholder for the transaction.

By providing Level 2 or Level 3 data with your transactions, you may be able to qualify for reduced interchange rates. Cardholders also benefit from the additional data, as they receive more detailed transaction information in their card statements.

Eligibility

Only taxable US domestic transactions qualify for Level 2 or Level 3 categorization. However, you can submit Level 2 or Level 3 data with all of your payments, as the additional data is automatically removed from any ineligible transactions before being forwarded to the scheme.

Each card scheme has their own set of requirements for a transaction to qualify for Level 2 or Level 3 categorization:

  • For Visa, the total tax amount must be between 0.1% and 22%. Business card transactions are only eligible for Level 2 categorization, while purchasing and corporate card transactions are eligible for Level 2 or Level 3 categorization.
  • For Mastercard, the total tax amount must be between 0.1% and 30%. Only commercial card transactions are eligible for Level 2 or Level 3 categorization.
  • For American Express, there are no tax requirements or card type restrictions. However, American Express transactions are only eligible for Level 2 categorization.

In addition to the restrictions, each card scheme excludes specific merchant category codes (MCC) from Level 2/Level 3 eligibility:

MCCDescriptionExcluded from

3000–3350, 4511

Airlines

Visa, Mastercard

3351–3500, 7512, 7513

Automobile/vehicle rental

Visa, Mastercard

3501–3999, 7011

Hotel/motel

Visa, Mastercard

4112

Passenger railways

Visa, Mastercard

4411

Cruise lines

Visa,

4722

Travel agencies and operators

Visa

5812

Eating places and restaurants

Visa, Mastercard

5814

Fast food restaurants

Visa

7519

Motor home and recreational vehicle rental

Mastercard

Submit Level 2 or Level 3 data

Level 2 and Level 3 fields can be submitted in either the payment or the capture request. Values submitted in the capture request will override values submitted in the payment request on a field-by-field basis.

For partial captures, the Level 2 or Level 3 data must be submitted in the capture request. If the data is sent in the payment request and a partial capture follows without the additional data, no data will be submitted to the card scheme.

If you submit Level 2 or Level 3 data in a payment or capture request for a transaction that is not eligible for Level 2 or Level 3 categorization, the additional data is automatically dropped from the request when forwarded to the scheme.

Visa and Mastercard data fields

FieldDescriptionLevel 2Level 3

customer.tax_number

string

The customer's value-added tax (VAT) registration number. Optional field.

Up to 13 characters.

processing.order_id

string

The invoice number.

Up to 15 characters.

processing.tax_amount

number

The total amount of sales tax on the total purchase amount.

item.commodity_code

string

The code identifying a commodity for value-added tax (VAT) purposes.

Up to 12 characters.

item.discount_amount

number

The discount applied to each invoice line item.

item.name

string

The description of the item purchased.

Up to 26 characters.

item.quantity

number

The number of units purchased.

Value greater than 0.

item.reference

string

The merchant product identifier.

Up to 12 characters.

item.tax_amount

number

The total amount of sales tax or value-added tax (VAT) on the total purchase amount. Tax should be included in the total purchase.

item.total_amount

number

The total amount for the line item.

item.unit_of_measure

string

The unit of measure code used for the item in the transaction.

Up to 12 characters.

item.unit_price

number

The unit cost of the item purchased.

processing.discount_amount

number

The discount amount applied to the transaction by the merchant. Optional field.

processing.duty_amount

number

The total charges for any import or export duty included in the transaction.

processing.shipping_amount

number

The total charges for freight, shipping or handling included in the transaction.

processing.shipping_tax_amount

number

The total amount of tax for the freight, shipping or handling charges. Optional field.

shipping.address.country

string

The destination country code. Optional field.

Up to 2 characters.

shipping.address.zip

string

The destination postal or zip code. Optional field.

Up to 10 characters.

shipping.from_address_zip

string

The origin postal or zip code. Optional field.

Up to 10 characters.

Request example - Level 2

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    {
    "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": "12",
    "expiry_year": "2025",
    "cvv": "100"
    },
    "amount": 1500,
    "currency": "USD",
    "customer":{
    "tax_number": "000123456"
    },
    "processing": {
    "order_id": "01234",
    "tax_amount": 30
    }
    }

    Request example - Level 3

    You can send a maximum of 50 item objects in a Level 3 Visa or Mastercard request.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      {
      "source": {
      "type": "card",
      "number": "4242424242424242",
      "expiry_month": "12",
      "expiry_year": "2025",
      "cvv": "100"
      },
      "amount": 1500,
      "currency": "USD",
      "customer": {
      "tax_number":"000123456"
      },
      "processing": {
      "order_id": "01234",
      "tax_amount": 30,
      "discount_amount":0,
      "duty_amount":0,
      "shipping_amount": 200,
      "shipping_tax_amount":0
      },
      "shipping": {
      "address": {
      "zip": "94111",
      "country": "US",
      "from_address_zip": "10014"
      }
      },
      "items": [
      {
      "name": "Paint",
      "quantity": 1,
      "unit_price": 1270,
      "reference": "Paint123",
      "commodity_code": "123",
      "unit_of_measure": "Litres",
      "total_amount": 1270,
      "tax_amount": 30,
      "discount_amount": 0
      }
      ]
      }

      American Express data fields

      American Express only supports Level 2 data.

      FieldDescription

      card.name

      string

      The customer's name. Optional field.

      item.name

      string

      The description of the item purchased.

      Up to 26 characters.

      item.quantity

      number

      The number of units purchased.

      item.unit_price

      number

      The unit cost of the item purchased.

      processing.order_id

      string

      The invoice number.

      Up to 15 characters.

      processing.tax_amount

      number

      The total amount of sales tax on the total purchase amount.

      shipping.address.zip

      string

      The destination postal or zip code. Optional field.

      Up to 10 characters.

      You can send a maximum of 4 item objects in an American Express request.

      Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        {
        "source": {
        "type": "card",
        "number": "3737373737373737",
        "expiry_month": "12",
        "expiry_year": "2025",
        "cvv": "100"
        },
        "amount": 1500,
        "currency": "USD",
        "processing": {
        "order_id": "01234",
        "Tax_amount": 30
        },
        "shipping": {
        "address": {
        "zip": "94111"
        }
        },
        "items": [
        {
        "name": "Paint",
        "quantity": 1,
        "unit_price": 1270
        }
        ]
        }