- Home
- All APIs
- WPG guide
- US and Canada domestic acquiring
- Level 2/3 data
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
APIs
You can supply Level 2 and Level 3 data through the following APIs:
Direct XML (AUTHORISE and SALE)HPP - Capture or Refund
batch request - Capture or Refund
order modification
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
Element | Level 2 | Level 3 | Type | Size | Description |
---|---|---|---|---|---|
<purchase> | |||||
<invoiceReferenceNumber> | - | - | PCDATA | 1-15 | Your invoice number. |
<customerReference> | ✔ | ✔ | PCDATA | 1-17 | Customer reference for the purchase. |
<cardAcceptorTaxId> | ✔ | ✔ | PCDATA | 1-20 | 9 digits for US domiciled merchants. |
<salesTax> | ✔ | ✔ | <amount> | value, exponent and currencyCode | For non-taxable transactions set <salesTax> to 0 and <taxExempt> to true. |
<discountAmount> | - | ✔ | <amount> | value, exponent and currencyCode | The amount of the discount for the order. |
<shippingAmount> | - | ✔ | <amount> | value, exponent and currencyCode | The shipping cost for the order. |
<dutyAmount> | - | ✔ | <amount> | value, exponent and currencyCode | The duty on the total purchase amount for the order. |
<shipFromPostalCode> | - | - | PCDATA | 1-10 | The postal code from where order is shipped. |
<destinationPostalCode> | - | - | PCDATA | 1-10 | The postal code of the order destination. |
<destinationCountryCode> | - | - | PCDATA | The country code of the order destination. | |
<orderDate> | - | - | <date> | dayOfMonth, month and year | The date the order was placed. |
<taxExempt> | - | - | PCDATA | true or false | Set to true if <salesTax> is 0. |
<item> Note: You can supply a maximum of 99 line items. | |||||
<description> | - | ✔ | PCDATA | 1-26 | Note: Mandatory when |
<productCode> | - | ✔ | PCDATA | 1-12 | Merchant defined product code. |
<commodityCode> | - | ✔ | PCDATA | 1-12 | Commodity code as defined by the National Institute of Governmental Purchasing. |
<quantity> | - | ✔ | PCDATA | 1-12 | The number of items purchased. Note: Must be greater than 0. |
<unitCost> | - | ✔ | <amount> | value, exponent and currencyCode | The price of one unit of the item purchased. |
<unitOfMeasure> | - | ✔ | PCDATA | 1-12 | The unit of measure of the purchased item. |
<itemTotal> | - | ✔ | <amount> | value, exponent and currencyCode | Total cost of the line item excluding tax. |
<itemTotalWithTax> | - | ✔ | <amount> | value, exponent and currencyCode | Total cost of the line item including tax. |
<itemDiscountAmount> | - | ✔ | <amount> | value, exponent and currencyCode | Item discount amount. |
<taxAmount> | - | - | <amount> | value, exponent and currencyCode | Tax 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>
<?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>
<?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 code | Description |
---|---|
11 | The element invoiceReferenceNumber must be between 1-15 characters : 'value supplied' |
11 | The element customerReference must be between 1-17 characters : 'value supplied' |
11 | The element cardAcceptorTaxId must be between 1-20 characters : 'value supplied' |
11 | The element shipFromPostalCode must be between 1-10 characters : 'value supplied' |
11 | The element destinationPostalCode must be between 1-10 characters : 'value supplied' |
11 | The element destinationCountryCode does not contain a recognized country code : 'value supplied' |
11 | Expecting either true of false, but received : 'value supplied' |
11 | The element description is required |
11 | The element description must be between 1-26 characters : 'value supplied' |
11 | The element productCode must be between 1-12 characters : 'value supplied' |
11 | The element commodityCode must be between 1-12 characters : 'value supplied' |
11 | The element quantity is not an integer number : 'value supplied' |
11 | The element quantity must be between 1-12 digits : 'value supplied' |
11 | The element unitOfMeasure must be between 1-12 characters : 'value supplied' |
11 | salesTax must be supplied when cardAcceptorTaxId is supplied |