Menu

Level 2/3 data

There are a number of benefits to supplying Level 2 or Level 3 data:

  • Lower interchange fees
  • Provides commercial customers greater insight into their spending

APIs

You can supply Level 2 and Level 3 data through the following APIs:

Qualification criteria

MasterCard

  • Transaction must be taxable
  • Tax must be between 0.1% and 30% of the transaction amount
  • For level 3 the transaction must use a corporate, business or purchasing card
  • For level 3 at least one line item must be included

Visa

  • Transaction must be taxable
  • Tax must be between 0.1% and 22% of the transaction amount
  • For level 3 the transaction must use a corporate or purchasing card

Data requirements

The table below defines the Level 2 and 3 data requirements for Visa and MasterCard. Level 2 and 3 data is supplied in <purchase> which is a child of <branchSpecificExtension>.

  • ✔ = required
  • - = optional
ElementLevel 2Level 3TypeSizeDescription
<purchase>
<invoiceReferenceNumber>--PCDATA1-15Your invoice number.
<customerReference>✔✔PCDATA1-17Customer reference for the purchase.
<cardAcceptorTaxId>✔✔PCDATA1-209 digits for US domiciled merchants.
<salesTax>✔✔<amount>value, exponent and currencyCodeFor non-taxable transactions set <salesTax> to 0 and <taxExempt> to true.
<discountAmount>-✔<amount>value, exponent and currencyCodeThe amount of the discount for the order.
<shippingAmount>-✔<amount>value, exponent and currencyCodeThe shipping cost for the order.
<dutyAmount>-✔<amount>value, exponent and currencyCodeThe duty on the total purchase amount for the order.
<shipFromPostalCode>--PCDATA1-10The postal code from where order is shipped.
<destinationPostalCode>--PCDATA1-10The postal code of the order destination.
<destinationCountryCode>--PCDATAISO Country CodeThe country code of the order destination.
<orderDate>--<date>dayOfMonth, month and yearThe date the order was placed.
<taxExempt>--PCDATAtrue or falseSet to true if <salesTax> is 0.
<item>

Note: You can supply a maximum of 99 line items.

<description>-✔PCDATA1-26

Note: Mandatory when <item> is supplied.

<productCode>-✔PCDATA1-12Merchant defined product code.
<commodityCode>-✔PCDATA1-12Commodity code as defined by the National Institute of Governmental Purchasing.
<quantity>-✔PCDATA1-12The number of items purchased.

Note: Must be greater than 0.

<unitCost>-✔<amount>value, exponent and currencyCodeThe price of one unit of the item purchased.
<unitOfMeasure>-✔PCDATA1-12The unit of measure of the purchased item.
<itemTotal>-✔<amount>value, exponent and currencyCodeTotal cost of the line item excluding tax.
<itemTotalWithTax>-✔<amount>value, exponent and currencyCodeTotal cost of the line item including tax.
<itemDiscountAmount>-✔<amount>value, exponent and currencyCodeItem discount amount.
<taxAmount>--<amount>value, exponent and currencyCodeTax amount for the line item.

Example requests

You can find a full XML payment submission with added Level 2/3 data below:

You can find a full example for a capture batch request with added Level 2/3 data below:

Errors

All errors related to Level 2/3 data are reported under error code 11.

Error codeDescription
11The element invoiceReferenceNumber must be between 1-15 characters : 'value supplied'
11The element customerReference must be between 1-17 characters : 'value supplied'
11The element cardAcceptorTaxId must be between 1-20 characters : 'value supplied'
11The element shipFromPostalCode must be between 1-10 characters : 'value supplied'
11The element destinationPostalCode must be between 1-10 characters : 'value supplied'
11The element destinationCountryCode does not contain a recognized country code : 'value supplied'
11Expecting either true of false, but received : 'value supplied'
11The element description is required
11The element description must be between 1-26 characters : 'value supplied'
11The element productCode must be between 1-12 characters : 'value supplied'
11The element commodityCode must be between 1-12 characters : 'value supplied'
11The element quantity is not an integer number : 'value supplied'
11The element quantity must be between 1-12 digits : 'value supplied'
11The element unitOfMeasure must be between 1-12 characters : 'value supplied'
11salesTax must be supplied when cardAcceptorTaxId is supplied