Level 2 and Level 3 data processing on the custom payment gateway integration

Last updated
Save as PDF

The Universal Payment Connector (UPC) service provides you the flexibility to submit Level 2 and Level 3 data. This information might result in lower interchange rates on eligible commercial, corporate, and purchasing cards. You need to manage the additional Level 2 and Level 3 parameters to evaluate whether the gateway can accept them and decide whether to include them in the request.

This article provides instructions on enabling the support for submitting Level 2 and Level 3 data through the UPC Token Gateway integration. It also describes the field mappings and constraints.

Prerequisites

In Zuora, configure the following custom fields:

On the Product Rate Plan Charge object, configure the following custom fields:
- CommodityCode
- ProductCode
On the Account object, configure the ShipFromPostalCode custom field.

When configuring a payment gateway instance, the API names (without "__c") of these custom fields are required to enable Level 2 and Level 3 data processing.

For more information about custom fields, see Custom object definitions.

Enable Level 2 and Level 3 data submission

To enable the support for sending Level 2 card data, Level 3 card data, or both through the UPC Token Gateway instance, configure the following settings on the configuration page of the UPC Token Gateway instance:

Enable Level 2 Processing: If you want to enable Level 2 card data processing, select this checkbox.
Enable Level 3 Processing: If you want to enable Level 3 card data processing, select this checkbox.
ShipFrom Postal Code Custom Field API Name: To send the shipFromPostalCode field to the gateway, enter the API name of the ShipFromPostalCode custom field without the __c suffix.
ProductCode Custom Field API Name: To send the ProductCode field to the gateway, enter the API name of the ProductCode custom field without the __c suffix.
CommodityCode Custom Field API Name: To send the CommodityCode field to the gateway, enter the API name of the CommodityCode custom field without the __c suffix.

For more information about configuring the UPC Token Gateway instance, see Set up a custom payment gateway.

Field mappings

Destination information

Level 2 field	Zuora field	Description
shipToPostalCode	SoldToContactZip	The postal code of the destination address for shipment. The maximum length is 10 characters.
shipToCountryCode	SoldToContactCountry	The country code for the destination address. The maximum length is 3 characters.
shipToStateProvinceCode	SoldToContactState	The state or province code of the destination address.
shipToCity	SoldToContactCity	The city of the destination address.
shipToAddressLine1	SoldToContactAddress1	The address line 1 of the destination address.
shipToAddressLine2	SoldToContactAddress2	The address line 2 of the destination address.

Ship-From address

Level 2 field Zuora field Description

Level 2 field	Zuora field	Description
shipFromPostalCode	The `ShipFromPostalCode` custom field on the `Account` object	Postal code of the “ship-from” address. The maximum length is 10.

shipFromPostalCode

The ShipFromPostalCode custom field on the Account object

Postal code of the “ship-from” address.

The maximum length is 10.

Amount information

Level 2 and Level 3 field		Zuora field	Description
Level 2	totalTaxAmount	The `taxAmount` field on the `InvoiceItem` object	Total tax amount applied to the transaction.
Level 3	freightAmount		The shipping or freight cost associated with the transaction. This field is set to 0 by default.
	dutyAmount		The duty charges for the transaction, if applicable. This field is set to 0 by default.
	discountAmount		Discount for the transaction, if applicable. It is calculated using the following formula: SUM{ Discount * (ApplyAmount/InvoiceAmount) }

Line item details

A maximum of 1,000 line items is allowed, with each line item containing the following fields:

