# Level 2 and 3 Data
source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/trans-enrich-data/order-and-line-item-data/level-2-and-3/index.md
A credit card transaction can be submitted with three levels of transaction data: Level 1, Level 2, and Level 3. Each level is defined by the amount of information provided to process the transaction.
* Level 1 includes standard transaction data, such as, date, card number, and total order amount.
* Level 2 includes Level 1 data plus enhanced transaction data, such as customer reference number, invoice number, and sales tax amount.
* Level 3 includes Level 2 data plus line item details.
The following methods are supported:
| Integration methods | Payment methods | Transactions |
|---------------------|-----------------|--------------------------------------------------------------------|
| All | Credit cards | * AUTHORIZE * PAY * VERIFY * CAPTURE * REFUND * AUTHENTICATE PAYER |
To view examples of API requests with Level 2 and 3 data, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api).
Tip: Mastercard Gateway recommends that API requests contain fewer than 65,000 characters. Warning:
* If you accept business, corporate, or purchase cards, providing Level 2 or 3 data on your transaction can 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.
* Your payment service provider 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 2 and 3 data is only available from API v42 onwards.
## Providing Level 2 and 3 data {#providing-level-2-and-3-data}
In \[initial transactions\], when you create an order, all Level 2 and 3 data that you provide applies to all transactions on the order. On \[subsequent transactions\], [Capture](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [Refund](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction), you only need to provide Level 2 and 3 data when you want to.
* Override the data that you provided for the order.
You can override the Level 2 and 3 data for the order. You can do this to correct information that was provided when you created the order. The updated information then applies to all subsequent transactions on the order. For example, `order.customerReference`.
Warning: You can only override those order fields that are allowed in a specific subsequent transaction. For example, order.amount can only be provided in an AUTHORIZE request, so you cannot override it in a subsequent CAPTURE request.
See the Order-level field or Transaction-level Field column in the Level 2 and 3 data tables.
* Provide data that only applies to the transaction.
You can provide Level 2 and 3 data that only applies to the specific transaction. For example, `transaction.taxAmount`.
See the Order-level field or Transaction-level Field column in the following Level 2 and 3 data tables.
* Perform CAPTURE or REFUND transactions where the transaction amount differs from the order amount. In these cases, you must provide Level 2 and 3 data on the transaction, such as amounts or line item details, as these cannot be defaulted from the order.
## Providing Level 2 and 3 data with EMV 3-D Secure {#providing-level-2-and-3-data-with-emv-3-d-secure}
If you use the gateway to perform [EMV 3-D Secure authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md) for your payment transactions, you can create an order by submitting an [Initiate Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request followed by an [Authenticate Payer](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request with Level 2 and 3 data. If you provide Level 2 and 3 data in the AUTHENTICATE PAYER request, provide the `authentication.transactionId` field in the subsequent AUTHORIZE, PAY, or VERIFY payment request. Level 2 and 3 data are populated from the referenced authentication. You can submit the same or different Level 2 and 3 data on your payment request to override Level 2 and 3 data provided on authentication.
Warning:
* If the order.amount provided in the AUTHORIZE, PAY, or VERIFY request differs from the order.amount of the authentication, Level 2 and 3 data is not copied from the authentication.
In this case, you must provide Level 2 and 3 data in the payment transaction.
* The AUTHENTICATE PAYER request supports:
* Level 2 fields from API v64 onwards
* Level 3 fields from API v77 onwards
## Sending the data to your acquirer {#sending-the-data-to-your-acquirer}
When the gateway sends Level 2 and 3 data to your acquirer, the 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 uses the values provided at the order level to send to the acquirer, as applicable.
The submitted data is returned in the transaction response.
### Level 2 data {#level-2-data}
To provide the following Level 2 data in your transaction request, use the corresponding order-level or transaction-level API fields as shown in the following table.
| Level 2 Data | Order-level field or Transaction-level Field | Description |
|-----------------------------------------------------|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Customer Order Date | `order.customerOrderDate` or N/A | Date the payer placed the order. |
| Order Amount | `order.amount` or N/A | Total amount for the order. Must equal the sum of sub-totals minus discount if provided. |
| Item Amount | `order.itemAmount` or `transaction.itemAmount` | Computed from line items if not provided. Must match the computed value if both are provided. *Rounding:* If decimal exceeds currency minor units, round half to even. |
| Shipping and Handling Amount | `order.shippingAndHandlingAmount` or `transaction.shippingAndHandlingAmount` | Total shipping and handling including applicable taxes. |
| Shipping and Handling Tax Amount | `order.shippingAndHandlingTaxAmount` or `transaction.shippingAndHandlingTaxAmount` | Tax on shipping and handling. Included in the total shipping amount. Supported from API v67. * Canada - Required for Visa transactions. |
| Shipping and Handling Tax Rate | `order.shippingAndHandlingTaxRate` or `transaction.shippingAndHandlingTaxRate` | Tax rate as decimal (for example, 0.025 for 2.5%). Supported from API v67. * Canada - Required for Visa transactions. |
| Duty Amount | `order.dutyAmount` or `transaction.dutyAmount` | Customs tax or tariff. Supported from API v67. |
| Tax Amount | `order.taxAmount` or `transaction.taxAmount` | Total tax amount. Must match the computed value from line items if both are provided. *Rounding:* Round half to even if decimal exceeds minor units. |
| Tax Type \[n\] | `order.tax[n].type` or `transaction.tax[n].type` | Type of tax. Submit only applicable types. Do not submit 0.00 amounts. **Region-specific:** | Region | Scheme | Valid Tax Type | Sample Values | |-------------------------------|------------|---------------------------------------------|----------------| | North America (US and Canada) | Mastercard | * 11 - GST * 12 - PST * 13 - HST * 14 - QST | 11, 12, 13, 14 | |
| Tax Amount \[n\] | `order.tax[n].amount` or `transaction.tax[n].amount` | Tax amount for the specified tax type. |
| Tax Rate \[n\] | `order.tax[n].rate` or `transaction.tax[n].rate` | Tax rate used to calculate the tax amount. |
| Tax Exempt Flag | `order.taxStatus` or `transaction.taxStatus` | Indicates tax exemption status. |
| Discount Amount | `order.discount.amount` or `transaction.discountAmount` | Total discount applied. |
| Merchant's Purchase Reference | `order.reference` or N/A | Order identifier. Defaults to `order.id` if not provided. |
| Invoice Number | `order.invoiceNumber` or N/A | Invoice number issued for the order. |
| Customer/Cardholder Reference Number | `order.customerReference` or N/A | Payer's reference for the order. |
| Requestor Name | `order.requestorName` or N/A | Name of the person requesting goods and services. |
| Merchant Tax Registration ID - Federal/National | `order.taxRegistrationId` or N/A | Federal tax ID or ABN. * US: Federal Tax ID * Canada: HST/GST account |
| Merchant Tax Registration ID - State/Province/Local | `order.localTaxRegistrationId` or N/A | Local tax ID. * Canada: PST/QST registration number |
| Customer VAT Registration Number | `customer.taxRegistrationId` or N/A | Customer's tax registration ID. |
| Merchant Address - ZIP/Post Code | | Submitted as configured in merchant profile. |
| Merchant Address - State/Province | | Submitted as configured in the merchant profile. |
| Ship From ZIP/Post Code | `shipping.origin.postcodeZip` or N/A | ZIP/post code of shipping origin. Defaults to merchant profile if not provided. |
| Shipping Destination Street | `shipping.address.street` or `shipping.address.street2` or N/A | First and second lines of the shipping address. |
| Shipping Destination City | `shipping.address.city` or N/A | City of the shipping address. |
| Shipping Destination State/Province | `shipping.address.stateProvince` or N/A | ISO 3166-2 subdivision code. For US territories, use country code. |
| Shipping Destination Country | `shipping.address.country` or N/A | 3-letter ISO country code. For US territories, use country code in both fields. |
| Shipping Destination ZIP/Post Code | `shipping.address.postcodeZip` or N/A | ZIP/post code of the shipping destination. |
| Billing Address Name | `customer.firstName` or `customer.lastName` or N/A | Payer's first and last name. |
| Billing Address Street 1 | `billing.address.street` or N/A | First line of billing address. |
| Billing Address Street 2 | `billing.address.street2` or N/A | Second line of billing address. |
| Billing Address City | `billing.address.city` or N/A | City of billing address. |
| Billing Address State | `billing.address.stateProvince` or N/A | State or province of billing address. |
| Billing Address ZIP/Postal Code | `billing.address.postcodeZip` or N/A | ZIP/post code of billing address. |
| Billing Address Country | `billing.address.country` or N/A | 3-letter ISO country code of billing address. |
### Level 3 data {#level-3-data}
Level 3 data includes Level 2 data that are listed in the previous section plus line item data. To provide the following Level 3 data in your transaction request, use the corresponding order-level from the `order.item[n]` object or transaction-level from the `transaction.item[n]` object API fields as shown in the following table.
Warning:
* All Level 3 fields are optional; however, if you provide any line item data on a transaction request, you must provide at least the name, quantity, and unit price for that item.
* The value for Item Merchant Tax ID cannot be provided on item level. The value provided on the order level in the order.taxRegistrationId field is submitted to the acquirer for all items.
To provide the following Level 3 data in your transaction request, use the corresponding order-level or transaction-level API fields as shown in the following table.
| Level 3 Data | Order-level Field or Transaction-level Field | Description |
|----------------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Item Total | If required in the acquirer message, this amount is computed as the sum of the total item amount (for example, `order.item[n].unitPrice` × `order.item[n].quantity`) for all line items. The order-level fields are copied into the transaction-level details unless the merchant submits a different amount or quantity in partial CAPTURE requests. ||
| Item Unit of Measure | `order.item[n].unitOfMeasure` or `transaction.item[n].unitOfMeasure` | Unit of measure used for the item quantity. Enumeration values may be required by your acquirer. See [Breakdown of tax amount per type for the line item. Submit only applicable tax types. Do not submit 0.00 amounts. **Region-specific:** | Region | Scheme | Valid Tax Type | Sample Values | |-------------------------------|------------|---------------------------------------------|----------------| | North America (US and Canada) | Mastercard | * 11 - GST * 12 - PST * 13 - HST * 14 - QST | 11, 12, 13, 14 |](../../picklFunctionality/levelIIAndIIIData/americanExpress.html?locale=en_US#x_L3UnitOfMeasureItem Unit of Measure Enumeration Values. | Item Description | order.item[n].description or transaction.item[n].description | Description for the item including details like size, color, etc. |
| Item Brand | order.item[n].brand or transaction.item[n].brand | Brand of the item. |
| Item Category | order.item[n].category or transaction.item[n].category | Your category for the item. |
| Item Industry Category | order.item[n].industryCategory or transaction.item[n].industryCategory | Industry category for specialized processing as industry data. |
| Item Name | order.item[n].name or transaction.item[n].name | Short name describing the item. |
| Item SKU | order.item[n].sku or transaction.item[n].sku | Stock Keeping Unit (SKU) or item identifier. |
| Item UNSPSC | order.item[n].detail.unspsc or transaction.item[n].detail.unspsc | United Nations Standard Products and Services Code. |
| Item UPC | order.item[n].detail.upc or transaction.item[n].detail.upc | Universal Product Code for the item. |
| Item Commodity Code | order.item[n].detail.commodityCode or transaction.item[n].detail.commodityCode | Code describing goods classification. |
| Item Quantity | order.item[n].quantity or transaction.item[n].quantity | Quantity of the item. If decimal places exceed minor units of currency, rounding is applied using the round half to even algorithm. |
| Item Unit Price | order.item[n].unitPrice or transaction.item[n].unitPrice | Cost price for the item. Multiplied by quantity to compute total item amount. Must match order.itemAmount or transaction.itemAmount if provided. |
| Item Unit Tax Amount | order.item[n].unitTaxAmount or transaction.item[n].unitTaxAmount | Tax amount per item. Multiply by quantity to get total tax for the item. |
| Item Tax Type | order.item[n].detail.unitTaxType or transaction.item[n].detail.unitTaxType | Single tax type charged for the line item. |
| Item Tax Rate (Percentage) | order.item[n].detail.unitTaxRate or transaction.item[n].detail.unitTaxRate | Single tax rate charged for the line item. |
| Item Tax Type [n] | order.item[n].detail.tax[m].type or transaction.item[n].detail.tax[m].type |