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
tax_amount between
0.1% and 22% for Visa transactions, and between 0.1% and 30% for Mastercard transactions.tax_exempt
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:
- Ruby
result = gateway.transaction.sale(
:amount => "100.00",
:payment_method_nonce => nonce_from_the_client,
:purchase_order_number => "12345",
:tax_amount => "5.00"
)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
line_items- line_items.name
- line_items.kind
- line_items.quantity
- line_items.unit_amount
- line_items.unit_of_measure
- line_items.total_amount
- line_items.tax_amount
- line_items.discount_amount
- line_items.product_code
- line_items.commodity_code
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.
- Ruby
currency = "USD"
# Calculate subtotal and tax amount
subtotal_amount = 0
tax_amount = 0
line_items = items.map do |item|
item_subtotal_amount = item.unit_amount * item.quantity
item_tax_amount = item.unit_tax_amount * item.quantity
if item.kind == "debit"
subtotal_amount += item_subtotal_amount
tax_amount += item_tax_amount
else
subtotal_amount -= item_subtotal_amount
tax_amount -= item_tax_amount
end
{
:quantity => item.quantity,
:name => item.name,
:kind => item.kind,
:unit_amount => Money.new(item.unit_amount, currency).to_s,
:unit_tax_amount => Money.new(item.unit_tax_amount, currency).to_s,
:tax_amount => Money.new(item_tax_amount, currency).to_s,
:total_amount => Money.new(item_subtotal_amount, currency).to_s,
}
end
# Define your shipping amount
shipping_amount = 2_00
shipping_tax_amount = 0.2
# Calculate total amount charged to the customer
total_amount = subtotal_amount + shipping_amount + tax_amount + shipping_tax_amount
result = gateway.transaction.sale(
:amount => Money.new(total_amount, currency).to_s,
:shipping_amount => Money.new(shipping_amount, currency).to_s,
:tax_amount => Money.new(tax_amount, currency).to_s,
:payment_method_nonce => nonce_from_the_client,
:line_items => line_items,
)Creating a transaction
Below is a full example using the minimum required fields for Level 3:
- Ruby
result = gateway.transaction.sale(
{
:amount => "100.00",
:payment_method_nonce => nonce_from_the_client,
:purchase_order_number => "12345",
:tax_amount => "5.00",
:tax_exempt => false,
:shipping_amount => "1.00",
:shipping_tax_amount => "0.1",
:discount_amount => "0.00",
:ships_from_postal_code => "60654",
:shipping => {
:first_name => "Clinton",
:last_name => "Ecker",
:street_address => "1234 Main Street",
:extended_address => "Unit 222",
:locality => "Chicago",
:region => "IL",
:postal_code => "60654",
:country_code_alpha3 => "USA"
},
:line_items => [
{
:name => "Product Name",
:kind => "debit",
:quantity => "10.0000",
:unit_amount => "9.5000",
:unit_of_measure => "unit",
:total_amount => "95.00",
:tax_amount => "5.00",
:discount_amount => "0.00",
:product_code => "54321",
:commodity_code => "98765"
}
]
}
);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.
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.
- Ruby
result = gateway.transaction.submit_for_settlement("transaction_id", nil,
{
:purchase_order_number => "12345",
:tax_amount => "1.23",
:tax_exempt => false,
:shipping_amount => "1.00",
:shipping_tax_amount => "0.1",
:discount_amount => "0.00",
:ships_from_postal_code => "60654",
:line_items => [
{
:name => "Product Name",
:kind => "debit",
:quantity => "10.0000",
:unit_amount => "9.5000",
:unit_of_measure => "unit",
:total_amount => "95.00",
:tax_amount => "5.00",
:discount_amount => "0.00",
:product_code => "54321",
:commodity_code => "98765"
}
]
}
);
if result.success?
settled_transaction = result.transaction
else
puts(result.message)
end