PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Level 2 and Level 3 Transaction Processing

Overview

Level 2 and Level 3 Data are crucial for enhancing transaction transparency, improving tax and compliance reporting, and qualifying for reduced interchange fees in B2B and government procurement. By providing detailed information on each purchase, these data levels enable accurate tracking, itemization, and processing, making them essential for both operational efficiency and cost savings in complex transactions.

🚧

Note

This data is optional for the PayConex™ transaction processing and is used according to an ISV's needs.

Bluefin PayConex™ only integrates with Worldpay's Express so in order to use Level 3 data, an ISV is required to process with Worldpay's Express. For more, please check out Worldpay Level II and Level III Data.

Level 2 Data

If you support purchasing cards and Level 2 transactions, you will need to capture and transmit additional data fields to comply with the requirements set by the major card brands. Without these extra fields, your transactions do not qualify as Level 2 transactions.

To support Level 2 processing, this extra data should be provided in a transaction request such as SALE and AUTHORIZATION.

These additional fields are as follows:

ParameterTypeRequiredDescriptionExample
merchantReferencestringfalseA merchant-defined reference."MEM001"
orderIdstringfalseA merchant-defined order identifier."ORD001"
taxstringfalseFor Visa cards, the value must be expressed as greater than 0.00. For Mastercard, the value may be expressed as 0.00 if desired."0.20"
zipstringfalseTypically the same value as the customer's zip code parameter. This value is not validated like the zip, so any alphanumeric value up to 10 digits is valid."12345"

Request

POST /api/v4/accounts/{accountId}/payments/sale

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "level2": {
    "merchantReference": "MEM001",
    "orderId": "ORD001",
    "tax": "0.20",
    "zip": "12345"
  },
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Response

In response, Level 2 data is populated and is included as transaction metadata.

{
  "transactionId": "000000048786",
  "status": "CAPTURED",
  "timestamp": "2025-04-10T20:22:09.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "level2": {
    "merchantReference": "MEM001",
    "orderId": "ORD001",
    "tax": "0.20",
    "zip": "12345"
  },
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "8ae6a3e3-8c8c-45ed-b884-523f045a873d",
        "correlationId": "35110db5-be81-45aa-8142-9085c94f65ce",
        "timestamp": "2025-04-10T15:22:06-05:00"
      }
    ],
    "networkTransactionId": "015100470089038G996"
  },
  "amounts": {
    "currency": "USD",
    "approved": "5.00",
    "requested": "5.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK0287",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "5.00"
  }
}

Level 3 Data

When submitting level 3 data, level 2 data must also be included. Level 3 data provides a detailed breakdown of each individual line item in the transaction, allowing the Payment Processor to authorize level 3 data and trigger the level 3 adjustment. This level of detail enhances transaction validation, tracking, and reporting.

Multiple line items are supported for selling two or more services at a time as different items may have unique tax rates, discounts, or VAT amounts. This avoids issues with generalized tax or discount application that might not reflect each item's true cost.

Level 3 Data can serve a range of purposes including legal services, retail, and manufacturing.

Dynamic Level 3 Data

One of the two variants is to provide Level 3 data dynamically in a transaction request.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "level2": {
    "merchantReference": "121231",
    "orderId": "ORD001",
    "tax": "10.00",
    "zip": "90210"
  },
  "level3": {
    "summaryCommodityCode": "8012",
    "shipFromZip": "12345",
    "transactionSaleTaxRate": "1042",
    "merchantVatRegistrationNumber": "12-3456789",
    "customerVatRegistrationNumber": "123-45-6789",
    "discountAmount": "30.00",
    "freightAmount": "30.00",
    "dutyAmount": "30.00",
    "destinationZip": "90210",
    "destinationCountryCode": "840",
    "vatInvoiceRefNumber": "ABC-12345667",
    "orderDate": "20230728",
    "vatAmount": "30.00",
    "vatRate": "1042",
    "alternateTaxAmount": "30.00",
    "nationalTaxAmount": "30.00"
  },
  "items": [
    {
      "alternateTaxId": "987654321054321",
      "commodityCode": "09.02.10",
      "debitCreditCode": "2",
      "description": "Acme Electronics unit",
      "discountAmount": "0.00",
      "discountCode": "2",
      "discountRate": "0",
      "extendedItemAmount": "500.00",
      "lineItemTotal": "500.00",
      "netGrossCode": "2",
      "productCode": "ABC123",
      "quantity": "1.00",
      "unitCost": "500.00",
      "unitOfMeasure": "EA",
      "vatAmount": "50.00",
      "vatRate": "1000",
      "vatType": "1234"
    },
    {
      "alternateTaxId": "123456789012345",
      "commodityCode": "12.03.45",
      "debitCreditCode": "2",
      "description": "Gadget Pro 3000",
      "discountAmount": "5.00",
      "discountCode": "1",
      "discountRate": "500",
      "extendedItemAmount": "950.00",
      "lineItemTotal": "1000.00",
      "netGrossCode": "1",
      "productCode": "GAD3000",
      "quantity": "1.00",
      "unitCost": "950.00",
      "unitOfMeasure": "EA",
      "vatAmount": "50.00",
      "vatRate": "500",
      "vatType": "5678"
    }
  ],
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

