Increment an Authorization

Some flows only learn the final amount after the card has already been authorized: a hotel stay that runs long, a fuel or rental top-up, an order with items added after checkout. Incremental authorization raises the authorized amount on a confirmed but uncaptured PaymentIntent so you can capture more than you originally held.

Prerequisites

An increment is only possible if the payment was set up for it in advance. Eligibility is decided at authorization time and cannot be added afterwards — there is no way to make an already-authorized payment incrementable.

Requirement	Detail
Manual capture	The PaymentIntent must be requires_capture with capture_method: manual, and its charge authorized and not yet captured. See Manual Capture.
Opted in up front	payment_method_options.card.request_incremental_authorization must have been set to if_available when the PaymentIntent was created or confirmed.
Card, card-not-present	Card payments only. card_present, napas_qr, and cake_pay are not supported.
Within the limit	At most 10 increments per charge. Further calls are rejected once the limit is reached.

Opting In: request_incremental_authorization

Set the option under payment_method_options.card on the call that creates or confirms the PaymentIntent.

Value	Behaviour
if_available	Request incremental authorization. Whether it is actually granted is decided by the issuer at authorization time.
never	Default. No increments possible.
request_incremental_authorization_unspecified	Treated as unset — same effect as never.

Because eligibility is decided at authorization, if_available is a request, not a guarantee. Set it whenever an increment is plausible; it costs nothing when you never increment.

POST /api/payment_intents

{
  "amount": 100000,
  "currency": "704",
  "capture_method": "manual",
  "payment_method_options": {
    "card": {
      "request_incremental_authorization": "if_available"
    }
  }
}

Field	Required	Description
capture_method	Yes	Must be "manual". An increment has no meaning for an automatically captured payment.
payment_method_options.card.request_incremental_authorization	Yes	Set to "if_available". Defaults to "never".

Incrementing

POST /api/payment_intents/{id}/increment_authorization

Request

{
  "amount": 150000,
  "description": "Extended stay — 1 additional night"
}

Field	Required	Description
amount	Yes	The new total authorized amount in the smallest currency unit — not a delta. Must exceed the PaymentIntent's current amount.
description	No	Replaces the PaymentIntent's description. Omit to leave it unchanged.
metadata	No	Replaces the PaymentIntent's metadata. Omit to leave it unchanged.

WARNING

amount is the new total, not the increase. To raise a 100,000 authorization by 50,000, send 150000 — sending 50000 is rejected for being below the current amount.

description and metadata replace the current values, and only when present in the request. Sending amount alone clears neither.

Response

{
  "payment_intent": {
    "id": "pi_01HZ3X9YQ7M8KH8M5JYV9X4F2B",
    "amount": 150000,
    "amount_capturable": 150000,
    "amount_received": 0,
    "status": "requires_capture"
  }
}

On success amount and amount_capturable both rise by the difference, and amount_received is untouched. The PaymentIntent stays in requires_capture — an increment moves amounts, not state — so there is no new status webhook to wait for. Capture the raised total with CapturePaymentIntent as usual.

Worked Example

A hotel authorizes one night up front, the guest extends by a night, and the full stay is captured at checkout.

Step	Call	amount	amount_capturable	amount_received	Status
Check-in	Create + confirm with request_incremental_authorization: if_available, capture_method: manual	100000	100000	0	requires_capture
Guest extends	increment_authorization with { "amount": 150000 }	150000	150000	0	requires_capture
Checkout	capture with {} (full, final)	150000	0	150000	succeeded

The capture is an ordinary one — nothing about it is increment-specific. If the guest's final bill came to less than the raised total, capture the lower amount with final_capture: true and the remainder is released. See Partial and Final Capture.

Errors

Rejected request	Reason
amount equal to or below the current amount	amount is the new total, not a delta, and must increase.
The PaymentIntent is not requires_capture, or its charge is already captured	There is no live authorization to raise.
capture_method is not manual	Increments apply only to the manual-capture flow.
request_incremental_authorization was not if_available at create or confirm	Eligibility is decided at authorization time and cannot be added afterwards. Start a new payment with the option set.
The payment method is card_present, napas_qr, or cake_pay	Card (card-not-present) payments only.
An 11th increment on the same charge	At most 10 increments per charge.

Related

• Manual Capture — the flow this builds on, including partial and final capture
• Controlling 3DS — the other payment_method_options.card option