Level II/III Data for the First Data Acquirer
This page contains additional integration details to that provided in the standard Level II/III integration guide, and is specific to the First Data acquirer.
The gateway will submit Level II/III data as provided by you to the First Data acquirer only if you provide at least the following fields:
- Shipping Destination ZIP/Post Code (
shipping.address.postcodeZip) - Shipping Origin ZIP/Post Code (
shipping.origin.postcodeZip, if not provided, the value as configured on your merchant profile may be submitted to the acquirer.) - Item level transaction data
- item quantity (
transaction.item[n].quantity) - item product code (
transaction.item[n].name) - item unit of measure (
transaction.item[n].unitOfMeasure) - item commodity code (
transaction.item[n].detail.commodityCodeortransaction.item[n].detail.acquirerCustom ={"XD34_4":"<non-integer item commodity code>"})
- item quantity (
- your tax registration ID (
order.taxRegistrationId(highly recommended to achieve best interchange rates))
Level II Data
To provide the following Level II data in your transaction request, use the corresponding order-level and/or transaction-level API fields with the integration details as shown in the "Field Value" column in the table below.
| Level II Data | Order-level Field | Transaction-level Field | Field Value |
|---|---|---|---|
| Merchant's Purchase Reference | order.referenceIf not provided, the gateway uses the value as provided in order.id (mandatory field).
|
- |
This field is mandatory for Mastercard cards (up to 17 characters) but optional for Visa cards (up to 25 characters). |
| Customer/Cardholder Reference Number | order.customerReference |
- |
This field is mandatory for Mastercard and Visa cards. |
| Invoice Number | order.invoiceNumber |
- |
This field is mandatory for Mastercard cards but optional for Visa cards. |
| Shipping and Handling Amount | order.shippingAndHandlingAmount |
transaction.shippingAndHandlingAmount |
If you provide a Shipping and Handling amount you may also need to provide the:
|
| Tax Amount | order.taxAmount |
transaction.taxAmount |
This field is mandatory for Mastercard cards but optional for Visa cards. |
| Duty Amount | From the API version 67 onwards, use the following:order.dutyAmountFor API versions lower than 67, use the following: order.tax[n].type=DUTYorder.tax[n].amount |
From the API version 67 onwards, use the following:transaction.dutyAmountFor API versions lower than 67, use the following: transaction.tax[n].type=DUTYtransaction.tax[n].amount |
- |
Level III Data
To provide the following Level III data in your transaction request, use the corresponding order-level (from the order.item[n] parameter group) and/or transaction-level (from the transaction.item[n] parameter group) API fields with the integration details as shown in the "Field Value" column in the table below.
| Level III Data | Order-level Field | Transaction-level Field | Field Value |
|---|---|---|---|
| Item Unit of Measure | order.item[n].unitOfMeasure |
transaction.item[n].unitOfMeasure |
You must provide the correct enumeration value as required by your acquirer, see Item Unit of Measure Enumeration Values. |
| Item Tax Type | order.item[n].detail.unitTaxType |
transaction.item[n].detail.unitTaxType |
You must provide the correct enumeration value for the tax type code as required by your acquirer, see Tax Type Enumeration Values. |
| Item Tax Type [n] | order.item[n].detail.tax[m].type |
transaction.item[n].detail.tax[m].type |
Only the details provided for the first element in the list (transaction.item[n].detail.unitTax[1].*) will be submitted to the acquirer. You must provide the correct enumeration value for the tax type code as required by your acquirer, see Tax Type Enumeration Values. |
| Item Commodity Code | order.item[n].detail.acquirerCustom
={"XD34_4":"<non-integer item commodity code>"} |
transaction.item[n].detail.acquirerCustom
={"XD34_4":"<non-integer item commodity code>"} |
Use this field if you want to submit a non-integer commodity code for a line item. To submit a numeric commodity code for a line item, you can submit in fields order.item[n].detail.commodityCode or transaction.item[n].detail.commodityCode. |
Tax Type Enumeration Values
Provide the correct tax type enumeration value in fields order.item[n].detail.unitTaxType and/or transaction.item[n].detail.unitTaxType
| Tax Type Code | Description |
|---|---|
| 00 | Unknown |
| 01 | Federal/National Sales Tax |
| 02 | State Sales Tax |
| 03 | City Sales Tax |
| 04 | Local Sales Tax |
| 05 | Municipal Sales Tax |
| 06 | Other Tax |
| 10 | Value Added Tax (VAT) |
| 11 | Goods and Services Tax (GST) |
| 12 | Provincial Sales Tax |
| 20 | Room Tax |
| 21 | Occupancy Tax |
| 22 | Energy Tax |
Item Unit of Measure Enumeration Values
Provide the correct unit of measure enumeration value for line items in fields order.item[n].unitOfMeasure and/or transaction.item[n].unitOfMeasure
| Item Unit of Measure Code | Description |
|---|---|
| ACR | Acre (4840 yd2) |
| ASM | Alcoholic strength by mass |
| ASV | Alcoholic strength by volume |
| AMP | Ampere |
| AMH | Ampere-hour (3,6 kC) |
| ARE | Are (100 m2) |
| BAR | Bar |
| BLL | Barrel (petroleum) (158,987 dm3) |
| BFT | Board foot |
| BQL | Becquerel |
| BIL | Billion EUR |
| MLD | Billion US |
| BX | ox |
| BHP | Brake horse power (245,7 watts) |
| BTU | British thermal unit (1,055 kilojoules) |
| BUA | Bushel (35,2391 dm3) |
| BUI | Bushel (36,36874 dm3) |
| CDL | Candela |
| CCT | Carrying capacity in metric tons |
| CS | ase |
| CNT | Cental GB (45,359237 kg) |
| CGM | Centigram |
| CLT | Centilitre |
| CMT | Centimetre |
| DTN | Centner, metric (100 kg) (syn.: decitonne) |
| WCD | Cord (3,63 m3) |
| COU | Coulomb |
| CKG | Coulomb per kilogram |
| DMQ | Cubic decimetre |
| FTQ | Cubic foot |
| INQ | Cubic inch |
| MTQ | Cubic metre |
| MQH | Cubic metre per hour |
| MQS | Cubic metre per second |
| MMQ | Cubic millimetre |
| YDQ | Cubic yard |
| CUR | Curie |
| DAY | Day |
| DEC | Decade (ten years) |
| DAA | Decare |
| DLT | Decilitre |
| DMT | Decimetre |
| CEL | Degree Celsius |
| FAH | Degree Fahrenheit |
| KEL | Degree Kelvin: same as Kelvin |
| DPT | Displacement tonnage |
| DZN | Dozen |
| DZP | Dozen packs |
| DZR | Dozen pairs |
| DPC | Dozen pieces |
| DRL | Dozen rolls |
| DRM | Drachm GB (3,887935 g) |
| DRI | Dram GB (1,771745 g) |
| DRA | Dram US (3,887935 g) |
| BLD | Dry barrel (115,627 dm3) |
| GLD | Dry gallon (4,404884 dm3) |
| PTD | Dry pint (0,55061 dm3) |
| QTD | Dry quart (1,101221 dm3) |
| EA or EAC | Each |
| FAR | Farad |
| OZI | Fluid ounce (28,413 cm3) |
| OZA | Fluid ounce (29,5735 cm3) |
| FOT | Foot (0,3048 m) |
| GLI | Gallon (4,546092 dm3) |
| GBQ | Gigabecquerel |
| GWH | Gigawatt-hour (1 million kW/h) |
| GII | Gill (0,142065 dm3) |
| GIA | Gill (11,8294 cm3) |
| GRN | Grain GB, US (64,798910 mg) |
| GRM | Gram |
| GFI | Gram of fissile isotopes |
| GGR | Great gross (12 gross) |
| GRO | Gross |
| GRT | Gross (register) ton |
| SAN | Half year (six months) |
| HAR | Hectare |
| HBA | Hectobar |
| HGM | Hectogram |
| DTH | Hectokilogram |
| HLT | Hectolitre |
| HPA | Hectolitre of pure alcohol |
| HMT | Hectometre |
| HTZ | Hertz |
| HUR | Hour |
| CEN | Hundred |
| BHX | Hundred boxes |
| HIU | Hundred international units |
| CLF | Hundred leaves |
| CNP | Hundred packs |
| CWA | Hundredweight US (45,3592 kg) |
| INH | Inch (25,4 mm) |
| ITM | Item |
| JOU | Joule |
| KEL | Kelvin |
| KBA | Kilobar |
| KGM | Kilogram |
| KPH | Kilogram of caustic potash |
| KSH | Kilogram of caustic soda |
| KNS | Kilogram of named substance |
| KNI | Kilogram of nitrogen |
| KPP | Kilogram of phosphonic anhydride |
| KPP | Kilogram of phosphorus pentoxide |
| KPH | Kilogram of potassium hydroxide |
| KPO | Kilogram of potassium oxide |
| KSD | Kilogram of substance 90 per cent dry |
| KUR | Kilogram of uranium |
| KMQ | Kilogram per cubic meter |
| KGS | Kilogram per second |
| KHZ | Kilohertz |
| KJO | Kilogoule |
| KMT | Kilometre |
| KMH | Kilometre per hour |
| KPA | Kilopascal |
| KTN | Kilotonne |
| KVR | Kilovar |
| KVT | Kilovolt |
| KVA | Kilovolt-ampere |
| KWT | Kilowatt |
| KWH | Kilowatt-hour |
| KNT | Knot (1 nautical mile per hour) |
| LEF | Leaf |
| GLL | Liquid gallon (3,7854l dm3) |
| PTL | Liquid pint (0,473176 dm3) |
| QTL | Liquid quart (0,946353 dm3) |
| LTR | Liter (1 dm3) |
| LPA | Liter of pure alcohol |
| LTN | Long ton GB, US (1,0160469 t) |
| LUM | Lumen |
| LUX | Lux |
| MHZ | Megahertz |
| MAL | Megalitre |
| MAM | Megametre |
| MPA | Megapascal |
| MVA | Megavolt-ampere (1000 KVA) |
| MAW | Megawatt |
| MWH | Megawatt-hour (100 kW/h) |
| MTR | Metre |
| MTS | Metre per second |
| MSK | Metre per second squared |
| CTM | Metric carat (200 mg = 2.10-4 kg) |
| TNE | Metric ton (1000 kg) |
| MBR | Millibar |
| MCU | Millicurie |
| MGM | Milligram |
| MI.T | Millilitre |
| MMT | Millimetre |
| MIO | Million |
| HMQ | Million cubic metres |
| MIU | Million international units |
| MIN | Minute |
| MON | Month |
| NMI | Nautical mile (1852 m) |
| NTT | Net (register) ton |
| NEW | Newton |
| NMB | Number |
| NAR | Number of articles |
| NBB | Number of bobbins |
| NCL | Number of cells |
| NIU | Number of international units |
| NMP | Number of packs |
| NMR | Number of pairs |
| NPL | Number of parcels |
| NPT | Number of parts |
| NRL | Number of rolls |
| OHM | Ohm |
| ONZ | Ounce GB, US (28,349523 g) |
| APZ | Ounce GB, US (31,10348 g) (syn: Troy ounce) |
| PK | Package |
| PAL | Pascal |
| DWT | Pennyweight GB, US (1,555174 g) |
| PCE | Piece |
| PCB | Piece |
| PSC | Piece |
| PTI | Pint (0,568262 dm3) |
| LBR | Pound GB, US (0,45359237 kg) |
| PGL | Proof gallon |
| LBS | Pounds |
| QTI | Quart (1,136523 dm3) |
| QAN | Quarter (of a year) |
| QTR | Quarter, GB (12,700586 kg) |
| RPM | Revolution per minute |
| RPS | Revolution per second |
| SCO | Score |
| SCR | Scruple GB, US (1,295982 g) |
| SEC | Second |
| SET | Set |
| SHT | Shipping ton |
| SST | Short standard (7200 matches) |
| SIE | Siemens |
| CMK | Square centimetre |
| DMK | Square decimetre |
| FTK | Square foot |
| INK | Square inch |
| KMK | Square kilometre |
| MTK | Square metre |
| MIK | Square mile |
| MMK | Square millimetre |
| YDK | Square yard |
| WSD | Standard |
| ATM | Standard atmosphere (101325 Pa) |
| SMI | (Statute) mile (1609,344 m) |
| STI | Stone GB (6,350293 kg) |
| ATT | Technical atmosphere (98066,5 Pa) |
| DAD | Ten days |
| TPR | Ten pairs |
| MIL | Thousand |
| TAH | Thousand ampere-hour |
| MBF | Thousand board feet (2,36 m3) |
| TQD | Thousand cubic metres per day |
| MBE | Thousand standard brick equivalent |
| TSH | Ton of steam per hour |
| TSD | Tonne of substance 90 per cent dry |
| TRL | Trillion EUR |
| APZ | Troy ounce |
| ST | Unknown unit of Measure |
| VLT | Volt |
| WTT | Watt |
| WHR | Watt-hour |
| WEB | Weber |
| WEE | Week |