[BUG] [Payments]: refund_uncaptured_amount is published on the capture API but nothing reads it

Bug Description

PaymentsCaptureRequest.refund_uncaptured_amount is declared in the API model and published in the v1 OpenAPI spec, but nothing reads it. Sending true, sending false, and omitting the field are indistinguishable.

Declared at crates/api_models/src/payments.rs#L6747-L6749:

/// Decider to refund the uncaptured amount. (Currently not fully supported or behavior may vary by connector).
pub refund_uncaptured_amount: Option<bool>,

It is also in api-reference/v1/openapi_spec_v1.json on PaymentsCaptureRequest, typed boolean and nullable.

The capture handler never mentions it: crates/router/src/core/payments/operations/payment_capture.rs has zero occurrences of the identifier. The only other occurrence in the repo is crates/router/src/core/fraud_check/operation/fraud_check_post.rs, which writes None when constructing a capture request. There is no reader in crates/router, crates/hyperswitch_domain_models, crates/hyperswitch_connectors, or crates/common_enums.

What decides the uncaptured remainder today is capture_method: manual sets amount_capturable to zero and the intent to the terminal partially_captured, while manual_multiple keeps the remainder capturable.

Expected Behavior

Either the field is honored at capture time, or it is removed from the request model and the published spec so integrators do not write it into their code expecting an effect.

Actual Behavior

The field is accepted and silently ignored. Its doc comment ("Currently not fully supported or behavior may vary by connector") reads as connector variance, but no connector sees it either, since nothing reads it into a connector request.

Steps To Reproduce

1. Create a payment with capture_method: manual and authorize it.
2. Capture part of the amount with refund_uncaptured_amount: true.
3. Repeat with false, and again with the field omitted.
4. All three behave identically: the remainder is not refunded by this field, and the payment reaches partially_captured with amount_capturable zero.

Context For The Bug

Found while documenting manual capture for the docs (juspay/hyperswitch-docs#272). "What does refund_uncaptured_amount default to?" is one of the most common capture questions in our support data, and the honest answer is that it does nothing. The docs page says so; a tracking issue would let it link the plan instead.

This is code inspection, not an executed test.

Environment

Code inspection at main (5fb7e5598eadd8ed5fa42822427107f271a1e112); also present at 184ffd4c015fd3fea2f3868549f1a86ffa5f40da.

Have you spent some time checking if this bug has been raised before?

• I checked and didn't find a similar issue