Level 3 field	Zuora field	Description
itemDetailLine[].description:	The `description` field on the `InvoiceItem` object	Description of the item.
itemDetailLine[].productCode:	The `ProductCode` custom field on the `ProductRatePlanCharge` object	Code identifying the product such as SKU or UPC. The maximum length is 12 characters.
itemDetailLine[].quantity	The `quantity` field on the `InvoiceItem` object	Quantity of the product being purchased. The maximum length is 4.
itemDetailLine[].unitOfMeasure	The `unitOfMeasure` field on the `InvoiceItem` object	Measurement unit for the item such as PCS or KG. The maximum length is 3.
itemDetailLine[].taxAmount:		The total tax amount applied to the individual line item. It is calculated based on the item's price and tax rate, rounded to 2 decimal places.
itemDetailLine[].taxRate		The tax rate applied to the line item. It is expressed as a percentage such as 5.00 for 5% tax. It is calculated using the following formula: Invoice detail’s tax_amount/Invoice detail’s amount_without_tax
itemDetailLine[].totalAmount	Zuora combines the values from the `amount_without_tax` and `tax_amount` fields on the `InvoiceItem` object and considers it as `totalAmount`.	The total amount for the line item, including tax. The maximum length is 12.
itemDetailLine[].discountAmount	The `discount` field on the `InvoiceItem` object	The discount applied to the line item, rounded to 2 decimal places. This field is passed to the gateway when the credit card type is not American Express.
itemDetailLine[].commodityCode	The `CommodityCode` custom field on the `ProductRatePlanCharge` object	Commodity code of the item, if applicable. The maximum length is 12 characters.
itemDetailLine[].unitPrice	The `unitPrice` field on the `InvoiceItem` object	The price per unit of the item, rounded to 2 decimal places.
itemDetailLine[itemNr].grossNetIndicator		Indicates whether the item's total amount includes tax (Gross) or excludes tax (Net). Possible values: "G" for Gross (tax included in the amount) "N" for Net (tax not included in the amount) It is determined using the following formula: if(tax_amount==0){return "N"} else if(tax_amount!=0) {return "Y"}
itemDetailLine[itemNr].discountIndicator		Specifies if a discount is applied to the item. Possible values: "Y" for Yes (discount applied) "N" for No (no discount applied) It is determined using the following condition: if(discount_amount==0){return "N"} else if(discount_amount!=0) {return "Y"}
itemDetailLine[itemNr].discountRate		The discount rate applied to the item, represented as a percentage. Format: Decimal such as 10.00 for a 10% discount. It is calculated using the following formula: Invoice detail’s discount_amount/Invoice detail’s amount_without_tax
itemDetailLine[itemNr].taxCode	InvoiceDetailTaxCodeName	A code representing the type of tax applied to the item such as VAT, GST, or ST.

Order information

Level 3 field	Description
orderDate	Date the order was placed.

Example of JSON structure for UPC Level 2 and Level 3 data

{
    "shipToCity": "Test City",
    "shipToAddressLine1": "Test Address Line 1",
    "shipToAddressLine2": "Test Address Line 2",
    "shipToStateProvinceCode": "California",
    "shipToPostalCode": "95016",
    "shipToCountryCode": "USA",
    "shipFromPostalCode": "1234567",
    "totalTaxAmount": "16.936803668",
    "lineItems": [
        {
            "quantity": "10",
            "unitPrice": "1000",
            "totalAmount": 11095,
            "discountAmount": "0",
            "unitOfMeasure": "Eac",
            "productCode": "TestPCode",
            "commodityCode": "SampleCCode",
            "taxAmount": "1095",
            "taxRate": "0.11",
            "discountIndicator": "N",
            "discountRate": "0",
            "taxCode": "Test",
            "grossNetIndicator": "Y"
        },
        {
            "quantity": "1",
            "unitPrice": "1000",
            "totalAmount": 1000,
            "discountAmount": "100",
            "productCode": "TestPCode",
            "commodityCode": "SampleCCode",
            "description": "Test Rate Plan Description",
            "taxAmount": "0",
            "taxRate": "0",
            "discountIndicator": "Y",
            "discountRate": "0.1",
            "taxCode": "null",
            "grossNetIndicator": "N"
        }
    ],
    "freightAmount": 0,
    "discountAmount": "0.8336807",
    "orderDate": "211124",
    "dutyAmount": 0
}