Level 2/3 data

There are a number of benefits to supplying Level 2 or Level 3 data:

  • Lower interchange fees
  • Provides commercial customers greater insight into their spending

On this Page:

APIs

You can supply Level 2 and Level 3 data through the following APIs:

Qualification criteria

MasterCard

  • Transaction must be taxable
  • Tax must be between 0.1% and 30% of the transaction amount
  • For level 3 the transaction must use a corporate, business or purchasing card
  • For level 3 at least one line item must be included

Visa

  • Transaction must be taxable
  • Tax must be between 0.1% and 22% of the transaction amount
  • For level 3 the transaction must use a corporate or purchasing card

Data requirements

The table below defines the Level 2 and 3 data requirements for Visa and MasterCard. Level 2 and 3 data is supplied in <purchase> which is a child of <branchSpecificExtension>.

  • ✔ = required
  • - = optional
ElementLevel 2Level 3TypeSizeDescription
<purchase>
<invoiceReferenceNumber>--PCDATA1-15Your invoice number.
<customerReference>✔✔PCDATA1-17Customer reference for the purchase.
<cardAcceptorTaxId>✔✔PCDATA1-209 digits for US domiciled merchants.
<salesTax>✔✔<amount>value, exponent and currencyCodeFor non-taxable transactions set <salesTax> to 0 and <taxExempt> to true.
<discountAmount>-✔<amount>value, exponent and currencyCodeThe amount of the discount for the order.
<shippingAmount>-✔<amount>value, exponent and currencyCodeThe shipping cost for the order.
<dutyAmount>-✔<amount>value, exponent and currencyCodeThe duty on the total purchase amount for the order.
<shipFromPostalCode>--PCDATA1-10The postal code from where order is shipped.
<destinationPostalCode>--PCDATA1-10The postal code of the order destination.
<destinationCountryCode>--PCDATAISO Country CodeThe country code of the order destination.
<orderDate>--<date>dayOfMonth, month and yearThe date the order was placed.
<taxExempt>--PCDATAtrue or falseSet to true if <salesTax> is 0.
<item>

Note: You can supply a maximum of 99 line items.

<description>-✔PCDATA1-26

Note: Mandatory when <item> is supplied.

<productCode>-✔PCDATA1-12Merchant defined product code.
<commodityCode>-✔PCDATA1-12Commodity code as defined by the National Institute of Governmental Purchasing.
<quantity>-✔PCDATA1-12The number of items purchased.

Note: Must be greater than 0.

<unitCost>-✔<amount>value, exponent and currencyCodeThe price of one unit of the item purchased.
<unitOfMeasure>-✔PCDATA1-12The unit of measure of the purchased item.
<itemTotal>-✔<amount>value, exponent and currencyCodeTotal cost of the line item excluding tax.
<itemTotalWithTax>-✔<amount>value, exponent and currencyCodeTotal cost of the line item including tax.
<itemDiscountAmount>-✔<amount>value, exponent and currencyCodeItem discount amount.
<taxAmount>--<amount>value, exponent and currencyCodeTax amount for the line item.

Example requests

