Use payment line items for flexible paymentsPublic preview

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

Multicapture

You can use payment line items during multicaptures.

Create and confirm an uncaptured PaymentIntent

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.

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

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.

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).

Overcapture

You can use payment line items during overcaptures.

Create and confirm an uncaptured PaymentIntent

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.

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.

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

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.

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.

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.