Payments / Accept payments / Submit additional transaction data

Submit additional transaction data Early access

Last updated: 18th July 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 and consumer 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:

MCC	Description	Excluded 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 data can be submitted in either the payment or the capture request.

If additional data is submitted in both requests, the data provided in the payment request is ignored and only the data provided in the capture request is sent to the scheme.

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

Field	Description	Level 2	Level 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

{
  "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.

{
  "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.

Field	Description
`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

{
  "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,
    }
  ]
}