You can find a full XML payment submission with added Level 2/3 data below:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd" >
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <submit>
        <order orderCode="YOUR_ORDER_CODE">
            <description>YOUR DESCRIPTION</description>
            <amount value="100" currencyCode="EUR" exponent="2"/>
            <orderContent>
                <![CDATA[]]>
            </orderContent>
            <paymentDetails>
                <CARD-SSL>
                    <cardNumber>4444333322221111</cardNumber>
                    <expiryDate>
                        <date month="06" year="2019"/>
                    </expiryDate>
                    <cardHolderName>AUTHORISED</cardHolderName>
                    <cvc>666</cvc>
                    <cardAddress>
                        <address>
                            <firstName>Mr Bert</firstName>
                            <address1>Worldpay</address1>
                            <address2>270-289 The Science Park</address2>
                            <address3>Milton Road</address3>
                            <postalCode>CB4 0WE</postalCode>
                            <city>Cambridge</city>
                            <countryCode>GB</countryCode>
                        </address>
                    </cardAddress>
                </CARD-SSL>
                <session shopperIPAddress="127.0.0.1" id="ssn818495445"/>
            </paymentDetails>
            <branchSpecificExtension>
                <purchase>
                    <invoiceReferenceNumber>INV12233566</invoiceReferenceNumber>
                    <customerReference>CUST00000001</customerReference>
                    <cardAcceptorTaxId>VAT1999292</cardAcceptorTaxId>
                    <salesTax>
                        <amount value="2400" exponent="2" currencyCode="USD" />
                    </salesTax>
                    <discountAmount>
                        <amount value="0" exponent="2" currencyCode="USD" />
                    </discountAmount>
                    <shippingAmount>
                        <amount value="100" exponent="2" currencyCode="USD" />
                    </shippingAmount>
                    <dutyAmount>
                        <amount value="0" exponent="2" currencyCode="USD" />
                    </dutyAmount>
                    <shipFromPostalCode>CB40WD</shipFromPostalCode>
                    <destinationPostalCode>CB4OWD</destinationPostalCode>
                    <destinationCountryCode>GB</destinationCountryCode>
                    <orderDate>
                        <date dayOfMonth="1" month="1" year="2018" />
                    </orderDate>
                    <taxExempt>false</taxExempt>
                    <item>
                        <description>Mobile phone</description>
                        <productCode>MOB1001</productCode>
                        <commodityCode>COM10022</commodityCode>
                        <quantity>1</quantity>
                        <unitCost>
                            <amount value="12000" exponent="2" currencyCode="USD" />
                        </unitCost>
                        <unitOfMeasure>each</unitOfMeasure>
                        <itemTotal>
                            <amount value="12000" exponent="2" currencyCode="USD" />
                        </itemTotal>
                        <itemTotalWithTax>
                            <amount value="14400" exponent="2" currencyCode="USD" />
                        </itemTotalWithTax>
                        <itemDiscountAmount>
                            <amount value="100" exponent="2" currencyCode="USD" />
                        </itemDiscountAmount>
                        <taxAmount>
                            <amount value="2400" exponent="2" currencyCode="USD" />
                        </taxAmount>
                    </item>
                </purchase>
            </branchSpecificExtension>
        </order>
    </submit>
</paymentService>

