Payments line itemsPrivate preview
Send additional transaction metadata across supported Payment Method Types to access cost savings, facilitate payment reconciliation, and improve auth rates.
Contact to enable
Contact your sales representative or support to enable this private preview feature.
Payment line items is a feature in the Payment Intents API that provides benefits for cards and local payment methods processing.
- Cost savings for eligible commercial cards for IC+ users: By passing payment line items, you can participate in the Level 2/Level 3 (L2/L3) program that major card networks administer. For eligible commercial cards, passing line item data can provide interchange fee savings.
- Facilitate reconciliation: Passing line item data can also facilitate reconciliation for your customers. For example, if you primarily serve government customers, it will aid the customer in reconciling a purchase against what shows up on their statement.
- Improved authorization rates: Payment methods like Klarna and PayPal use line item data in their underwriting models, potentially allowing them to approve more credit based payment options when line items data is passed.
Feature restrictions
Payment line items have the following restrictions across supported payment method types:
Cards L2/L3 program | Klarna | PayPal | |
---|---|---|---|
Geographic availability | Only supported for US domestic transactions (US user accepting US issued cards, excluding US territories) | Klarna is a global payment method. For business location support, see Klarna payments. | Available for customers in all locations. For business location support, see PayPal payments. |
Card networks | Only supported for Visa, Mastercard, and American Express (cost savings requires direct agreement with American Express) | Not applicable | Not applicable |
Number of line items | Currently supports 100 line items (maximum of 4 line items for American Express) | Same as cards | Same as cards |
Feature compatibility | Only auto and separate authorization and capture modes work with payment line items. You can’t currently use decremental authorization or for transactions where you’re passing in payment line items. | Only auto and separate authorization and capture modes work with payment line items. | Only auto and separate authorization and capture modes work with payment line items. |
Industry specific metadata | You can’t send line items alongside industry specific metadata such as car rental/lodging, and airlines | Klarna supports industry specific metadata with Extra Merchant Data (private preview). | Same as cards |
Surfaces | Only available for payments made through the PaymentIntents API. | Same as cards | Same as cards |
Cards L2/L3 Rates Eligibility
See Industry to MCC codes to see what MCC your business might fall under.
Stripe API doesn’t reject line items that don’t meet the network MCC or tax requirements. However, these transactions don’t qualify for the corresponding Level 2/3 savings.
Cards L2/L3 Rates Eligibility | Level 2 | Level 3 |
---|---|---|
Card types | Only Business, Purchasing, and Corporate cards are eligible | Only Purchasing and Corporate cards are eligible |
MCCs | Users with the following MCCs aren’t eligible for Level II:
| Users with the following MCCs aren’t eligible for Level III:
|
Sales tax requirement |
| Not applicable |
Field Requirements
All the fields mentioned below are passed inside amount_details. Refer to Sample request (Level II data) to learn about passing data.
General supported fields
Private preview
Two more fields [Commodity Code] and [Unit of Measure] aren’t yet available in private preview, but will become required for the Visa CEDP program (refer to Network Cost Updates for Feb 20, 2025).
Field Name | Type | Values / Restrictions | Description | Required For L2/L3 | Required API Fields |
---|---|---|---|---|---|
payment_details[customer_reference] | string | This field isn’t available for non-card payments. | Some customers might be required by their company or organization to provide this information. If so, provide this value. Otherwise you can ignore this field. | ||
payment_details[order_reference] | string | This field isn’t available for non-card payments. If automatic_payment_methods.enabled is set to | A unique value assigned by the business to identify the transaction. | ✅ L2/L3 | |
discount_amount | integer | Value must be > 0 | The total discount applied on the transaction represented in the smallest currency unit. | ||
shipping[to_postal_code] | string | Max length 10 chars. Value must be alphanumeric characters | If a physical good is being shipped, the postal code of where it’s being shipped to. | ||
shipping[from_postal_code] | string | Max length 10 chars. Value must be alphanumeric characters | If a physical good is being shipped, the postal code of where it’s being shipped from. | ||
shipping[amount] | integer | Value must be >= 0 | If a physical good is being shipped, the cost of shipping represented in the smallest currency unit. | ||
tax[total_tax_amount] | integer | Value must be >= 0 | The total amount of tax on the transaction. | ✅ L2 | |
line_items[tax][total_tax_amount] | integer | Value must be >= 0 | The total amount of tax on a single line item represented in the smallest currency unit. | ✅ L3 | |
line_items[product_name] | string | Max length 1024 chars. Cards truncates to 26 characters and Paypal truncates to 127 characters. | The product name of the line item. | ✅ L3 | ✅ |
line_items[product_code] | string | Max length 12 chars | The product code of the line item, such as an SKU. | ✅ L3 | |
line_items[unit_cost] | integer | Value must be >= 0 | The unit cost of the line item represented in the smallest currency unit. | ✅ L3 | ✅ |
line_items[quantity] | integer | Value must be > 0 | The quantity of items. | ✅ L3 | ✅ |
line_items[discount_amount] | integer | Value must be > 0 | The discount applied on this line item represented in the smallest currency unit. |
Note
The following fields are mutually exclusive; you can provide only one in a request:
- Either
tax[total_
ortax_ amount] line_
items[tax][total_ tax_ amount] - Either
discount_
oramount line_
items[discount_ amount]
Additional Klarna supported fields
Klarna supports the above fields for cards, and in addition, also supports:
Field Name | Type | Values and Restrictions | Description | Required |
---|---|---|---|---|
line_items[payment_method_options][klarna][product_url] | string | Max 4096 characters. Rough Regex: https?:\/\/[-a-zA-Z0-9@:%. | Valid http or https URL of the product | |
line_items[payment_method_options][klarna][image_url] | string | Max 4096 characters. Rough Regex: https?:\/\/[-a-zA-Z0-9@:%. | Valid http or https URL of the image |
Note
For Klarna transactions, total amount is implicitly derived from the formula (unit_
. There is no explicit field to pass the amount.
Additional PayPal Supported Fields
PayPal supports the above fields for cards, and in addition, also supports:
Field Name | Type | Values / Restrictions | Description | Required |
---|---|---|---|---|
line_items[payment_method_options][paypal][description] | string | Max 127 characters | Description of the line item. | |
line_items[payment_method_options][paypal][category] | enum | digital_goods, physical_goods, donation | Type of the line item. | |
line_items[payment_method_options][paypal][sold_by] | string | Max 127 characters | The Stripe account ID of the connected account that sells the item. |
Cards-specific line items for L2/L3 rates
Pass in required data for eligible cards to qualify for L2/L3 network programs
- Level II: sales tax charged on transactions
- Level III: line item level breakdown such as product code, quantity, unit cost
Payment Intent Confirmation
PaymentIntent capture
Capture the PaymentIntent separately after confirmation by passing in manual_
during PaymentIntent Creation or Confirmation, and then call the Capture endpoint separately.
Pass in an updated amount_
hash during Capture if needed.
Payment Method Specific line items
Pass in additional payment method types on a per-line-item basis all in one place. You can pass in data related to payment methods you might not be confirming with as well, as long as the parameter is supported. This can simplify your integration, without requiring engineering effort to add and remove payment method specific fields for each payment method.
Note
Line items are not included by default in the API response. To return line items, expand amount_
Sample request
Sample response
{ id: "pi_3OoMm5BLxXjrKOiR3LRyi610", amount: 4600, currency: "usd" amount_details: { discount_amount: 100, shipping: { from_postal_code: "94110", to_postal_code: "94117", amount: 100 }, tax: { total_tax_amount: 500 }, line_items: { object: "list", url: "/v1/payment_intents/pi_3OoMm5BLxXjrKOiR3LRyi610/amount_details_line_items", has_more: false, data: [{ _id: "li_123", product_code: "SKU001", product_name: "Product 001", unit_cost: 2000, quantity: 1, discount_amount: 0, tax: { total_tax_amount: 100 }, payment_method_options: { klarna: { image_url: "https://www.example.com/image.jpg", product_url: "https://www.example.com/product" }, paypal: { description: "This is a sample product description unique to PayPal for SKU001", category: digital_goods, } } }, { _id: "li_456", product_code: "SKU002", product_name: "Product 002", unit_cost: 1800, quantity: 1, discount_amount: 0, tax: { total_tax_amount: 100 }, payment_method_options: { klarna: { image_url: "https://www.example.com/image.jpg", product_url: "https://www.example.com/product" }, paypal: { description: "This is a sample product description unique to PayPal for SKU001", category: physical_goods, } } } ] } }, status: "requires_payment_method" }
The following example shows passing the top-level discount_
and tax
without line item level tax
and discount_
Sample Reponse
{ "id": "pi_3R0p2JCvDOElLqwO0mlHFrzv", "object": "payment_intent", "amount": 2500, "amount_capturable": 0, "amount_details": { "discount_amount": 100, "line_items": { "object": "list", "data": [ { "id": "uli_RueKif6jOR65uG", "object": "amount_details_line_item", "discount_amount": null, "payment_method_options": { "klarna": { "image_url": "https://www.example.com/image.jpg", "product_url": "https://www.example.com/product" }, "paypal": { "category": "digital_goods", "description": "This is a sample product description unique to PayPal for SKU001" } }, "product_code": "SKU001", "product_name": "Product 001", "quantity": 1, "tax": null, "unit_cost": 2000 } ], "has_more": false, "url": "/v1/payment_intents/pi_3R0p2JCvDOElLqwO0mlHFrzv/amount_details_line_items" }, "shipping": { "amount": 100, "from_postal_code": "94110", "to_postal_code": "94117" }, "tax": { "total_tax_amount": 500 }, "tip": {} }, "amount_received": 0, "amount_subtotal": 2500, "capture_method": "automatic_async", "payment_details": { "customer_reference": "customer_reference", "order_reference": "order_reference" }, "payment_method": null, "payment_method_configuration_details": null, "payment_method_options": { "card": { "installments": null, "mandate_options": null, "network": null, "request_three_d_secure": "automatic" }, "klarna": { "preferred_locale": null }, "paypal": { "preferred_locale": null, "reference": null } }, "payment_method_types": ["card", "paypal", "klarna"], ... }
Industry to MCC codes
Category | Description |
---|---|
Food & Beverage |
|
Hospitality & Travel |
|
Retail & E-Commerce |
|
Utilities & Miscellaneous |
|