Level II and Level III Data

A credit card transaction may be submitted with three levels of transaction data: Level I, Level II, and Level III. Each level is defined by the amount of information provided to process the transaction.

  • Level I includes standard transaction data such as date, card number, and total purchase amount.
  • Level II includes Level I data plus enhanced transaction data such as customer reference number, invoice number, and sales tax amount.
  • Level III includes Level II data plus line item details.

If you accept business, corporate, or purchase cards then providing Level II/III data on your transaction may qualify the transaction for better interchange rates. Your customer's business can also benefit from itemized card statements as well as information to support and streamline business processes such as purchasing authorization, reconciliation, and reporting.

Note that the gateway does not validate that the data provided on the transaction is sufficient to qualify for specific interchange rates as required by the card schemes.

The support for Level II/III data is only available from DirectAPI version 42 and above.

Providing Level II/III Data on Initial Operations

When you create an order all Level II/III data that you provide will apply to all transactions on the order.

Providing Level II/III Data on Subsequent Operations

You only need to provide Level II/III data on subsequent operations (Capture or Refund) when you want to:

  • override the data you provided for the order

    You can override the Level II/III data for the order by providing the data at order level. You may want to do this to correct information provided when you created the order. The updated information will then apply to all subsequent transactions on the order. For example, order.customerReference

    Only order-level fields present on the transaction request can be overridden. For example, order.amount can be provided in an Authorize transaction request, but not on a subsequent Capture transaction request.

    See Order-Level Field column in the Level II/III tables below.

  • provide data that only applies to the transaction

    You can provide Level II/III data that only applies to the specific transaction. For example, transaction.taxAmount

    See Transaction-Level Field column in the Level II/III tables below.

  • perform Capture or Refund transactions where the transaction amount differs from the order amount. In these cases, you must provide Level II/III data on the transaction, like amounts or line item details, as these cannot be defaulted from the order.

Sending Level II/III Data to your Acquirer

When the gateway sends Level II/III data to your acquirer, values provided on the transaction take precedence over the values provided at the order level. If you do not provide values on the transaction, the gateway will use the values provided at the order level to send to the acquirer, where applicable only.

Level II/III data will only be submitted to the acquirer for Capture and Refund transactions but not for Authorization or Verification Only transactions.
Level II Data

To provide the following Level II data in your transaction request, use the corresponding order-level and/or transaction-level DirectAPI fields as shown in the table below.

Level II Data Order-level Field Transaction-level Field
Customer Order Date order.customerOrderDate  
Order Amount (the amount to be authorized, submitted when creating an order) order.amount

If you provide any sub-total amounts (order.itemAmount, order.shippingAndHandlingAmount, order.taxAmount, order.gratuityAmount, order.cashbackAmount), order.discount.amount then the order amount MUST equal the sum of the sub-total amounts minus the discount amount.
 
Item Amount order.itemAmount

If you do not provide this field but provide any line item data, then this amount is computed as the sum of the total item amount (order.item[n].unitPrice times order.item[n].quantity) for all the line items. If you provide both this field and any line item data then the value in this field MUST equal the computed value.
If the decimal places in the computed value exceed the minor units of the payer's currency the gateway will round the total using the "round half to even" algorithm. For example, if 2.555 (quantity) times 3 (unit price) totals 7.665, and if the payer's currency (USD) has 2 minor units, then the rounded item amount will equal 7.66.
Ensure you apply this rounding when you provide the item amount field in the request.
transaction.itemAmount
Shipping and Handling Amount order.shippingAndHandlingAmount transaction.shippingAndHandlingAmount
Tax Amount order.taxAmount
If you do not provide this field but provide any line item data, then this amount is computed as the sum of the total tax amount (order.item[n].unitTaxAmount times order.item[n].quantity) for all the line items. If you provide both this field and any line item data then the value in this field MUST equal the computed value.
If the decimal places in the computed value exceed the minor units of the payer's currency the gateway will round the total using the "round half to even" algorithm. For example, if 2.555 (quantity) times 3 (unit price) totals 7.665, and if the payer's currency (USD) has 2 minor units, then the rounded item amount will equal 7.66.
Ensure you apply this rounding when you provide the item amount field in the request.
transaction.taxAmount
Tax Type [n] order.tax[n].type

You may be required to submit the correct enumeration value as required by your acquirer. Please contact your payment service provider for details.
transaction.tax[n].type

You may be required to submit the correct enumeration value as required by your acquirer. Please contact your payment service provider for details.
Tax Amount [n] order.tax[n].amount transaction.tax[n].amount
Tax Rate [n] order.tax[n].rate transaction.tax[n].rate
Tax Exempt Flag order.taxStatus transaction.taxStatus
Discount Amount order.discount.amount transaction.discountAmount
Merchant's Purchase Reference order.reference

If not provided, the gateway uses the value as provided in order.id (mandatory field).
 
Invoice Number order.invoiceNumber
 
Customer/Cardholder Reference Number order.customerReference  
Requestor Name order.requestorName  
Merchant Tax Registration ID - Federal/National order.taxRegistrationId If you are a US merchant, provide your Federal Tax ID.
If you are a Canadian merchant, provide your HST (Harmonized Sales Tax) account with the Canada Revenue Agency.
Merchant Tax Registration ID - State/Province/Local order.localTaxRegistrationId  
Customer VAT Registration Number customer.taxRegistrationId  
Merchant Address - ZIP/Post Code The value as configured on your merchant profile is submitted to the acquirer.
Merchant Address - State/Province The value as configured on your merchant profile is submitted to the acquirer.
Ship From ZIP/Post Code shipping.origin.postcodeZip
If not provided, the value as configured on your merchant profile may be submitted to the acquirer.
 