You can find a full example for a capture batch request with added Level 2/3 data below:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE batchService PUBLIC "-//Worldpay//DTD Worldpay batchService v1//EN" "http://dtd.worldpay.com/batchService_v1.dtd" >
<batchService version="1.0" merchantCode="YOUR_MERCHANT_CODE" batchCode="batch57617">
    <capture orderCode="ORDER_CODE_1">
        <amount value="10000" currencyCode="USD" exponent="2" />
        <branchSpecificExtension>
            <purchase>
                <invoiceReferenceNumber>INV12233566</invoiceReferenceNumber>
                <customerReference>CUST00000001</customerReference>
                <cardAcceptorTaxId>VAT1999292</cardAcceptorTaxId>
                <salesTax>
                    <amount value="2400" exponent="2" currencyCode="USD" />
                </salesTax>
                <discountAmount>
                    <amount value="0" exponent="2" currencyCode="USD" />
                </discountAmount>
                <shippingAmount>
                    <amount value="100" exponent="2" currencyCode="USD" />
                </shippingAmount>
                <dutyAmount>
                    <amount value="0" exponent="2" currencyCode="USD" />
                </dutyAmount>
                <shipFromPostalCode>CB40WD</shipFromPostalCode>
                <destinationPostalCode>CB4OWD</destinationPostalCode>
                <destinationCountryCode>GB</destinationCountryCode>
                <orderDate>
                    <date dayOfMonth="1" month="1" year="2018" />
                </orderDate>
                <taxExempt>false</taxExempt>
                <item>
                    <description>Mobile phone</description>
                    <productCode>MOB1001</productCode>
                    <commodityCode>COM10022</commodityCode>
                    <quantity>1</quantity>
                    <unitCost>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </unitCost>
                    <unitOfMeasure>each</unitOfMeasure>
                    <itemTotal>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </itemTotal>
                    <itemTotalWithTax>
                        <amount value="14400" exponent="2" currencyCode="USD" />
                    </itemTotalWithTax>
                    <itemDiscountAmount>
                        <amount value="100" exponent="2" currencyCode="USD" />
                    </itemDiscountAmount>
                    <taxAmount>
                        <amount value="2400" exponent="2" currencyCode="USD" />
                    </taxAmount>
                </item>
                <item>
                    <description>Camera</description>
                    <productCode>CAM0001</productCode>
                    <commodityCode>COM100222</commodityCode>
                    <quantity>1</quantity>
                    <unitCost>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </unitCost>
                    <unitOfMeasure>each</unitOfMeasure>
                    <itemTotal>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </itemTotal>
                    <itemTotalWithTax>
                        <amount value="14400" exponent="2" currencyCode="USD" />
                    </itemTotalWithTax>
                    <itemDiscountAmount>
                        <amount value="100" exponent="2" currencyCode="USD" />
                    </itemDiscountAmount>
                    <taxAmount>
                        <amount value="2400" exponent="2" currencyCode="USD" />
                    </taxAmount>
                </item>
            </purchase>
        </branchSpecificExtension>
    </capture>
    <capture orderCode="ORDER_CODE_2">
        <amount value="10000" currencyCode="USD" exponent="2" />
        <branchSpecificExtension>
            <purchase>
                <invoiceReferenceNumber>INV12233566</invoiceReferenceNumber>
                <customerReference>CUST00000001</customerReference>
                <cardAcceptorTaxId>VAT1999292</cardAcceptorTaxId>
                <salesTax>
                    <amount value="2400" exponent="2" currencyCode="USD" />
                </salesTax>
                <discountAmount>
                    <amount value="0" exponent="2" currencyCode="USD" />
                </discountAmount>
                <shippingAmount>
                    <amount value="100" exponent="2" currencyCode="USD" />
                </shippingAmount>
                <dutyAmount>
                    <amount value="0" exponent="2" currencyCode="USD" />
                </dutyAmount>
                <shipFromPostalCode>CB40WD</shipFromPostalCode>
                <destinationPostalCode>CB4OWD</destinationPostalCode>
                <destinationCountryCode>GB</destinationCountryCode>
                <orderDate>
                    <date dayOfMonth="1" month="1" year="2018" />
                </orderDate>
                <taxExempt>false</taxExempt>
                <item>
                    <description>Mobile phone</description>
                    <productCode>MOB1001</productCode>
                    <commodityCode>COM10022</commodityCode>
                    <quantity>1</quantity>
                    <unitCost>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </unitCost>
                    <unitOfMeasure>each</unitOfMeasure>
                    <itemTotal>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </itemTotal>
                    <itemTotalWithTax>
                        <amount value="14400" exponent="2" currencyCode="USD" />
                    </itemTotalWithTax>
                    <itemDiscountAmount>
                        <amount value="100" exponent="2" currencyCode="USD" />
                    </itemDiscountAmount>
                    <taxAmount>
                        <amount value="2400" exponent="2" currencyCode="USD" />
                    </taxAmount>
                </item>
                <item>
                    <description>Camera</description>
                    <productCode>CAM0001</productCode>
                    <commodityCode>COM100222</commodityCode>
                    <quantity>1</quantity>
                    <unitCost>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </unitCost>
                    <unitOfMeasure>each</unitOfMeasure>
                    <itemTotal>
                        <amount value="12000" exponent="2" currencyCode="USD" />
                    </itemTotal>
                    <itemTotalWithTax>
                        <amount value="14400" exponent="2" currencyCode="USD" />
                    </itemTotalWithTax>
                    <itemDiscountAmount>
                        <amount value="100" exponent="2" currencyCode="USD" />
                    </itemDiscountAmount>
                    <taxAmount>
                        <amount value="2400" exponent="2" currencyCode="USD" />
                    </taxAmount>
                </item>
            </purchase>
        </branchSpecificExtension>
    </capture>
</batchService>

Errors

All errors related to Level 2/3 data are reported under error code 11.

Error codeDescription
11The element invoiceReferenceNumber must be between 1-15 characters : 'value supplied'
11The element customerReference must be between 1-17 characters : 'value supplied'
11The element cardAcceptorTaxId must be between 1-20 characters : 'value supplied'
11The element shipFromPostalCode must be between 1-10 characters : 'value supplied'
11The element destinationPostalCode must be between 1-10 characters : 'value supplied'
11The element destinationCountryCode does not contain a recognized country code : 'value supplied'
11Expecting either true of false, but received : 'value supplied'
11The element description is required
11The element description must be between 1-26 characters : 'value supplied'
11The element productCode must be between 1-12 characters : 'value supplied'
11The element commodityCode must be between 1-12 characters : 'value supplied'
11The element quantity is not an integer number : 'value supplied'
11The element quantity must be between 1-12 digits : 'value supplied'
11The element unitOfMeasure must be between 1-12 characters : 'value supplied'
11salesTax must be supplied when cardAcceptorTaxId is supplied

Feedback or bugs to report?

Ask our developer community.

Get support

STAY CONNECTED

©2020 Worldpay, LLC and/or its affiliates. All rights reserved.

Within this page
APIsQualification criteriaData requirementsExample requestsErrors

​

Search our documentation, API references and articles.