Payment line items

Send additional transaction metadata across supported Payment Method Types to access cost savings, facilitate payment reconciliation, and improve auth rates.

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/Product 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 and L3 rates eligibility

Visa the related setting Program

To learn more about Visa’s Commercial Enhanced Data Program (the related setting), which replaces their U.S. Level 2/3 interchange programs, including information about its network fees, see the the related setting Support article.

Note: Visa Level 2 was sunset in April 2026 and is no longer available. Visa savings are now available through Product 3 (the related setting) only.

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 and/or tax requirements, but these transactions don’t qualify for the corresponding Level 2/3 savings.

The following fields are required in order to receive L2 or L3 rates.

Field requirements

Pass the fields mentioned below either through amount_details or payment_details. Refer to Sample request (Level 2 data) to learn more about passing data.

General supported fields

Required field indicates a field is required to pass Stripe validations when any line item data is populated. Required for L2 or L3 indicates a field is required to receive network L2/L3 rates.

1 amount_details[tax][total_tax_amount] and amount_details[line_item][tax][total_tax_amount] are mutually exclusive. You can only specify one or the other.

2 amount_details[discount_amount] and amount_details[line_item][discount_amount] are mutually exclusive. You can only specify one or the other.

Additional cards supported fields

Cards supports the preceding general fields, and also supports:

Additional Klarna supported fields

Klarna supports the preceding general fields, and also supports:

Note

For Klarna transactions, total amount is implicitly derived from the formula (unit_cost * quantity) - discount_amount + tax.total_tax_amount. There is no explicit field to pass the amount.

Additional PayPal supported fields

Paypal supports the preceding general fields, and also supports:

Cards-specific line items for L2 and L3 rates

Pass in required data for eligible cards to qualify for L2/L3 network programs

• Level 2: sales tax charged on transactions
• Level 3/Product 3: line item level breakdown such as product code, quantity, unit cost

Sample request (Level 2 data)

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Sample response (Level 2 data)

{
 "id": "pi_3OoMm5BLxXjrKOiR3LRyi610",
 "amount": 4600,
 "currency": "usd",
 "amount_details": {
 "tax": {
 "total_tax_amount": 500
 }
 },
 "status": "requires_payment_method"
}

PaymentIntent operations

You can pass line items during both confirmation and capture.

Set line items during confirmation

You can set line items during confirmation regardless of the capture_method you choose. If you pass line items during confirmation, then capture separately, you don’t need to pass line items again.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Set line items during capture

If you don’t specify line items during confirmation, you can pass them during capture.

Note

Not supported when using PayPal

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Pass in an updated amount_details hash during capture if needed.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

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 aren’t included by default in the API response. To return line items, expand amount_details.line_items

Sample request (with payment method specific line items)

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Sample response (with payment method specific line items)

Using top-level discount or tax

The following example shows passing the top-level discount_amount and tax without line item level tax and discount_amount.

Sample request (top-level discount or tax)

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Sample response (top-level discount or tax)

Loosen arithmetic validation

By default, Stripe validates that your line item data adds up correctly. When the sum of line items doesn’t match the total amount, Stripe returns a 400 error so you can correct discrepancies before processing the payment.

Opt out of strict validation on a per-request basis by setting enforce_arithmetic_validation to false. When you do this:

• The request proceeds even if line item amounts don’t match the total.
• Stripe returns validation error details in the amount_details.error field in the response.
• For card payments, Stripe doesn’t send line item data with arithmetic errors to card networks, preventing the transaction from qualifying for L2/L3 interchange savings.

Sample request

The following is a sample request when arithmetic validation isn’t enforced:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Sample response

The following is a sample response when arithmetic validation isn’t enforced:

Industry to MCC codes

Flexible payment scenarios

You can use payment line items with complex payments such as surcharge, multicaptures, overcaptures, incremental authorization, decremental authorization, and partial authorization.