Online Payments

Level 2 and Level 3 data

Commercial cards are payment cards issued by financial institutions to businesses and organizations to manage business-related expenses. The individual products include Corporate, Business, and Purchase or Purchasing cards. The American Express product is called Corporate Purchasing. To be eligible for a better rate when you accept a commercial card, provide additional data in the payment. Additional data applicable to commercial cards is categorized as level 2 and level 3 data. The requirements for level 2 and level 3 data vary by card brand.

Level 2 data

A commercial card with support for level 2 data offers enhanced transaction data capabilities for the cardholder. The additional level 2 information enables effective expense management and compliance for the cardholder's business.

Benefits

Gives businesses greater control over their transactions
Introduces eligibility for improved interchange
More efficiently manages operations
Allows for streamlined reporting and reconciliation
Improves security against fraud
Enhances customer insights and marketing trends

Review the following level 2 data field requirements by payment brand:

Level 2 data fields
Field	Visa/ChaseNet	Mastercard	American Express	Discover
retailAddenda.`purchaseOrderNumber`	Optional	Required	Optional	Optional
retailAddenda.`taxAmount`	Required	Required	Optional	Optional
retailAddenda.`isTaxable`	Optional	Required	Optional	Required
shipTo.shippingAddress.`postalCode`	Optional	Optional	Required	Optional

Note

The taxAmount must be greater than zero to be eligible for a lower interchange rate.

Level 3 data

Purchase card level 3 data is detailed transaction information such as descriptions, quantities, and prices during a credit card transaction, often required for business-to-business transactions. Include this data to provide transparency and details about the purchase to be eligible to qualify for a lower interchange rate.

Send purchase card level 3 data in your card payment requests to identify information about an order and the individual items contained (line-item details). Send level 3 data in either the payment authorization or capture request. The card brand receives level 3 data at settlement.

Refer to the table Visa and Mastercard level 3 data field requirements for details.

Benefits

The benefits of level 3 data include:

Enhanced reporting on the cardholder statement: Provides detailed transaction data, such as item descriptions, quantities, and prices, which can improve financial reporting and analysis for your customer. The level of reporting available on the cardholder statement varies per card issuer.
Cost savings: Merchant businesses often receive lower interchange fees as card networks offer reduced rates for transactions with level 3 data.
Streamlined reconciliation: Simplifies the reconciliation process with comprehensive transaction details.
Scalable reconciliation: As transaction volumes increase, level 3 data enhances reconciliation for cardholder organizations such as government agencies and large corporations by streamlining and improving the reconciliation process.

Review the following level 3 data field reference table for details on field usage and constraints.

Level 3 Data Field Reference
Field Name	Description	Example value
`taxInclusiveLineItemTotalAmount`	Specifies the total price, including tax, for all items purchased in the transaction. To refund a line item, enter a negative sign in the `taxInclusiveLineItemTotalAmount` value. For example, in US dollars, the value -12000 indicates a refund of $120.00 for the corresponding line item.	5000,-12000
`totalShippingAmount`	Specifies the shipping cost to deliver all purchased items to the consumer. If the currency is not a zero decimal currency, the allowed value for `level3.totalShippingAmount` is 0 to 999999999, which is up to 9 digits. If the currency is a zero decimal currency, the allowed value is 0 to 9999999, which is up to 7 digits. For more information on decimal currency, refer to Currency codes.	0, 12345, 999999999

HTTP method: POSTEndpoint: /payments

Json

{
    "retailAddenda": {
        "taxAmount": 100,
        "isTaxable": true,
        "purchaseOrderNumber": "1234567890",
        "orderDate": "2019-09-10",
        "level3": {
            "totalShippingAmount": 100,
            "dutyAmount": 500,
            "shipToAddressPostalCode": "33607",
            "shipToAddressCountryCode": "USA",
            "shipFromAddressPostalCode": 34490,
            "totalTransactionDiscountAmount": 20,
            "shippingValueAddedTaxAmount": 50,
            "shippingValueAddedTaxPercent": 10,
            "orderDiscountTreatmentCode": 2,
            "valueAddedTaxAmount": 54,
            "valueAddedTaxPercent": 90,
            "valueAddedTaxInvoiceReferenceNumber": 9999,
            "partyTaxGovernmentIssuedIdentifier": 30,
            "alternateTaxAmount": 2,
            "lineItems": [
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": 30,
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20%",
                            "taxTypeCode": "0124"
                        }
                    ]
                },
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": 30,
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20%",
                            "taxTypeCode": "0124"
                        }
                    ]
                },
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": 30,
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20%",
                            "taxTypeCode": "0124"
                        }
                    ]
                }
            ]
        }
    }
}

