Level 2 and Level 3 data

Overview

Hyperswitch allows merchants to include Level 2 and Level 3 enhanced data in payment requests to optimize interchange costs on eligible commercial card transactions. This is done using a set of unified fields in the payment_create API, which are internally routed and transformed per connector.

• Level 2: Adds tax, invoice, and reference-level data
• Level 3: Adds full line-item details (e.g., item quantity, commodity code, shipping, duty)

Visa and Mastercard support Level 2 and 3 processing. American Express supports Level 2 only

Availability

• Regions: Most connectors currently support U.S. domestic processing only for Level 2 and Level 3 data
• Support for level 2/level 3 varies by connector and is not guaranteed

Unified L2/L3 Fields

Hyperswitch exposes a set of generic fields in the payment_create API that can be directly used to pass Level 2 and Level 3 data. These fields cover the most common requirements across card networks and connectors, so merchants can send enhanced transaction data without worrying about connector-specific differences.

The fields are organized into two groups:

1. Top-Level Fields (apply to the entire order/payment)

These fields represent order-wide attributes that are required by most connectors:

• order_date — when the order was placed
• customer_reference — unique reference, PO number, or invoice number
• order_tax_amount — total sales tax for the order
• shipping_cost — freight/shipping charges
• duty_amount — duty or customs charges
• discount_amount — any discount applied at the order level
• tax_status — whether the order is taxable or exempt

2. Nested Fields (grouped by domain for clarity)

Some data is structured to align with domain-specific groupings, making it easier to map downstream:

• Shipping
  • shipping.* (general attributes)
  • shipping.address.* (e.g., line1, postal_code, country)
  • shipping.phone.*
  • shipping.email
    
    
• Customer
  • customer.* (general attributes)
  • customer.address.*
  • customer.phone.*
  • customer.email
    
    
• Order Details (Line Items)\ Each item can include:
  • order_details[].product_name
  • order_details[].commodity_code
  • order_details[].quantity
  • order_details[].unit_of_measure
  • order_details[].unit_price
  • order_details[].item_tax_amount
  • order_details[].item_discount_amount

Supported Connectors

Our unified (generic) L2/L3 fields in payment_create cover the majority of requirements across connectors

If your connector requires fields that aren’t in our unified list, we’ll evaluate and add the minimal set needed