Level 2 and 3 Data
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.
Supported for following methods:
| Integration methods | Payment methods | Transactions |
|---|---|---|
| All | Credit cards |
|
To view examples of API requests with Level 2 and 3 data, download the Postman collection.
- 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
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 or Refund, you only need to provide Level 2 and 3 data when you want to.
- Override the data 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.You can only override those order fields that are allowed in a specific subsequent transaction. For example,order.amountcan 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 3DS
If you use the gateway to perform 3D Secure (3DS) authentication for your payment transactions, you can create an order by submitting an Initiate Authentication request followed by an Authenticate Payer 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 is 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.
- If the
order.amountprovided in the AUTHORIZE, PAY, or VERIFY request differs from theorder.amountof 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
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, where applicable only.
The submitted data is returned in the transaction response.
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 NA |
Date the payer placed the order. |
| Order Amount (the amount to be authorized, submitted when creating an order) | order.amount or NA |
Total amount for the order. If you provide any sub-total amounts (order.itemAmount, order.shippingAndHandlingAmount, order.taxAmount, order.gratuityAmount, order.cashbackAmount), and order.discount.amount, the order amount must equal the sum of the sub-total amounts minus the discount amount. |
| Item Amount | order.itemAmount or transaction.itemAmount |
If you do not provide this field but provide any line item data, this amount is computed as the sum of the total item amount, for example, 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, 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 rounds the total using the round half to even algorithm. For example, if 2.555 (quantity) times 3 (unit price) totals 7.665, and if a payer's currency (USD) has 2 minor units, the rounded item amount equals to 7.66.
Ensure you apply this rounding when you provide the item amount field in the request. |
| Shipping and Handling Amount | order.shippingAndHandlingAmount or transaction.shippingAndHandlingAmount |
Total shipping and handling amount for the order or transaction including any applicable taxes. |
| Shipping and Handling Tax Amount | order.shippingAndHandlingTaxAmount or transaction.shippingAndHandlingTaxAmount |
Tax amount levied on the shipping and handling amount for the order or transaction. This amount is included in the shipping and handling amount provided in the order.shippingAndHandlingAmount/transaction.shippingAndHandlingAmount field.
This field is supported from API v67 onwards. |
| Shipping and Handling Tax Rate | order.shippingAndHandlingTaxRate or transaction.shippingAndHandlingTaxRate |
Tax rate applied to the shipping and handling amount for the order/transaction to determine the shipping and handling tax amount. For a tax rate of 2.5%, provide 0.025. This field is supported from API v67 onwards. |
| Duty Amount | order.dutyAmount or transaction.dutyAmount |
Duty amount, also known as customs tax, tariff, or dues, for the order or transaction. This field is supported from API v67 onwards. |
| Tax Amount | order.taxAmount or transaction.taxAmount |
Total tax amount for the order or transaction. If you do not provide this field but provide any line item data, this amount is computed as the sum of the total tax amount (for example, 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, 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 rounds 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, the rounded item amount equals 7.66.
Ensure you apply this rounding when you provide the item amount field in the request. |
| Tax Type [n] | order.tax[n].type or transaction.tax[n].type |
Type of tax included in the order or transaction amount. You may be required to submit the correct enumeration value as required by your acquirer. Contact your payment service provider for details. |
| Tax Amount [n] | order.tax[n].amount or transaction.tax[n].amount |
Tax amount included in this order or transaction for the tax type. |
| Tax Rate [n] | order.tax[n].rate or transaction.tax[n].rate |
Tax rate (percentage) used to determine the tax amount included in this order or transaction for the tax type. |
| Tax Exempt Flag | order.taxStatus or transaction.taxStatus |
Your tax status for this order or transaction. |
| Discount Amount | order.discount.amount or transaction.discountAmount |
Total amount of the discount you have applied to the order or transaction. |
| Merchant's Purchase Reference | order.reference or NA |
Identifier of the order. If not provided, the gateway uses the value as provided in order.id (mandatory field). |
| Invoice Number | order.invoiceNumber or NA |
Invoice number you issued for this order. |
| Customer or Cardholder Reference Number | order.customerReference or NA |
Payer's own reference for the order. |
| Requestor Name | order.requestorName or NA |
Name of the person who requested the goods or services. |
| Merchant Tax Registration ID - Federal or National | order.taxRegistrationId or NA |
Your tax registration identifier provided by the Federal or National tax authority, for example, federal tax identification number, ABN. If you are a US merchant, provide your Federal Tax ID. If you are a Canadian merchant, provide your Harmonized Sales Tax (HST) account with the Canada Revenue Agency. |
| Merchant Tax Registration ID - State or Province or Local | order.localTaxRegistrationId or NA |
Your tax registration identifier provided by the Local or State or Province tax authority. If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Provincial Sales Tax (PST). |
| Customer VAT Registration Number | customer.taxRegistrationId or NA |
Tax registration identifier of the customer. |
| Merchant Address - ZIP or Post Code | |
The value as configured on your merchant profile is submitted to the acquirer. |
| Merchant Address - State or Province | |
The value as configured on your merchant profile is submitted to the acquirer. |
| Ship From ZIP or Post Code | shipping.origin.postcodeZip or NA |
Post code or ZIP code of the address the order is shipped from. If not provided, the value as configured on your merchant profile is submitted to the acquirer. |
| Shipping Destination Street | shipping.address.street or
NA
shipping.address.street2 or NA |
First line of the address.
Second line of the address, if provided. |
| Shipping Destination City | shipping.address.city or NA |
City of the address. |
| Shipping Destination State or Province | shipping.address.stateProvince or NA |
State or province of the address. You must provide the three-character ISO 3166-2 country subdivision code. If the destination is a US territory, provide the country code. For example, GUM in both the shipping.address.country and the shipping.address.stateProvince fields. Provide this field only if all items included in the order are shipped to the same location. |
| Shipping Destination Country | shipping.address.country or NA |
3-letter ISO standard alpha country code of the address. If the destination is a US territory, provide the country code. For example, GUM in both the shipping.address.country and the shipping.address.stateProvince fields. Provide this field only if all items included in the order are shipped to the same location. |
| Shipping Destination ZIP or Post Code | shipping.address.postcodeZip or NA |
Post code or ZIP code of the address. |
| Billing Address Name | customer.firstName or
|
Payer's first name.
Payer's last name. |
| Billing Address Street 1 | billing.address.street or NA |
First line of the address. |
| Billing Address Street 2 | billing.address.street2 or NA |
Second line of the address, if provided. |
| Billing Address City | billing.address.city or NA |
City of the address. |
| Billing Address State | billing.address.stateProvince or NA |
State or province of the address. |
| Billing Address ZIP or Postal code | billing.address.postcodeZip or NA |
Post code or ZIP code of the address. |
| Billing Address Country | billing.address.country or NA |
3-letter ISO standard alpha country code of the address. |
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.
- 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.taxRegistrationIdfield 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 times order.item[n].quantity) for all the 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. You may be required to submit the correct enumeration value as required by your acquirer. Contact your payment service provider for details. |
| Item Description | order.item[n].description or transaction.item[n].description |
Description for the item with information such as size, color, and so on. |
| 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 |
Provide the industry category to send this line item to your acquirer 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 the item identifier for this item. |
| Item United Nations Standard Products and Services Code (UNSPSC) | order.item[n].detail.unspsc or transaction.item[n].detail.unspsc |
United Nations Standard Products and Services Code for the item. |
| Item Universal Product Code (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 a commodity or a group of commodities pertaining to goods classification. |
| Item Quantity | order.item[n].quantity or transaction.item[n].quantity |
Quantity of the item.
When a decimal quantity is multiplied by amounts (for example,
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 rounds 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, the rounded item amount equals 7.66. |
| Item Unit Price | order.item[n].unitPrice or transaction.item[n].unitPrice |
Cost price for the item.
This amount is multiplied with order.item[n].quantity or transaction.item[n].quantity to compute the total item amount for the line item. If order.itemAmount or transaction.itemAmount is provided, the sum of the total item amount for all the line items must equal the value in order.itemAmount or transaction.itemAmount. |
| Item Unit Tax Amount | order.item[n].unitTaxAmount or transaction.item[n].unitTaxAmount |
Total amount of the discount you have applied to the order or transaction. |
| Item Tax Type | order.item[n].detail.unitTaxType or transaction.item[n].detail.unitTaxType |
If there is only a single tax type, use this field to provide the tax type charged for this line item. |
| Item Tax Rate (Percentage) | order.item[n].detail.unitTaxRate or transaction.item[n].detail.unitTaxRate |
If there is only a single tax rate, use this field to provide the tax rate charged for this line item. |
| Item Tax Type [n] | order.item[n].detail.tax[m].type or transaction.item[n].detail.tax[m].type |
Use these fields to provide a breakdown of the order or 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 is a single tax type, use order.item[n].detail.unitTaxType or transaction.item[n].detail.unitTaxType. |
| Item Tax Amount [n] | order.item[n].detail.tax[m].amount or transaction.item[n].detail.tax[m].amount |
|
| Item Tax Rate [n] (Percentage) | order.item[n].detail.tax[m].rate or transaction.item[n].detail.tax[m].rate |
|
| Item Discount Amount | order.item[n].unitDiscountAmount or transaction.item[n].unitDiscountAmount |
Discount amount applied to this item.
This amount is multiplied with order.item[n].quantity or transaction.item[n].quantity to compute the total discount amount for the line item. If order.discount.amount or transaction.discountAmount is provided, the value in this field must equal the sum of the total discount amount for all the line items. |
| Item Discount Rate (Percentage) | order.item[n].detail.unitDiscountRate or transaction.item[n].detail.unitDiscountRate |
Discount rate, percentage, applied to this item. |
Example of Level 2 and 3 data fields
{
"customer": {
"taxRegistrationId": "BA1234",
"firstName": "John",
"lastName": "Smith"
},
"order": {
"customerReference": "345",
"reference": "2412",
"invoiceNumber": "TEST001",
"customerOrderDate": "2022-07-22",
"requestorName": "John Smith",
"shippingAndHandlingTaxAmount": 1.00,
"shippingAndHandlingTaxRate": 33.32,
"localTaxRegistrationId": "ABCD1234",
"taxRegistrationId": "AB/CD/12-34",
"dutyAmount": 1.00,
"taxStatus": "NOT_EXEMPT",
"currency": "USD",
"amount": "206",
"taxAmount": "15",
"shippingAndHandlingAmount": "100",
"tax": [
{
"type": "11",
"amount": "1.00",
"rate": "0.01"
},
{
"type": "12",
"amount": "2.00",
"rate": "0.02"
},
{
"type": "13",
"amount": "4.00",
"rate": "0.04"
},
{
"type": "14",
"amount": "5.00",
"rate": "0.05"
}
],
"item": [
{
"name": "TestItem_01",
"brand": "dell",
"category": "electronics",
"description": "laptop 1TB 64GB",
"quantity": "1",
"unitPrice": "50",
"unitOfMeasure": "EA",
"unitDiscountAmount": "5.00",
"unitTaxAmount": "5",
"sku": "2",
"detail": {
"commodityCode": "999992",
"unitDiscountRate": "5",
"unitTaxRate: "1",
"unspsc "1",
"upc": "123",
"tax": [
{
"amount": "5",
"rate": "1",
"type": "11"
},
{
"amount": "5",
"rate": "10.5",
"type": "12"
}
]
}
},
{
"name": "TestItem_02",
"brand": "Lexus",
"category": "motorvehicles",
"description": "Lexus RX350",
"quantity": "1",
"unitPrice": "50",
"unitOfMeasure": "EA",
"unitDiscountAmount": "5.00",
"unitTaxAmount": "10",
"detail": {
"commodityCode": "896292",
"unitDiscountRate": "5",
"upc": "999",
"tax": [
{
"amount": "10",
"rate": "1",
"type": "13"
},
{
"amount": "10",
"rate": "10.5",
"type": "14"
}
]
}
}
]
},
"shipping": {
"address": {
"street": "123 Main St",
"stateProvinceCode": "NY",
"stateProvince": "New York",
"postcodeZip": "10000",
"city": "New York",
"country": "USA"
}
},
"billing": {
"address": {
"street": "456 East End Ave",
"stateProvinceCode": "NY",
"stateProvince": "New York",
"postcodeZip": "10021",
"city": "New York",
"country": "USA"
}
}
}