Level 2/Level 3 processing

DocsCurrentADVANCED

Last updated: Oct 17th, 6:15pm

What are Level 2 and 3 card payment transactions?

Card payment processing has three levels: Level 1, Level 2, and Level 3. The information required to complete the payment as a Level 1, Level 2, or Level 3 eligible transaction differs between the levels.

Level 1 requires less information and generally incurs higher interchange fees than the transactions processed with Level 2 and Level 3 data. Most businesses can operate at Level 1. However, IC++ merchants can benefit from reduced interchange fees when processing corporate and purchase credit cards by providing additional transaction information called Level 2 and Level 3 data.

Which types of card payments qualify?

Corporate and purchase credit cards are eligible for Levels 2 and 3 processing if the required information is provided. Consumer cards are only eligible for Level 1 processing. Level 2 and Level 3 cost optimization benefits don't apply to debit cards.

Which card networks support Level 2 and 3 processing?

Visa and Mastercard offer Levels 2 and 3 processing. American Express offers Level 2, and Discover offers only Level 1 processing.

How does a payment qualify?

Merchants must send the following information to qualify for Levels 2 and 3 processing. However, the card network and cardholder issuing bank ultimately determine whether a transaction qualifies for Level 2 or Level 3 processing:

Level 2 data

Card number, expiration, billing address, shipping address, and invoice number.

Customer Code or PO number: A unique reference ID for the order.

Tax amount: An amount must be submitted separately from the transaction amount.

Level 3 data

Level 2 data, and,

Unit amount or unit price.

Unit of measure.

Freight or shipping amount: The shipping and handling charges.

Duty amount: The charges for any import or export duties.

Discount amount.

Item commodity code.

Item description.

Item product code.

Item quantity.

Unit tax amount.

Unit discount amount.

Ship-from ZIP code.

Note: The partner, merchant, or other initiating party must provide the Level 2 and 3 payment details when using the Orders v2 API to start a payment.

Create Order request

This code sample shows Level 2 and 3 data in the body of a POST call to the Create order endpoint of the Orders v2 API. This request creates a new order and completes the payment in a single step by declaring the intent as CAPTURE:

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: REQUEST-ID' \
4-H 'Authorization: Bearer ACCESS-TOKEN' \
5-H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
6-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
7-d '{
8   "intent": "CAPTURE",
9   "payer": {
10      "name": {
11         "given_name": "Firstname",
12         "surname": "Lastname"
13      },
14      "address": {
15         "address_line_1": "123 Main St.",
16         "admin_area_2": "Anytown",
17         "admin_area_1": "CA",
18         "postal_code": "12345",
19         "country_code": "US"
20      }
21   },
22   "purchase_units": [
23      {
24         "reference_id": "Reference_ID_L2L32",
25         "description": "Description of PU",
26         "custom_id": "Custom-ID",
27         "soft_descriptor": "Purchase Descriptor",
28         "invoice_id": "INV_202302011234",
29         "supplementary_data": {
30            "card": {
31               "level_2": {
32                  "invoice_id": "INV_202302011234",
33                  "tax_total": {
34                     "currency_code": "USD",
35                     "value": "5.20"
36                  }
37               },
38               "level_3": {
39                  "shipping_amount": {
40                     "currency_code": "USD",
41                     "value": "1.17"
42                  },
43                  "duty_amount": {
44                     "currency_code": "USD",
45                     "value": "1.16"
46                  },
47                  "discount_amount": {
48                     "currency_code": "USD",
49                     "value": "1.15"
50                  },
51                  "shipping_address": {
52                     "address_line_1": "123 Main St.",
53                     "admin_area_2": "Anytown",
54                     "admin_area_1": "CA",
55                     "postal_code": "12345",
56                     "country_code": "US"
57                  },
58                  "ships_from_postal_code": "12345",
59                  "line_items": [
60                     {
61                        "name": "Item1",
62                        "description": "Description of Item1",
63                        "upc": {
64                           "type": "UPC-A",
65                           "code": "001004697"
66                        },
67                        "unit_amount": {
68                           "currency_code": "USD",
69                           "value": "9.50"
70                        },
71                        "tax": {
72                           "currency_code": "USD",
73                           "value": "5.12"
74                        },
75                        "discount_amount": {
76                           "currency_code": "USD",
77                           "value": "1.11"
78                        },
79                        "total_amount": {
80                           "currency_code": "USD",
81                           "value": "95.10"
82                        },
83                        "unit_of_measure": "POUND_GB_US",
84                        "quantity": "10",
85                        "commodity_code": "98756"
86                     }
87                  ]
88               }
89            }
90         },
91         "amount": {
92            "currency_code": "USD",
93            "value": "100.30",
94            "breakdown": {
95               "item_total": {
96                  "currency_code": "USD",
97                  "value": "90.20"
98               },
99               "tax_total": {
100                  "currency_code": "USD",
101                  "value": "10.10"
102               },
103               "shipping": {
104                  "currency_code": "USD",
105                  "value": "10.00"
106               },
107               "discount": {
108                  "currency_code": "USD",
109                  "value": "10.00"
110               }
111            }
112         },
113         "items": [
114            {
115               "name": "Item1",
116               "description": "Description of Item1",
117               "sku": "SKU - 0",
118               "url": "http: //example.com",
119               "unit_amount": {
120                  "currency_code": "USD",
121                  "value": "45.10"
122               },
123               "tax": {
124                  "currency_code": "USD",
125                  "value": "5.05"
126               },
127               "quantity": "2",
128               "category": "PHYSICAL_GOODS"
129            }
130         ],
131         "shipping": {
132            "address": {
133               "address_line_1": "123 Main St.",
134               "admin_area_2": "Anytown",
135               "admin_area_1": "CA",
136               "postal_code": "12345",
137               "country_code": "US"
138            }
139         }
140      }
141   ]
142}'

