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 authorised 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 authorisation

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

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 authorisation for this payment. The created PaymentIntent allows incremental authorisation 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 authorisation

To authorise additional amounts on a PaymentIntent beyond the initially authorised amount, use the increment_authorisation endpoint and provide an amount up to the maximum incremental authorisation amount supported by the payment method.

Pass in an updated amount_details hash that is consistent with the total authorised 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 authorisation and the PaymentIntent’s total authorised amount is updated.

Partial authorisation

You can use payment line items with partial authorisations.

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 authorisation 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 authorisation, 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 authorised for US$7, which is less than the originally requested US$10.

Example PaymentIntent confirmation response

Capture the PaymentIntent

Capture the PaymentIntent and pass an updated amount_details that matches the partially authorised 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