📘

Note

With no level 3 data, the line items remain only as transaction metadata, meaning none interact with the Payment Processor at all.

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

Body Parameters

level3

As mentioned before, this data can be dynamically provided in a request using the parameters below or can be provided in a static form of Level 3 Profile. Level 3 data is also set with the Items.

ParameterTypeDescriptionExample
summaryCommodityCodestringInternational description code of overall goods or services."8012"
shipFromZipstringPostal or zip code of the address from where the purchased goods are being shipped."12345"
transactionSaleTaxRatestringTax rate used to calculate the Transaction Sale Tax Amount. Submitted as a percentage. Two-digit implied decimal. For example, if 10.42%, submit 1042."1042"
merchantVatRegistrationNumberstringGovernment-assigned tax identification number of merchant."12-3456789"
customerVatRegistrationNumberstringTax registration number supplied by cardholder."123-45-6789"
discountAmountstringDiscount amount applied to the line item. This field should be 0.00 if the unit cost reflects a discount price or if no line item discount applies."30.00"
freightAmountstringFreight or shipping portion of the total transaction amount."30.00"
dutyAmountstringAmount charged for duties. Fee amount associated with the import of the goods."30.00"
destinationZipstringZIP code to which the goods are being shipped."90210"
destinationCountryCodestringCountry code to which goods are being shipped. U.S. is 840."840"
vatInvoiceRefNumberstringInvoice number associated with VAT invoice. Not applicable for US merchants."ABC-12345667"
orderDatestringPurchase order date. Format: YYYYMMDD."20230728"
vatAmountstringAmount of any sales or value added taxes associated with the purchased item."30.00"
vatRatestringTax rate used to calculate VAT amount. Submitted as a percentage. Two-digit implied decimal. For example, if 10.42%, submit 1042."1042"
alternateTaxAmountstringSecond tax amount (used in countries where more than one tax can be applied). Not applicable for US merchants."30.00"
nationalTaxAmountstringSame as the previous."30.00"
items

Also known as Line Item Detail, this particular property is used to provide detailed information about each individual item/purchase or service included in a Level 3 transaction. It helps in breaking down the transaction into its constituent parts, offering clarity and specificity for the Payment Processor. An item is set with Level 3 data so that each item is processed with the Level 3 data adjusted accordingly in the back end.

ParameterTypeDescription
commodityCodestringInternational description code of the individual good or service being supplied. Recommend using national or international list of standardized codes.
descriptionstringItem description.
productCodestringMerchant-defined description code of the item.
quantitystringQuantity of the item (up to four decimal places).
unitOfMeasurestringCode for units of measurement used in international trade.
unitCoststringUnit cost of the item.
vatAmountstringAmount of any sales or value added taxes associated with the item.
vatRatestringSubmitted tax rate used to calculate VAT as a percentage. Two-digit implied decimal. For example, if 10.42%, submit 1042.
discountAmountstringDiscount amount applied to the line item. This field should be 0.00 if the unit cost reflects a discount price or if no line item discount applies.
lineItemTotalstringTotal full amount associated with the line item (including tax).
alternateTaxIdstringTax identification number of the merchant reporting the alternate tax amount. Not applicable for US merchants (tag must be present, but can be empty).
vatTypestringTax identification number of the merchant reporting the alternate tax amount. Not applicable for US merchants (tag must be present, but can be empty).
discountCodestringIndicates whether discount was applied to the purchase price of the item. 0 = Not supported, 1 = Amount is discounted, 2 = Amount is not discounted.
netGrossCodestringIndicates whether extended item amount included the tax. 0 = Not supported, 1 = Item Amount includes tax amount, 2 = Item Amount does not include tax amount.
extendedItemAmountstringAmount of the item (price multiplied by quantity).
debitCreditCodestringIndicates whether extendedItemAmount is a credit (taking away from the total amount of the sale) or debit (adding to the total amount of the sale). 0 = Not supported, 1 = Extended item amount is credit, 2 = Extended item amount is debit.
discountRatestringDiscount rate for the line item. Submitted as a percentage. Two-digit implied decimal. For example, if 10.42%, submit 1042.

Response

As it can be seen below, dynamically set Level 3 fields are also re-populated in response and as transaction metadata for tracking and reporting purposes.