Lines 25-31 declare a level_2 object inside purchase_units.supplementary_data.card, including the invoice ID and the taxes charged for the payment.

Lines 32-82 declare a level_3 object inside purchase_units.supplementary_data.card. Data includes shipping, duty, discount amounts, line-item information, and units of measure.

Ensure consistent field mapping between purchase units and supplementary data

Ensure that the field names, data types, formats, and values in the supplementary_data object match the corresponding fields in the purchase_units object. The following table shows which fields from each object need to match.

supplementary_data	purchase_units
`card.level_2.invoice_id`	`invoice_id`
`card.level_2.tax_total.currency_code`	`amount.breakdown.tax_total.currency_code`
`card.level_2.tax_total.value`	`amount.breakdown.tax_total.value`
`card.level_3.shipping_amount.currency_code`	`amount.breakdown.shipping.currency_code`
`card.level_3.shipping_amount.value`	`amount.breakdown.shipping.value`
`card.level_3.discount_amount.currency_code`	`amount.breakdown.discount.currency_code`
`card.level_3.discount_amount.value`	`amount.breakdown.discount.value`
`card.level_3.shipping_address.address_line_1`	`shipping.address.address_line_1`
`card.level_3.shipping_address.address_line_2`	`shipping.address.address_line_2`
`card.level_3.shipping_address.admin_area_2`	`shipping.address.admin_area_2`
`card.level_3.shipping_address.admin_area_1`	`shipping.address.admin_area_1`
`card.level_3.shipping_address.postal_code`	`shipping.address.admin_area_1`
`card.level_3.shipping_address.country_code`	`shipping.address.country_code`
`card.level_3.line_items[0].name`	`items[0].name`
`card.level_3.line_items[0].description`	`items[0].description`
`card.level_3.line_items[0].upc.type`	`items[0].upc.type`
`card.level_3.line_items[0].upc.code`	`items[0].upc.code`
`card.level_3.line_items[0].unit_amount.currency_code`	`items[0].unit_amount.currency_code`
`card.level_3.line_items[0].unit_amount.value`	`items[0].unit_amount.value`
`card.level_3.line_items[0].tax.currency_code`	`items[0].tax.currency_code`
`card.level_3.line_items[0].tax.value`	`items[0].tax.value`
`card.level_3.line_items[0].total_amount.currency_code`	`amount.breakdown.item_total.currency_code`
`card.level_3.line_items[0].total_amount.value`	`amount.breakdown.item_total.value`
`card.level_3.line_items[0].quantity`	`items[0].quantity`

Note:

When the common fields between purchase_units and supplementary_data don't match, the values from the latter take precedence.

When you send a PATCH request that modifies the purchase_units object, include the corresponding supplementary_data object. Update both objects simultaneously to maintain consistency.

If you don't send supplementary_data in the PATCH request, the system automatically deletes the existing supplementary_data object to prevent discrepancies and ensure data integrity.