Overview
This page describes how to send optional data with your settle request to receive a better interchange rate per transaction. Nuvei supports level 2&3 by accepting and passing additional enhanced data fields for business, corporate cards, etc. This data is supported for online payments.
To settle transaction with level 2&3 processing data after a successful Auth transaction, send a /settleTransaction request and include the addendums.l23processingData class with the parameters described in the following table.
General Notes
- Level 2&3 data is supported only by REST API integration.
- Level 2&3 data is supported only for the Auth-Settle flow.
- Level 2&3 templates are not part of the current functionally. To use level 2&3, you need to provide data in all relevant fields.
- Level 2&3 qualification:
Gaming and industries below do not qualify for level 2&3 benefit (this is subject to evaluation with individual merchants):- Restaurants/Fast-Food
- Airlines/Cruise Lines
- Direct Marketing
- Passenger Transport
- Hotels/Lodging
- Car Rentals
- Merchants must have cards that qualify for level 2&3.
Level 2&3 Data Parameters
l23processingData
This class contains processing data for level 2 and level 3.
| Parameter | Description | Example |
|---|---|---|
| taxIndicator (String, 1) | Indicates if local tax is included or not. Values: 0 = Tax not included 1 = State or Provincial Tax included 2 = Transaction is not subject to tax. This field must contain 1 if the Local Tax field is not zeros | 2 |
| customerCode (string, 25) | A reference number or code that identifies the customer or consumer. | 5807704 |
| merchantVATRegNum (String, 20) | Contains the merchant’s VAT registration number or Single Business Reference Number (SBRN). | 78875627 |
| customerVATRegNum (String, 13) | Contains the customer’s value-added tax registration number. | 291826 |
| summaryCommodityCode (String, 4) | Contains the national standard coding structure for the description of goods. | 7907 |
| destinationZip (String, 10) | Postal code of the destination. | 31820 |
| shipFromZip (String, 10) | Postal code of the location being shipped from. | 36877 |
| destinationCountryCode (String, 3) | Country code of the destination. | US |
| uniqueVATReference (String, 15) | Value added tax invoice reference number. | 661487902584ALM |
| orderDate (String, 6) | Date the order was taken. The entry should be a six-digit numeric, in the format YYMMDD. | 230622 |
| vatOrTaxRate (String, 4) | Tax rate applied to freight and shipping. | 0.05 |
| lineItemCount (String,5) | Number of Line Item Details sent for the transaction. Currently limited to 999 | Variable - depends on # of detail items |
| lineItemCountTax (String,3) | Number of Canadian Tax Line Item Details sent for the transaction. Currently linited to 6 | Variable - depends on # of canadian tax detail items |
l23processingData.taxItems
This is an array of processing data describing tax items for transactions processed in Canada.
| Parameter | Description | Example |
|---|---|---|
| taxAmountIndicator (String, 1) | Value used to reflect additional tax capture and reporting. | Y |
| taxAmount (String, 12) | Detailed Tax Amount on the transaction | 0.024 |
| taxRate (String, 5) | Tax Rate applied to transaction | 0.0012 |
| taxRateExponent (String, 1) | Indicates decimal place of tax rate applied. | 2 |
| taxTypeApplied (String, 4) | Indicator used to further define tax categories | 72TP |
| taxTypeIdentifier (String, 2) | Indicates type of tax collected, in relation to specific tax amount. | 00 |
l23processingData.Items
This is an array of processing data describing line items.
| Parameter | Description | Example | |
|---|---|---|---|
| commodityCode (String, 12) | Code used to categorize purchase item. | 7907 | |
| description (String, 35) | Text field describing the item purchased. | Garden Supplies | |
| productCode (String, 12) | Identifies product being purchased | ZC Gen Merch | |
| quantity (String, 12) | The number of units of the product being purchased | 5 | |
| unitMeasure (String, 12) | Code indicating unit of measure (gallons, etc.). | Each | |
| price (String, 12) | Cost of fuel per unit of measure (for example, dollars per gallon). | 4.00 | |
| vatOrTaxAmount (String, 12) | Any value-added tax or other sales tax amount. | 0.05 | |
| vatOrTaxRate (String, 4) | The percentage of the sales tax applied-please enter numbers only, use the | 0.025 | |
| totalAmount (String, 12) | Total of line items. | 20.00 | |
| discountRate (String, 5) | Discount Rate applicable to amount, please use numbers only, use the 'discountRateExponent' to dtermine the postion of the decimal point | 0.015 | |
| discount (String, 12) | Any discount on the purchase, per line item. | 0.30 | |
| taxType (String, 4) | Indicator used to further define tax categories-this is a numeric value | 1111 | |
| quantityExponentIndicator (String, 1) | Indicates decimal place of quantity | 2 | |
| discountRateExponent (String, 1) | Indicates decimal place of Discount Rate | 2 | |
| discountTreatmentCode (String, 1) | Indicates how the merchant is managing discounts. 0 = no invoice level discount provided 1 = tax was calculated on the post-discount invoice total 2 = tax was calculated on the pre-discount invoice total | 2 | |
| creditIndicator (String, 1) | Indicates whether the net of Extended Item Amount (net of discount, taxes, price) is a Debit or a Credit. | D | |
| extendedAmount (String, 9) | Represents a calculation of the individual item amount multiplied by quantity. | 1 |
l23processingData.amountDetails
This class contains processing data related to amounts.
| Parameter | Description | Example |
|---|---|---|
| nationalTaxAmount (String, 12) | Indicates the amount of National Tax included in the transaction amount. | 0.12 |
| totalDiscount (String, 12) | Amount of Discount applied. | 0.3 |
| totalShipping (String, 12) | Amount of freight or shipping. | 5.55 |
| dutyAmount (String, 12) | Amount of duty taxes. | 0.16 |
| vatOrTaxAmount (String, 12) | VAT/Tax Amount (Freight Shipping) | 0.88 |
| taxAmount (String, 12) | Indicates the amount of state or provinical tax included in the transaction amount. This amount must be expressed in the same currency as thetransaction amount. This field must be numeric. It may contain zeros. This field contains two implied decimal places. | 0.22 |
Example Level 2&3 Settle Request
{
"merchantId":"<your merchantId>",
"merchantSiteId":"<your merchantSiteId>",
"clientRequestId":"<unique request ID in merchant system>",
"clientUniqueId":"<unique transaction ID in merchant system>",
"amount":"200",
"currency":"USD",
"relatedTransactionId":"<transactionId of the original Auth transaction>",
"authCode":"<returned in the response from the original payment request>",
"addendums":{
"l23processingData":{
"taxIndicator":"1",
"customerCode":"5807704",
"merchantVATRegNum":"78875627",
"customerVATRegNum":"291826",
"summaryCommodityCode":"7907",
"destinationZip":"31820",
"shipFromZip":"36877",
"destinationCountryCode":"US",
"uniqueVATReference":"661487902584ALM",
"orderDate":"230622",
"vatOrTaxRate":"0.05",
"lineItemCount":"1",
"lineItemCountTax":"1",
"taxItems":[
{
"taxAmountIndicator":"Y",
"taxAmount":"0.024",
"taxRate":"0.0012",
"taxRateExponent":"2",
"taxTypeApplied":"72TR",
"taxTypeIdentifier":"00"
}
],
"items":[
{
"commodityCode":"7907",
"description":"Garden Supplies",
"productCode":"ZC Gen Merch",
"quantity":"5",
"unitMeasure":"Each",
"price":"4.00",
"vatOrTaxAmount":"0.05",
"vatOrTaxRate":"0.025",
"totalAmount":"20.00",
"discountRate":"0.015",
"discount":"0.30",
"taxType":"1111",
"quantityExponentIndicator":"2",
"discountRateExponent":"2",
"discountTreatmentCode":"2",
"creditIndicator":"D",
"extendedAmount":"1.00"
}
],
"amountDetails":{
"nationalTaxAmount":"0.12",
"totalDiscount":"0.30",
"totalShipping":"5.55",
"dutyAmount":"0.16",
"vatOrTaxAmount":"0.88",
"taxAmount":"0.22"
}
}
},
"timeStamp":"<YYYYMMDDHHmmss>",
"checksum":"<calculated checksum>"
}
Last modified September 2024