Response:

Json

{
    "retailAddenda": {
        "purchaseOrderNumber": "1234567890",
        "orderDate": "2019-09-10",
        "taxAmount": 100,
        "isTaxable": true,
        "level3": {
            "totalShippingAmount": 100,
            "dutyAmount": 500,
            "shipToAddressPostalCode": "33607",
            "shipToAddressCountryCode": "USA",
            "shipFromAddressPostalCode": "34490",
            "totalTransactionDiscountAmount": 20,
            "valueAddedTaxAmount": 54,
            "valueAddedTaxPercent": "90",
            "shippingValueAddedTaxPercent": "10",
            "orderDiscountTreatmentCode": "2",
            "valueAddedTaxInvoiceReferenceNumber": "9999",
            "shippingValueAddedTaxAmount": 50,
            "partyTaxGovernmentIssuedIdentifier": "30",
            "alternateTaxAmount": 2,
            "lineItems": [
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": "30",
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "taxTypeCode": "0124",
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20%"
                        }
                    ]
                },
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": "30",
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "taxTypeCode": "0124",
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20"
                        }
                    ]
                },
                {
                    "lineItemDescriptionText": "Off-road tires",
                    "merchantProductIdentifier": "041",
                    "itemComodityCode": "1234",
                    "lineItemUnitQuantity": "1",
                    "lineItemUnitofMeasureCode": "UNIT",
                    "unitPriceAmount": 1000,
                    "taxInclusiveLineItemTotalAmount": 120,
                    "transactionDiscountAmount": 10,
                    "purchaseTransactionDiscountPercent": "30",
                    "lineItemDiscountTreatmentCode": "1",
                    "lineItemDetailCode": "0",
                    "lineItemTaxIndicator": true,
                    "lineItemDiscountIndicator": true,
                    "lineItemTaxes": [
                        {
                            "taxTypeCode": "0124",
                            "lineItemTaxAmount": 30,
                            "taxPercent": "20%"
                        }
                    ]
                }
            ]
        }
    }
}

Visa, ChaseNet, and Mastercard requirements

Visa, ChaseNet, and Mastercard only support line-item data on level 3-capable cards. The authorization response identifies if the card is level 3 capable.

If the paymentMethodType.card.cardTypeIndicators.isLevel3Eligible value is true, the card can support level 3 line-item data. If the paymentMethodType.card.cardTypeIndicators.isLevel3Eligible value is false, the card is not capable of supporting level 3 line-item data. If you send level 3 data on all payment requests, we only send level 3 data to the card networks when eligible.

On Visa transactions, the transaction amount must equal the total of all of the retailAddenda.level3.lineItems[ ].taxInclusiveLineItemTotalAmount values plus the retailAddenda.level3.totalShippingAmount plus the retailAddenda.level3.dutyAmount plus the retailAddenda.level3.shippingValueAddedTaxAmount minus the retailAddenda.level3.totalTransactionDiscountAmount. If the totals are not correct, Online Payments returns an error.

Mastercard requires level 2 data when supporting purchase card level 3 data. The required fields are:

retailAddenda.purchaseOrderNumber
retailAddenda.taxAmount
retailAddenda.isTaxable

Visa and Mastercard level 3 data field requirements

