Use payment line items for flexible payments

Learn how to use payment line items with complex payments, such as multicapture and overcapture payments.

You can use payment line items for complex payments, such as multicapture and overcapture payments.

Multicapture

You can use payment line items during multicaptures.

Note

Multicapture isn’t supported for Klarna or PayPal.

Create and confirm an uncaptured PaymentIntent

Note

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Specify the capture_method as manual when creating the PaymentIntent and use the if_available parameter to request multicapture for this payment. The created PaymentIntent allows multiple captures if the payment method supports it.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified on the PaymentIntent.

{
 "amount": 4600,
 "amount_capturable": 4600,
 "amount_received": 0,
 "payment_details": {
 "customer_reference": "customer_reference",
 "order_reference": "order_reference"
 },
 "amount_details": {
 "discount_amount": 200,
 "tax": {
 "total_tax_amount": 400
 },
 "shipping": {
 "from_postal_code": "94110",
 "to_postal_code": "94117",
 "amount": 400
 },
 "line_items": [
 {
 "product_code": "SKU001",
 "product_name": "Product 001",
 "unit_cost": 2000,
 "quantity": 1,
 "unit_of_measure": "feet",
 "payment_method_options": {
 "card": {
 "commodity_code": "123123"
 }
 }
 },
 {
 "product_code": "SKU002",
 "product_name": "Product 002",
 "unit_cost": 2000,
 "quantity": 1,
 "unit_of_measure": "gallons",
 "payment_method_options": {
 "card": {
 "commodity_code": "123123"
 }
 }
 }
 ]
 }
 ...
}

Capture the PaymentIntent

You can add amount _ details on the first capture even if they weren’t specified at creation.
If you provided amount _ details at creation, you must either pass in amount _ details or unset them on the first capture.

The same rules apply to amount_details[line_items] —you can add them on the first capture if not specified at creation, but must include or explicitly unset them if they were present at creation.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified on the first capture.

The PaymentIntent remains in a requires_capture state. At this point, you can either:

Continue to capture the PaymentIntent multiple times up to the full amount of the PaymentIntent.
Transition the PaymentIntent to a succeeded state by setting final _ capture to true , or making a capture without the final _ capture parameter (because final _ capture defaults to true ).
If previous captures included amount _ details or amount _ details[line _ items] , you must continue to include them in subsequent captures.
If previous captures didn’t include these fields, you can’t add them in later captures.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items from the first two captures, according to the following rules:

discount _ amount , tax. total _ tax _ amount and shipping. amount are summed across captures.
shipping. from _ postal _ code and shipping. to _ postal _ code might be omitted in the captures, but if it’s provided, you must not change it across captures.
line _ items will be aggregated across captures.

Overcapture

You can use payment line items during overcaptures.

Create and confirm an uncaptured PaymentIntent

Note

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Specify the capture_method as manual when creating the PaymentIntent and use the if_available parameter to request overcapture for this payment. The created PaymentIntent allows overcapture if the payment method supports it.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified on the PaymentIntent.

Capture the PaymentIntent

To capture more than the currently authorized amount on a PaymentIntent, use the capture endpoint and provide an amount_to_capture up to the maximum_amount_capturable.

Pass in an updated amount_details hash that is consistent with the capture amount during Capture.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified during capture.

Incremental authorization

You can use payment line items during incremental authorization to authorize additional amounts on a PaymentIntent after the initial authorization.

Create and confirm an uncaptured PaymentIntent

Note

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Specify the capture_method as manual when creating the PaymentIntent and use the if_available parameter to request incremental authorization for this payment. The created PaymentIntent allows incremental authorization if the payment method supports it.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified on the PaymentIntent.

Increment the authorization

To authorize additional amounts on a PaymentIntent beyond the initially authorized amount, use the increment_authorization endpoint and provide an amount up to the maximum incremental authorization amount supported by the payment method.

Pass in an updated amount_details hash that is consistent with the total authorized amount after the increment.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items specified during the increment authorization, and the PaymentIntent’s total authorized amount is updated.

Partial authorization

You can use payment line items with partial authorizations.

Create and confirm an uncaptured PaymentIntent

Note

The API response doesn’t include line items by default. To return line items, expand amount_details.line_items.

Specify the capture_method as manual when creating the PaymentIntent and use the if_available parameter to request partial authorization for this payment.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

If you provided line item data before the partial authorization, the sum of the line item amounts might not match the total amount on the PaymentIntent. In that case, the amount_details.error hash in the response has a code of amount_details_amount_mismatch and includes the mismatch amount in the message property.

The example response below shows the transaction being partially authorized for 7 USD, which is less than the originally requested 10 USD.

Example PaymentIntent confirmation response

Capture the PaymentIntent

Capture the PaymentIntent and pass an updated amount_details that matches the partially authorized amount.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Updating amount_details removes the mismatch error hash from the PaymentIntent. For card payments, that allows Stripe to send the line item data to card networks.

Example PaymentIntent capture response

Add a surcharge

You can use payment line items with surcharges.

Create and confirm a PaymentIntent

When you create a PaymentIntent, make sure to follow the standard flow for surcharging. Specify the total amount inclusive of the surcharge and pass the surcharge amount in amount_details[surcharge][amount]. Don’t create a separate line item for the surcharge. To populate tax information with the surcharge, use amount_details[tax][total_tax_amount] instead of amount_details[line_item][tax][total_tax_amount].

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, the amount_details field contains the line items that you specified on the PaymentIntent.

Example of an incorrect implementation

The following example shows what happens if you add a surcharge line item in addition to specifying amount_details[surcharge][amount] when creating the PaymentIntent. In this example, the line items won’t correctly add up to the amount exclusive of the surcharge amount, and the request will 400.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results