{
  "transactionId": "000000048826",
  "status": "CAPTURED",
  "timestamp": "2025-04-10T20:25:24.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "level2": {
    "merchantReference": "121231",
    "orderId": "ORD001",
    "tax": "10.00",
    "zip": "90210"
  },
  "level3": {
    "status": "PENDING",
    "transactionSaleTaxRate": "1042",
    "merchantVatRegistrationNumber": "12-3456789",
    "customerVatRegistrationNumber": "123-45-6789",
    "summaryCommodityCode": "8012",
    "discountAmount": "30.00",
    "freightAmount": "30.00",
    "dutyAmount": "30.00",
    "destinationZip": "90210",
    "shipFromZip": "12345",
    "destinationCountryCode": "840",
    "vatInvoiceRefNumber": "ABC-12345667",
    "orderDate": "20230728",
    "vatAmount": "30.00",
    "vatRate": "1042",
    "alternateTaxAmount": "30.00",
    "nationalTaxAmount": "30.00"
  },
  "items": [
    {
      "quantity": "1.00",
      "commodityCode": "09.02.10",
      "description": "Acme Electronics unit",
      "productCode": "ABC123",
      "unitOfMeasure": "EA",
      "unitCost": "500.00",
      "vatAmount": "50.00",
      "vatRate": "1000",
      "vatType": "1234",
      "discountCode": "2",
      "netGrossCode": "2",
      "extendedItemAmount": "500.00",
      "debitCreditCode": "2",
      "discountRate": "0",
      "discountAmount": "0.00"
    },
    {
      "quantity": "1.00",
      "commodityCode": "12.03.45",
      "description": "Gadget Pro 3000",
      "productCode": "GAD3000",
      "unitOfMeasure": "EA",
      "unitCost": "950.00",
      "vatAmount": "50.00",
      "vatRate": "500",
      "vatType": "5678",
      "discountCode": "1",
      "netGrossCode": "1",
      "extendedItemAmount": "950.00",
      "debitCreditCode": "2",
      "discountRate": "500",
      "discountAmount": "5.00"
    }
  ],
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "00aa987f-8653-44b7-a5d6-46fe5c471b29",
        "correlationId": "495e0b3b-ce3b-4bc9-9710-c831c9a546c6",
        "timestamp": "2025-04-10T15:25:22-05:00"
      }
    ],
    "networkTransactionId": "015100772643694G058"
  },
  "amounts": {
    "currency": "USD",
    "approved": "5.00",
    "requested": "5.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK1657",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "5.00"
  }
}

Level 3 Profile

Level 3 Profiles is a separate PayConex™ service that allows you to have predefined level 3 data. In case you are repeatedly sending the same set of data in a level 3 transaction, the Level3Profile functions similarly to dynamically specifying all of the level 3 data and items, but it is static as it retrieves predefined level 3 data stored under a profile name in your PayConex™ account, applying consistent level 3 attributes and line items associated with that profile. This is helpful for transactions with standardized tax, shipping, and duty requirements.

For example, we can create a Level 3 Profile with the data we have used thus far.

POST /api/v4/accounts/{accountId}/level3-profile

{
  "name": "TESTPROFILE6",
  "data": {
    "transactionSaleTaxRate": "1042",
    "merchantVatRegistrationNumber": "12-3456789",
    "customerVatRegistrationNumber": "123-45-6789",
    "summaryCommodityCode": "8012",
    "discountAmount": "30.00",
    "freightAmount": "30.00",
    "dutyAmount": "30.00",
    "destinationZip": "90210",
    "shipFromZip": "12345",
    "destinationCountryCode": "840",
    "vatInvoiceRefNumber": "ABC-12345667",
    "orderDate": "20230728",
    "vatAmount": "30.00",
    "vatRate": "1042",
    "alternateTaxAmount": "30.00",
    "nationalTaxAmount": "30.00",
    "lineItemDetail": [
      {
        "quantity": "1.00",
        "commodityCode": "09.02.10",
        "description": "Acme Electronics unit",
        "productCode": "ABC123",
        "unitOfMeasure": "EA",
        "unitCost": "500.00",
        "vatAmount": "50.00",
        "vatRate": "1000",
        "vatType": "1234",
        "discountCode": "2",
        "netGrossCode": "2",
        "extendedItemAmount": "500.00",
        "debitCreditCode": "2",
        "discountRate": "0",
        "discountAmount": "0.00"
      },
      {
        "quantity": "1.00",
        "commodityCode": "12.03.45",
        "description": "Gadget Pro 3000",
        "productCode": "GAD3000",
        "unitOfMeasure": "EA",
        "unitCost": "950.00",
        "vatAmount": "50.00",
        "vatRate": "500",
        "vatType": "5678",
        "discountCode": "1",
        "netGrossCode": "1",
        "extendedItemAmount": "950.00",
        "debitCreditCode": "2",
        "discountRate": "500",
        "discountAmount": "5.00"
      }
    ]
  }
}

📘

Level 3 Profiles API

For more API examples, see Level 3 Profiles API.

Now, we can use that Level 3 Profile in a transaction request.

{
  "level2": {
    "merchantReference": "121231",
    "orderId": "ORD001",
    "tax": "10.00",
    "zip": "90210"
  },
  "level3ProfileName": "TESTPROFILE6",
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

📘

Note

If you manually add items and still use the Level3Profile that already defines them, the items in the request will overwrite the ones within the Level 3 Profile.

In this case, level 3 data and items are not populated either in response or transaction metadata but the Profile name used is stored, which means that the merchant gets to see what data was exactly used. See Getting a Level 3 Profile.