Visa and Mastercard level 3 field requirements
Field	Visa	Mastercard	Notes
retailAddenda.`purchaseOrderNumber`	Optional	Required	Level 2 field.
retailAddenda.`orderDate`	Optional	Optional	Level 2 field.
retailAddenda.`taxAmount`	Required	Required	Level 2 field.
retailAddenda.`isTaxable`	Optional	Required	Level 2 field.
retailAddenda.level3.`totalShippingAmount`	Required Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Optional Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.
retailAddenda.level3.`dutyAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Optional Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.
retailAddenda.level3.`shipToAddressPostalCode`	Required	Required	Conditionally required if the transaction involves shipment.
retailAddenda.level3.`shipToAddressCountryCode`	Required	Optional	Conditionally required if the transaction involves shipment.
retailAddenda.level3.`shipFromAddressPostalCode`	Required	Optional	Conditionally required if the transaction involves shipment.
retailAddenda.level3.`totalTransactionDiscountAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	N/A	Conditionally required if the transaction is discounted.
retailAddenda.level3.`valueAddedTaxAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Optional Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Provide if VAT tax applies.
retailAddenda.level3.`valueAddedTaxPercent`	Required	N/A	Provide if VAT tax applies.
retailAddenda.level3.`shippingValueAddedTaxAmount`	Required Maximum length of 12 If you send an amount greater than these maximums, we will truncate from the right.	N/A	Provide if VAT tax applies.
retailAddenda.level3.`shippingValueAddedTaxPercent`	Required	N/A	Provide if VAT tax applies.
retailAddenda.level3.`orderDiscountTreatmentCode`	Optional	N/A
retailAddenda.level3.`taxTreatmentCode`	Optional	N/A
retailAddenda.level3.`valueAddedTaxInvoiceReferenceNumber`	Optional	N/A
retailAddenda.level3.`partyTaxGovernmentIssuedIdentifier`	Optional	Required
retailAddenda.level3.`alternateTaxAmount`	N/A	Optional Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Conditionally required if an alternate tax amount applies.
retailAddenda.level3.`lineItems[ ]`	Required	Required	Send at least one line item.
retailAddenda.level3.lineItems[ ].`lineItemDescriptionText`	Required	Required	Must contain non-space and non-zero values for US, Canada, and Europe.
retailAddenda.level3.lineItems[ ].`merchantProductIdentifier`	Required	Required	Must contain non-space and non-zero values for US, Canada, and Europe.
retailAddenda.level3.lineItems[ ].`itemComodityCode`	Required	Optional	Must contain non-space and non-zero values.
retailAddenda.level3.lineItems[ ].`lineItemUnitQuantity`	Required	Required	Must contain non-space and non-zero values for US, Canada, and Europe.
retailAddenda.level3.lineItems[ ].`lineItemUnitofMeasureCode`	Required	Required	Must contain non-space and non-zero values for US, Canada, and Europe.
retailAddenda.level3.lineItems[ ].`unitPriceAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Required Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Must contain non-space and non-zero values for Europe.
retailAddenda.level3.lineItems[ ].`taxInclusiveLineItemTotalAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Required Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Must contain non-space and non-zero values for US, Canada, and Europe.
retailAddenda.level3.lineItems[ ].`transactionDiscountAmount`	Required Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Required Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Conditionally required if a discount applies. Must contain non-space and non-zero values for Europe.
retailAddenda.level3.lineItems[ ].`purchaseTransactionDiscountPercent`	N/A	N/A
retailAddenda.level3.lineItems[ ].`lineItemDiscountTreatmentCode`	Required	N/A	Conditionally required if a discount applies.
retailAddenda.level3.lineItems[ ].`lineItemDetailCode`	Optional	N/A
retailAddenda.level3.lineItems[ ].`lineItemTaxIndicator`	N/A	Required	Must contain non-space and non-zero values for Europe.
retailAddenda.level3.lineItems[ ].`lineItemDiscountIndicator`	N/A	Required	Must contain non-space and non-zero values for Europe.
retailAddenda.level3.lineItems[ ].`lineItemTaxes[ ]`			Use the `lineItemTaxes` array to send one or more taxes.
retailAddenda.level3.lineItems[ ].lineItemTaxes[ ].`taxTypeCode`	N/A	Required	Must contain non-space and non-zero values for Canada, and Europe.
retailAddenda.level3.lineItems[ ].lineItemTaxes[ ].`lineItemTaxAmount`	Optional Maximum length of 12 If you send an amount greater than the maximum length, we truncate it from the right.	Required Maximum length of 9 If you send an amount greater than the maximum length, we truncate it from the right.	Must contain non-space and non-zero values for Canada, and Europe.
retailAddenda.level3.lineItems[ ].lineItemTaxes[ ].`taxPercent`	Required	Required	Conditionally required if `lineItemTaxAmount` contains a value. Must contain non-space and non-zero values for Canada, and Europe.

Discover and Diners Club requirements

Discover and Diners Club allow line-item data on any card. If data is received in the payment request, it is passed on to the card brands.

Line-items can repeat so that a merchant can identify all items purchased. Card brands have a maximum number of line-items that are supported.

The following table identifies the number of line-items allowed:

Maximum number of allowable line-items per card brand
Card brand	Maximum number of allowable line items
Visa and ChaseNet	998
Mastercard	998
Discover and Diners Club	98

Tip

Passing more line items than the supportable amount results in an error.
American Express uses transaction advice fields instead of line-item data.

American Express requirements

American Express uses transaction advice text to submit order or invoice data. The transactionAdviceText field is an array that repeats up to four times, with a maximum length of 40 characters per line.

Tip

Merchants must work with their American Express representative to identify a format to follow within transaction advice text. This requires a certification to American Express that confirms the proper format is followed.

Currency codes