Level 2 and 3 Processing

Required Fields

Level 2 data

To qualify for Level 2 processing on a given transaction, include the following fields in the Transaction: Sale call:

Interchange rates for Level 2 data

The values you pass in the required Level 2 fields determine whether you qualify for lower interchange rates or not. US merchants must pass a taxAmount() between 0.1% and 22% for Visa transactions, and between 0.1% and 30% for Mastercard transactions.

taxExempt() transactions may not qualify for reduced L2 rates, but they could still be eligible for L3 rates.

Creating a transaction

Here's a full example with the required fields for Level 2:

Java

TransactionRequest transactionRequest = new TransactionRequest()
    .amount(new BigDecimal("100.00"))
    .paymentMethodNonce(nonceFromTheClient)
    .purchaseOrderNumber("12345")
    .taxAmount(new BigDecimal("5.00"));
Result<transaction> result = gateway.transaction().sale(transactionRequest);

Level 3 data

To qualify for Level 3 processing on a given transaction, you must pass Level 2 data, along with specific additional Level 3 data and line items. Line items are similar to the details you would find on an itemized invoice.

When you create a transaction, include the following fields in the Transaction: Sale call:

Level 2 fields
Level 3 fields:
Level 3 lineItem()
- lineItem.name
- lineItem.kind
- lineItem.quantity
- lineItem.unitAmount
- lineItem.unitOfMeasure
- lineItem.totalAmount
- lineItem.taxAmount
- lineItem.discountAmount
- lineItem.productCode
- lineItem.commodityCode

Supported characters

To ensure all line items appear as expected on the cardholder's statement, use only a-z, A-Z, 0-9, ', ., -, and spaces in the following fields:

Line items that contain other characters may still qualify for Level 3 processing, but unsupported characters will be converted to a space on the cardholder's statement.

Amount validation

Each processor verifies that the total of the line item amounts matches the root transaction amount. If there's a discrepancy, the transaction may be declined. To ensure these amounts match, it's advisable to sum the per-item tax, subtotal amounts, shipping tax, and shipping amount to calculate the total transaction amount. In the EU and UK regions, transactions with a non-zero shipping amount may be rejected if the shipping tax amount is zero. Below is an example for validating the amounts in Ruby.

Creating a transaction

Below is a full example using the minimum required fields for Level 3:

Java

TransactionRequest transactionRequest = new TransactionRequest()
    .amount(new BigDecimal("100.00"))
    .paymentMethodNonce(nonceFromTheClient)
    .purchaseOrderNumber("12345")
    .taxAmount(new BigDecimal("5.00"))
    .taxExempt(new Boolean(false))
    .shippingAmount(new BigDecimal("1.00"))
    .shippingTaxAmount(new BigDecimal("0.1"))
    .discountAmount(new BigDecimal("0.00"))
    .shipsFromPostalCode("60654")
    .shippingAddress()
        .firstName("Clinton")
        .lastName("Ecker")
        .streetAddress("1234 Main Street")
        .extendedAddress("Unit 222")
        .locality("Chicago")
        .region("IL")
        .postalCode("60654")
        .countryCodeAlpha3("USA")
        .done()
    .lineItem()
        .name("Product")
        .kind(TransactionLineItem.Kind.DEBIT)
        .quantity(new BigDecimal("10.0000"))
        .unitAmount(new BigDecimal("9.5000"))
        .unitOfMeasure("unit")
        .totalAmount(new BigDecimal("95.00"))
        .taxAmount(new BigDecimal("5.00"))
        .discountAmount(new BigDecimal("0.00"))
        .productCode("54321")
        .commodityCode("98765")
        .done();
Result<transaction> result = gateway.transaction().sale(transactionRequest);

Specifying level 2 and 3 data when submitting for settlement

Availability

Level 2 and 3 processing via submit for settlement requires internal approval. Please contact us if you’re interested in this functionality.

In some cases, transaction amounts, and by extension Level 2 and 3 parameters, are not finalized until the transaction is ready to be submitted for settlement. This functionality allows you to apply Level 2 and 3 parameters when submitting a transaction for settlement instead of specifying them in the transaction sale call.

Note

Level 2 and 3 data provided via submit for settlement will override all Level 2 and 3 data previously provided in a sale request. If you wish to pass Level 2 and 3 data, we recommend utilizing either transaction.sale or transaction.submit_for_settlement, but not both at the same time.

Java

TransactionRequest request = new TransactionRequest()
    .purchaseOrderNumber("12345")
    .taxAmount(new BigDecimal("5.00"))
    .taxExempt(new Boolean(false))
    .shippingAmount(new BigDecimal("1.00"))
    .shippingTaxAmount(new BigDecimal("0.1"))
    .discountAmount(new BigDecimal("0.00"))
    .shipsFromPostalCode("60654")
    .lineItem()
        .name("Product")
        .kind(TransactionLineItem.Kind.DEBIT)
        .quantity(new BigDecimal("10.0000"))
        .unitAmount(new BigDecimal("9.5000"))
        .unitOfMeasure("unit")
        .totalAmount(new BigDecimal("95.00"))
        .taxAmount(new BigDecimal("5.00"))
        .discountAmount(new BigDecimal("0.00"))
        .productCode("54321")
        .commodityCode("98765")
        .done();
Result<transaction> result = gateway.transaction().submitForSettlement("transactionId", request);
if (result.isSuccess()) {
    // See result.getTarget for details
} else {
    // Handle errors
}

Validation errors

A transaction result may contain validation errors specifically for Level 3 fields or transaction line items, but only if the format or length of the value is outside expected bounds. This is to ensure the additional fields minimally interfere with the successful submission of transactions.

For a list of errors, see the Validation Errors reference page.