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.
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.
When you create an order all Level II/III data that you provide will apply to all transactions on the order.
You only need to provide Level II/III data on subsequent operations (Capture or Refund) when you want to:
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
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.
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.
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.
To provide the following Level II data in your transaction request, use the corresponding order-level and/or transaction-level API 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 The total shipping and handling amount for the transaction including any applicable taxes. |
transaction.shippingAndHandlingAmount |
Shipping and Handling Tax Amount | order.shippingAndHandlingTaxAmount This field is supported from the version 67 and above. The tax amount levied on the shipping and handling amount for the transaction. This amount is included in the shipping and handling amount provided in the field order.shippingAndHandlingTaxAmount .
|
transaction.shippingAndHandlingTaxAmount |
Shipping and Handling Tax Rate | order.shippingAndHandlingTaxRate This field is supported from the version 67 and above. The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount. For a tax rate of 2.5%, provide 0.025. |
transaction.shippingAndHandlingTaxRate |
Duty Amount | order.dutyAmount This field is supported from the version 67 and above. The duty amount also known as customs tax, tariff, or dues, for the transaction. |
transaction.dutyAmount |
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 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 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/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 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)
API fields as shown in the table below.
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 |
Copyright © 2023 Mastercard