Shipping Destination Street shipping.address.street
shipping.address.street2
 
Shipping Destination City shipping.address.city  
Shipping Destination State/Province shipping.address.stateProvince  
Shipping Destination Country  shipping.address.country  
Shipping Destination ZIP/Post Code shipping.address.postcodeZip  
Billing Address Name customer.firstName
customer.lastName
 
Billing Address Street 1 billing.address.street  
Billing Address Street 2 billing.address.street2  
Billing Address City billing.address.city  
Billing Address State billing.address.stateProvince  
Billing Address ZIP/Postal code billing.address.postcodeZip  
Billing Address Country billing.address.country  

Level II Data API Reference [REST][NVP]

Level III Data

Level III data includes Level II data listed above plus line item data. To provide the following Level III data in your transaction request, use the corresponding order-level (from the order.item[n] parameter group) and/or transaction-level (from the transaction.item[n] parameter group) DirectAPI fields as shown in the table below.

All Level III fields are optional; however, if you provide any line item data on a transaction request, then you MUST provide at least the name, quantity, and unit price for that item.
Level III Data Order-level Field Transaction-level Field
Item Merchant Tax ID The value cannot be provided on item level. For all items the value provided on the order level in field order.taxRegistrationId will be submitted to the acquirer.
Item Total If required in the acquirer message then this amount is computed as the sum of the total item amount (order.item[n].unitPrice times order.item[n].quantity) for all the line items.
Item Unit of Measure order.item[n].unitOfMeasure

You may be required to submit the correct enumeration value as required by your acquirer. Please contact your payment service provider for details.
transaction.item[n].unitOfMeasure

You may be required to submit the correct enumeration value as required by your acquirer. Please contact your payment service provider for details.
Item Description order.item[n].description transaction.item[n].description
Item Brand order.item[n].brand transaction.item[n].brand
Item Category order.item[n].category transaction.item[n].category
Item Industry Category order.item[n].industryCategory transaction.item[n].industryCategory
Item Name order.item[n].name transaction.item[n].name
Item SKU order.item[n].sku transaction.item[n].sku
Item UNSPSC (United Nations Standard Products and Services Code) order.item[n].detail.unspsc transaction.item[n].detail.unspsc
Item UPC (Universal Product Code) order.item[n].detail.upc transaction.item[n].detail.upc
Item Commodity Code order.item[n].detail.commodityCode transaction.item[n].detail.commodityCode
Item Quantity order.item[n].quantity
When a decimal quantity is multiplied by amounts (order.item[n].unitPrice, order.item[n].unitTaxAmount, or order.item[n].unitDiscountAmount), and if the decimal places in the computed value exceed the minor units of the payer's currency the gateway will round the total using the "round half to even" algorithm. For example, if 2.555 (quantity) times 3 (unit price) totals 7.665, and if the payer's currency (USD) has 2 minor units, then the rounded item amount will equal 7.66.
transaction.item[n].quantity
Item Unit Price order.item[n].unitPrice

This amount is multiplied with order.item[n].quantity to compute the total item amount for the line item. If order.itemAmount is provided, then the sum of the total item amount for all the line items MUST equal the value in order.itemAmount
transaction.item[n].unitPrice
Item Unit Tax Amount order.item[n].unitTaxAmount

This amount is multiplied with order.item[n].quantity to compute the total tax amount for the line item. If order.taxAmount is provided, then the sum of the total tax amount for all the line items MUST equal the value in order.taxAmount.
transaction.item[n].unitTaxAmount
Item Tax Type order.item[n].detail.unitTaxType
Use this field to provide the tax type charged for this line item, if only a single tax type.
transaction.item[n].detail.unitTaxType
Item Tax Rate (Percentage) order.item[n].detail.unitTaxRate
Use this field to provide the tax rate charged for this line item, if only a single tax rate.
transaction.item[n].detail.unitTaxRate
Item Tax Type [n] order.item[n].detail.tax[m].type
order.item[n].detail.tax[m].amount
order.item[n].detail.tax[m].rate

Use these fields to provide a breakdown of the order tax amount for the line item per tax type. This applies if there are more than one tax type charged for this line item. If there's a single tax type, use order.item[n].detail.unitTaxType
transaction.item[n].detail.tax[m].type
transaction.item[n].detail.tax[m].amount
transaction.item[n].detail.tax[m].rate

Use these fields to provide a breakdown of the transaction tax amount for the line item per tax type. This applies if there are more than one tax type charged for this line item. If there's a single tax type, use transaction.item[n].detail.unitTaxType
Item Tax Amount [n]
Item Tax Rate [n] (Percentage)
Item Discount Amount order.item[n].unitDiscountAmount

This amount is multiplied with the order.item[n].quantity to compute the total discount amount for the line item. If order.discount.amount is provided, then the value in this field MUST equal the sum of the total discount amount for all the line items.
transaction.item[n].unitDiscountAmount
Item Discount Rate (Percentage) order.item[n].detail.unitDiscountRate transaction.item[n].detail.unitDiscountRate

Level III Data API Reference [REST][NVP]

Copyright © 2020 Commonwealth Bank of Australia