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.

Note

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.
checkcheck

processing.order_id

string

The invoice number.

Up to 15 characters.
checkcheck

processing.tax_amount

number

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

checkcheck

item.commodity_code

string

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

Up to 12 characters.
errorcheck

item.discount_amount

number

The discount applied to each invoice line item.

errorcheck

item.name

string

The description of the item purchased.

Up to 26 characters.
errorcheck

item.quantity

number

The number of units purchased.

Value greater than 0.
errorcheck

item.reference

string

The merchant product identifier.

Up to 12 characters.
errorcheck

item.tax_amount

number

The total amount of sales tax or value-added tax (VAT) for the line item.

errorcheck

item.total_amount

number

The total amount for the line item.

errorcheck

item.unit_of_measure

string

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

Up to 12 characters.
errorcheck

item.unit_price

number

The unit cost of the item purchased.

errorcheck

processing.discount_amount

number

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

errorcheck

processing.duty_amount

number

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

errorcheck

processing.shipping_amount

number

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

errorcheck

processing.shipping_tax_amount

number

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

errorcheck

shipping.address.country

string

The destination country code. Optional field.

Up to 2 characters.
errorcheck

shipping.address.zip

string

The destination postal or zip code. Optional field.

Up to 10 characters.
errorcheck

shipping.from_address_zip

string

The origin postal or zip code. Optional field.

Up to 10 characters.
errorcheck

Request example - Level 2

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

Request example - Level 3

Note

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

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

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.

Note

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

Request example

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

On this page

Eligibility
Submit Level 2 or Level 3 data
Visa and Mastercard data fields
American Express data fields