Issue:
Bug: docs: API reference improvements



API Reference needed some context on the payments flows, and improvements in some descriptions.

Pull request description:
## Type of Change
<!-- Put an `x` in the boxes that apply -->

- [ ] Bugfix
- [ ] New feature
- [ ] Enhancement
- [ ] Refactoring
- [ ] Dependency updates
- [X] Documentation
- [ ] CI/CD

## Description
<!-- Describe your changes in detail -->
Improving API-Reference to include payment flows, and include better and correct description of some fields.
### Additional Changes

- [ ] This PR modifies the API contract
- [ ] This PR modifies the database schema
- [ ] This PR modifies application configuration/environment variables

<!--
Provide links to the files with corresponding changes.

Following are the paths where you can find config files:
1. `config`
2. `crates/router/src/configs`
3. `loadtest/config`
-->


## Motivation and Context
<!--
Why is this change required? What problem does it solve?
If it fixes an open issue, please link to the issue here.

If you don't have an issue, we'd recommend starting with one first so the PR
can focus on the implementation (unless it is an obvious bug or documentation fix
that will have little conversation).
-->


## How did you test it?
<!--
Did you write an integration/unit/API test to verify the code changes?
Or did you test this change manually (provide relevant screenshots)?
-->


## Checklist
<!-- Put an `x` in the boxes that apply -->

- [ ] I formatted the code `cargo +nightly fmt --all`
- [ ] I addressed lints thrown by `cargo clippy`
- [ ] I reviewed the submitted code
- [ ] I added unit tests for my changes where possible


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

- **Documentation**
  - Introduced a comprehensive "Payment Flows" API reference covering payment processing patterns, one-time and recurring payments, and flow diagrams.
  - Enhanced OpenAPI specifications with clearer endpoint and schema descriptions, improved field explanations, and expanded example requests and responses.
  - Updated sidebar metadata and icons for setup instructions.
  - Added a new documentation site configuration file with structured navigation, theming, and integrations.
  - Removed legacy API documentation configuration file.
  - Improved in-code documentation for payment models and endpoints to clarify field usage and API behaviors.
  - Refined descriptive text in API schemas for addresses, captures, payment attempts, and payment methods to improve clarity and precision.
  - Expanded and clarified enum documentation for payment authentication, capture methods, currency codes, intent statuses, and future usage.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Testing:

Patch:
diff --git a/api-reference-v2/openapi_spec.json b/api-reference-v2/openapi_spec.json
index d88111cc43e..09346e388fd 100644
--- a/api-reference-v2/openapi_spec.json
+++ b/api-reference-v2/openapi_spec.json
@@ -3990,7 +3990,7 @@
         "properties": {
           "city": {
             "type": "string",
-            "description": "The address city",
+            "description": "The city, district, suburb, town, or village of the address.",
             "example": "New York",
             "nullable": true,
             "maxLength": 50
@@ -4005,21 +4005,21 @@
           },
           "line1": {
             "type": "string",
-            "description": "The first line of the address",
+            "description": "The first line of the street address or P.O. Box.",
             "example": "123, King Street",
             "nullable": true,
             "maxLength": 200
           },
           "line2": {
             "type": "string",
-            "description": "The second line of the address",
+            "description": "The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).",
             "example": "Powelson Avenue",
             "nullable": true,
             "maxLength": 50
           },
           "line3": {
             "type": "string",
-            "description": "The third line of the address",
+            "description": "The third line of the street address, if applicable.",
             "example": "Bridgewater",
             "nullable": true,
             "maxLength": 50
@@ -4899,7 +4899,7 @@
       },
       "AuthenticationType": {
         "type": "string",
-        "description": "Pass this parameter to force 3DS or non 3DS auth for this payment. Some connectors will still force 3DS auth even in case of passing 'no_three_ds' here and vice versa. Default value is 'no_three_ds' if not set",
+        "description": "Specifies the type of cardholder authentication to be applied for a payment.\n\n- `ThreeDs`: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.\n- `NoThreeDs`: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.\n\nNote: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.",
         "enum": [
           "three_ds",
           "no_three_ds"
@@ -7081,7 +7081,7 @@
       },
       "CaptureMethod": {
         "type": "string",
-        "description": "Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors",
+        "description": "Specifies how the payment is captured.\n- `automatic`: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.\n- `manual`: Funds are authorized but not captured. A separate request to the `/payments/{payment_id}/capture` endpoint is required to capture the funds.",
         "enum": [
           "automatic",
           "manual",
@@ -7103,7 +7103,7 @@
         "properties": {
           "capture_id": {
             "type": "string",
-            "description": "Unique identifier for the capture"
+            "description": "A unique identifier for this specific capture operation."
           },
           "status": {
             "$ref": "#/components/schemas/CaptureStatus"
@@ -7124,11 +7124,11 @@
           },
           "connector": {
             "type": "string",
-            "description": "The connector used for the payment"
+            "description": "The name of the payment connector that processed this capture."
           },
           "authorized_attempt_id": {
             "type": "string",
-            "description": "Unique identifier for the parent attempt on which this capture is made"
+            "description": "The ID of the payment attempt that was successfully authorized and subsequently captured by this operation."
           },
           "connector_capture_id": {
             "type": "string",
@@ -7142,22 +7142,22 @@
           },
           "error_message": {
             "type": "string",
-            "description": "If there was an error while calling the connector the error message is received here",
+            "description": "A human-readable message from the connector explaining why this capture operation failed, if applicable.",
             "nullable": true
           },
           "error_code": {
             "type": "string",
-            "description": "If there was an error while calling the connectors the code is received here",
+            "description": "The error code returned by the connector if this capture operation failed. This code is connector-specific.",
             "nullable": true
           },
           "error_reason": {
             "type": "string",
-            "description": "If there was an error while calling the connectors the reason is received here",
+            "description": "A more detailed reason from the connector explaining the capture failure, if available.",
             "nullable": true
           },
           "reference_id": {
             "type": "string",
-            "description": "Reference to the capture at connector side",
+            "description": "The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.",
             "nullable": true
           }
         }
@@ -9148,7 +9148,7 @@
       },
       "Currency": {
         "type": "string",
-        "description": "The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.",
+        "description": "The three-letter ISO 4217 currency code (e.g., \"USD\", \"EUR\") for the payment amount. This field is mandatory for creating a payment.",
         "enum": [
           "AED",
           "AFN",
@@ -11308,7 +11308,7 @@
       },
       "FutureUsage": {
         "type": "string",
-        "description": "Indicates that you intend to make future payments with the payment methods used for this Payment. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete.\n- On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment\n- Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.",
+        "description": "Specifies how the payment method can be used for future payments.\n- `off_session`: The payment method can be used for future payments when the customer is not present.\n- `on_session`: The payment method is intended for use only when the customer is present during checkout.\nIf omitted, defaults to `on_session`.",
         "enum": [
           "off_session",
           "on_session"
@@ -12364,7 +12364,7 @@
       },
       "IntentStatus": {
         "type": "string",
-        "description": "The status of the current payment that was made",
+        "description": "Represents the overall status of a payment intent.\nThe status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).",
         "enum": [
           "succeeded",
           "failed",
@@ -17959,7 +17959,6 @@
           },
           "payment_token": {
             "type": "string",
-            "description": "Provide a reference to a stored payment method",
             "example": "187282ab-40ef-47a9-9206-5099ba31e432",
             "nullable": true
           }
@@ -24028,6 +24027,7 @@
       },
       "ThreeDsCompletionIndicator": {
         "type": "string",
+        "description": "Indicates if 3DS method data was successfully completed or not",
         "enum": [
           "Y",
           "N",
diff --git a/crates/api_models/src/payments.rs b/crates/api_models/src/payments.rs
index 4a0069baa6e..eb153ff9cd1 100644
--- a/crates/api_models/src/payments.rs
+++ b/crates/api_models/src/payments.rs
@@ -73,7 +73,6 @@ pub struct ConnectorCode {
     pub connector: api_enums::Connector,
     pub code: String,
 }
-
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema, PartialEq, Eq)]
 pub struct BankCodeResponse {
     #[schema(value_type = Vec<BankNames>)]
@@ -852,23 +851,23 @@ impl AmountDetailsUpdate {
 #[generate_schemas(PaymentsCreateRequest, PaymentsUpdateRequest, PaymentsConfirmRequest)]
 #[serde(deny_unknown_fields)]
 pub struct PaymentsRequest {
-    /// The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the Decimal and Non-Decimal Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies)
+    /// The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.
     #[schema(value_type = Option<u64>, example = 6540)]
     #[serde(default, deserialize_with = "amount::deserialize_option")]
     #[mandatory_in(PaymentsCreateRequest = u64)]
     // Makes the field mandatory in PaymentsCreateRequest
     pub amount: Option<Amount>,
 
-    /// Total tax amount applicable to the order
+    /// Total tax amount applicable to the order, in the lowest denomination of the currency.
     #[schema(value_type = Option<i64>, example = 6540)]
     pub order_tax_amount: Option<MinorUnit>,
 
-    /// The three letter ISO currency code in uppercase. Eg: 'USD' to charge US Dollars
+    /// The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
     #[schema(example = "USD", value_type = Option<Currency>)]
     #[mandatory_in(PaymentsCreateRequest = Currency)]
     pub currency: Option<api_enums::Currency>,
 
-    /// The Amount to be captured / debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. Also, it must be less than or equal to the original payment account.
+    /// The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and `capture_method` is `automatic`, the full payment `amount` will be captured. If `capture_method` is `manual`, this can be specified in the `/capture` call. Must be less than or equal to the authorized amount.
     #[schema(value_type = Option<i64>, example = 6540)]
     pub amount_to_capture: Option<MinorUnit>,
 
@@ -876,8 +875,7 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<i64>, example = 6540)]
     pub shipping_cost: Option<MinorUnit>,
 
-    /// Unique identifier for the payment. This ensures idempotency for multiple payments
-    /// that have been done by a single merchant. The value for this field can be specified in the request, it will be auto generated otherwise and returned in the API response.
+    /// Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.
     #[schema(
         value_type = Option<String>,
         min_length = 30,
@@ -920,7 +918,7 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub capture_on: Option<PrimitiveDateTime>,
 
-    /// Whether to confirm the payment (if applicable). It can be used to completely process a payment by attaching a payment method, setting `confirm=true` and `capture_method = automatic` in the *Payments/Create API* request itself.
+    /// If set to `true`, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If `false` or omitted (default is `false`), the payment is created with a status such as `requires_payment_method` or `requires_confirmation`, and a separate `POST /payments/{payment_id}/confirm` call is necessary to proceed with authorization.
     #[schema(default = false, example = true)]
     pub confirm: Option<bool>,
 
@@ -959,11 +957,11 @@ pub struct PaymentsRequest {
     #[schema(example = true)]
     pub off_session: Option<bool>,
 
-    /// A description for the payment
+    /// An arbitrary string attached to the payment. Often useful for displaying to users or for your own internal record-keeping.
     #[schema(example = "It's my first payment request")]
     pub description: Option<String>,
 
-    /// The URL to which you want the user to be redirected after the completion of the payment operation
+    /// The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).
     #[schema(value_type = Option<String>, example = "https://hyperswitch.io", max_length = 2048)]
     pub return_url: Option<Url>,
 
@@ -1136,9 +1134,7 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<bool>, default = false)]
     pub request_extended_authorization: Option<RequestExtendedAuthorizationBool>,
 
-    /// Merchant's identifier for the payment/invoice. This will be sent to the connector
-    /// if the connector provides support to accept multiple reference ids.
-    /// In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.
+    /// Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.
     #[schema(
         value_type = Option<String>,
         max_length = 255,
@@ -1472,7 +1468,7 @@ impl RequestSurchargeDetails {
 #[cfg(feature = "v1")]
 #[derive(Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema)]
 pub struct PaymentAttemptResponse {
-    /// Unique identifier for the attempt
+    /// A unique identifier for this specific payment attempt.
     pub attempt_id: String,
     /// The status of the attempt
     #[schema(value_type = AttemptStatus, example = "charged")]
@@ -1486,9 +1482,9 @@ pub struct PaymentAttemptResponse {
     /// The currency of the amount of the payment attempt
     #[schema(value_type = Option<Currency>, example = "USD")]
     pub currency: Option<enums::Currency>,
-    /// The connector used for the payment
+    /// The name of the payment connector (e.g., 'stripe', 'adyen') used for this attempt.
     pub connector: Option<String>,
-    /// If there was an error while calling the connector, the error message is received here
+    /// A human-readable message from the connector explaining the error, if one occurred during this payment attempt.
     pub error_message: Option<String>,
     /// The payment method that is to be used
     #[schema(value_type = Option<PaymentMethod>, example = "bank_transfer")]
@@ -1511,11 +1507,11 @@ pub struct PaymentAttemptResponse {
     pub modified_at: PrimitiveDateTime,
     /// If the payment was cancelled the reason will be provided here
     pub cancellation_reason: Option<String>,
-    /// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
+    /// If this payment attempt is associated with a mandate (e.g., for a recurring or subsequent payment), this field will contain the ID of that mandate.
     pub mandate_id: Option<String>,
-    /// If there was an error while calling the connectors the error code is received here
+    /// The error code returned by the connector if this payment attempt failed. This code is specific to the connector.
     pub error_code: Option<String>,
-    /// Provide a reference to a stored payment method
+    /// If a tokenized (saved) payment method was used for this attempt, this field contains the payment token representing that payment method.
     pub payment_token: Option<String>,
     /// Additional data related to some connectors
     pub connector_metadata: Option<serde_json::Value>,
@@ -1525,7 +1521,7 @@ pub struct PaymentAttemptResponse {
     /// Payment Method Type
     #[schema(value_type = Option<PaymentMethodType>, example = "google_pay")]
     pub payment_method_type: Option<enums::PaymentMethodType>,
-    /// Reference to the payment at connector side
+    /// The connector's own reference or transaction ID for this specific payment attempt. Useful for reconciliation with the connector.
     #[schema(value_type = Option<String>, example = "993672945374576J")]
     pub reference_id: Option<String>,
     /// (This field is not live yet)Error code unified across the connectors is received here if there was an error while calling connector
@@ -1647,7 +1643,7 @@ pub struct PaymentAttemptRevenueRecoveryData {
     Default, Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema,
 )]
 pub struct CaptureResponse {
-    /// Unique identifier for the capture
+    /// A unique identifier for this specific capture operation.
     pub capture_id: String,
     /// The status of the capture
     #[schema(value_type = CaptureStatus, example = "charged")]
@@ -1658,21 +1654,21 @@ pub struct CaptureResponse {
     /// The currency of the amount of the capture
     #[schema(value_type = Option<Currency>, example = "USD")]
     pub currency: Option<enums::Currency>,
-    /// The connector used for the payment
+    /// The name of the payment connector that processed this capture.
     pub connector: String,
-    /// Unique identifier for the parent attempt on which this capture is made
+    /// The ID of the payment attempt that was successfully authorized and subsequently captured by this operation.
     pub authorized_attempt_id: String,
     /// A unique identifier for this capture provided by the connector
     pub connector_capture_id: Option<String>,
     /// Sequence number of this capture, in the series of captures made for the parent attempt
     pub capture_sequence: i16,
-    /// If there was an error while calling the connector the error message is received here
+    /// A human-readable message from the connector explaining why this capture operation failed, if applicable.
     pub error_message: Option<String>,
-    /// If there was an error while calling the connectors the code is received here
+    /// The error code returned by the connector if this capture operation failed. This code is connector-specific.
     pub error_code: Option<String>,
-    /// If there was an error while calling the connectors the reason is received here
+    /// A more detailed reason from the connector explaining the capture failure, if available.
     pub error_reason: Option<String>,
-    /// Reference to the capture at connector side
+    /// The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.
     pub reference_id: Option<String>,
 }
 
@@ -4314,23 +4310,23 @@ impl Address {
 #[derive(Clone, Default, Debug, Eq, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct AddressDetails {
-    /// The address city
+    /// The city, district, suburb, town, or village of the address.
     #[schema(max_length = 50, example = "New York")]
     pub city: Option<String>,
 
-    /// The two-letter ISO country code for the address
+    /// The two-letter ISO 3166-1 alpha-2 country code (e.g., US, GB).
     #[schema(value_type = Option<CountryAlpha2>, example = "US")]
     pub country: Option<api_enums::CountryAlpha2>,
 
-    /// The first line of the address
+    /// The first line of the street address or P.O. Box.
     #[schema(value_type = Option<String>, max_length = 200, example = "123, King Street")]
     pub line1: Option<Secret<String>>,
 
-    /// The second line of the address
+    /// The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
     #[schema(value_type = Option<String>, max_length = 50, example = "Powelson Avenue")]
     pub line2: Option<Secret<String>>,
 
-    /// The third line of the address
+    /// The third line of the street address, if applicable.
     #[schema(value_type = Option<String>, max_length = 50, example = "Bridgewater")]
     pub line3: Option<Secret<String>>,
 
@@ -4424,22 +4420,22 @@ pub struct PhoneDetails {
 #[cfg(feature = "v1")]
 #[derive(Debug, Clone, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, ToSchema)]
 pub struct PaymentsCaptureRequest {
-    /// The unique identifier for the payment
+    /// The unique identifier for the payment being captured. This is taken from the path parameter.
     #[serde(skip_deserializing)]
     pub payment_id: id_type::PaymentId,
-    /// The unique identifier for the merchant
+    /// The unique identifier for the merchant. This is usually inferred from the API key.
     #[schema(value_type = Option<String>)]
     pub merchant_id: Option<id_type::MerchantId>,
-    /// The Amount to be captured/ debited from the user's payment method. If not passed the full amount will be captured.
-    #[schema(value_type = i64, example = 6540)]
+    /// The amount to capture, in the lowest denomination of the currency. If omitted, the entire `amount_capturable` of the payment will be captured. Must be less than or equal to the current `amount_capturable`.
+    #[schema(value_type = Option<i64>, example = 6540)]
     pub amount_to_capture: Option<MinorUnit>,
-    /// Decider to refund the uncaptured amount
+    /// Decider to refund the uncaptured amount. (Currently not fully supported or behavior may vary by connector).
     pub refund_uncaptured_amount: Option<bool>,
-    /// Provides information about a card payment that customers see on their statements.
+    /// A dynamic suffix that appears on your customer's credit card statement. This is concatenated with the (shortened) descriptor prefix set on your account to form the complete statement descriptor. The combined length should not exceed connector-specific limits (typically 22 characters).
     pub statement_descriptor_suffix: Option<String>,
-    /// Concatenated with the statement descriptor suffix that’s set on the account to form the complete statement descriptor.
+    /// An optional prefix for the statement descriptor that appears on your customer's credit card statement. This can override the default prefix set on your merchant account. The combined length of prefix and suffix should not exceed connector-specific limits (typically 22 characters).
     pub statement_descriptor_prefix: Option<String>,
-    /// Merchant connector details used to make payments.
+    /// Merchant connector details used to make payments. (Deprecated)
     #[schema(value_type = Option<MerchantConnectorDetailsWrap>, deprecated)]
     pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
 }
@@ -4824,28 +4820,28 @@ pub struct PaymentsResponse {
     #[schema(value_type = Option<i64>, example = 6540)]
     pub shipping_cost: Option<MinorUnit>,
 
-    /// The maximum amount that could be captured from the payment
+    /// The amount (in minor units) that can still be captured for this payment. This is relevant when `capture_method` is `manual`. Once fully captured, or if `capture_method` is `automatic` and payment succeeded, this will be 0.
     #[schema(value_type = i64, minimum = 100, example = 6540)]
     pub amount_capturable: MinorUnit,
 
-    /// The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.
+    /// The total amount (in minor units) that has been captured for this payment. For `fauxpay` sandbox connector, this might reflect the authorized amount if `status` is `succeeded` even if `capture_method` was `manual`.
     #[schema(value_type = Option<i64>, example = 6540)]
     pub amount_received: Option<MinorUnit>,
 
-    /// The connector used for the payment
+    /// The name of the payment connector (e.g., 'stripe', 'adyen') that processed or is processing this payment.
     #[schema(example = "stripe")]
     pub connector: Option<String>,
 
-    /// It's a token used for client side verification.
+    /// A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.
     #[schema(value_type = Option<String>, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
     pub client_secret: Option<Secret<String>>,
 
-    /// Time when the payment was created
+    /// Timestamp indicating when this payment intent was created, in ISO 8601 format.
     #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(with = "common_utils::custom_serde::iso8601::option")]
     pub created: Option<PrimitiveDateTime>,
 
-    /// The currency of the amount of the payment
+    /// Three-letter ISO currency code (e.g., USD, EUR) for the payment amount.
     #[schema(value_type = Currency, example = "USD")]
     pub currency: String,
 
@@ -4862,11 +4858,11 @@ pub struct PaymentsResponse {
 
     pub customer: Option<CustomerDetailsResponse>,
 
-    /// A description of the payment
+    /// An arbitrary string providing a description for the payment, often useful for display or internal record-keeping.
     #[schema(example = "It's my first payment request")]
     pub description: Option<String>,
 
-    /// List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order
+    /// An array of refund objects associated with this payment. Empty or null if no refunds have been processed.
     #[schema(value_type = Option<Vec<RefundResponse>>)]
     pub refunds: Option<Vec<refunds::RefundResponse>>,
 
@@ -4968,17 +4964,17 @@ pub struct PaymentsResponse {
     #[schema(max_length = 255, example = "Payment for shoes purchase")]
     pub statement_descriptor_suffix: Option<String>,
 
-    /// Additional information required for redirection
+    /// If the payment requires further action from the customer (e.g., 3DS authentication, redirect to a bank page), this object will contain the necessary information for the client to proceed. Null if no further action is needed from the customer at this stage.
     pub next_action: Option<NextActionData>,
 
-    /// If the payment was cancelled the reason will be provided here
+    /// If the payment intent was cancelled, this field provides a textual reason for the cancellation (e.g., "requested_by_customer", "abandoned").
     pub cancellation_reason: Option<String>,
 
-    /// If there was an error while calling the connectors the code is received here
+    /// The connector-specific error code from the last failed payment attempt associated with this payment intent.
     #[schema(example = "E0001")]
     pub error_code: Option<String>,
 
-    /// If there was an error while calling the connector the error message is received here
+    /// A human-readable error message from the last failed payment attempt associated with this payment intent.
     #[schema(example = "Failed while verifying the card")]
     pub error_message: Option<String>,
 
@@ -4990,26 +4986,26 @@ pub struct PaymentsResponse {
     #[remove_in(PaymentsCreateResponseOpenApi)]
     pub unified_message: Option<String>,
 
-    /// Payment Experience for the current payment
+    /// Describes the type of payment flow experienced by the customer (e.g., 'redirect_to_url', 'invoke_sdk', 'display_qr_code').
     #[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
     pub payment_experience: Option<api_enums::PaymentExperience>,
 
-    /// Can be used to specify the Payment Method Type
+    /// The specific payment method subtype used for this payment (e.g., 'credit_card', 'klarna', 'gpay'). This provides more granularity than the 'payment_method' field.
     #[schema(value_type = Option<PaymentMethodType>, example = "gpay")]
     pub payment_method_type: Option<api_enums::PaymentMethodType>,
 
-    /// The connector used for this payment along with the country and business details
+    /// A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").
     #[schema(example = "stripe_US_food")]
     pub connector_label: Option<String>,
 
-    /// The business country of merchant for this payment
+    /// The two-letter ISO country code (e.g., US, GB) of the business unit or profile under which this payment was processed.
     #[schema(value_type = Option<CountryAlpha2>, example = "US")]
     pub business_country: Option<api_enums::CountryAlpha2>,
 
-    /// The business label of merchant for this payment
+    /// The label identifying the specific business unit or profile under which this payment was processed by the merchant.
     pub business_label: Option<String>,
 
-    /// The business_sub_label for this payment
+    /// An optional sub-label for further categorization of the business unit or profile used for this payment.
     pub business_sub_label: Option<String>,
 
     /// Allowed Payment Method Types for a given PaymentIntent
@@ -5092,7 +5088,7 @@ pub struct PaymentsResponse {
     /// The browser information used for this payment
     pub browser_info: Option<serde_json::Value>,
 
-    /// Identifier for Payment Method used for the payment
+    /// A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments.
     pub payment_method_id: Option<String>,
 
     /// Payment Method Status, refers to the status of the payment method used for this payment.
@@ -5330,7 +5326,6 @@ pub struct PaymentsConfirmIntentRequest {
     #[schema(value_type = Option<String>)]
     pub payment_method_id: Option<id_type::GlobalPaymentMethodId>,
 
-    /// Provide a reference to a stored payment method
     #[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
     pub payment_token: Option<String>,
 }
@@ -6414,9 +6409,9 @@ pub struct PaymentsRetrieveRequest {
     pub merchant_id: Option<id_type::MerchantId>,
     /// Decider to enable or disable the connector call for retrieve request
     pub force_sync: bool,
-    /// The parameters passed to a retrieve request
+    /// Optional query parameters that might be specific to a connector or flow, passed through during the retrieve operation. Use with caution and refer to specific connector documentation if applicable.
     pub param: Option<String>,
-    /// The name of the connector
+    /// Optionally specifies the connector to be used for a 'force_sync' retrieve operation. If provided, Hyperswitch will attempt to sync the payment status from this specific connector.
     pub connector: Option<String>,
     /// Merchant connector details used to make payments.
     #[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
@@ -7563,6 +7558,7 @@ pub struct PaymentsManualUpdateResponse {
 }
 
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
+/// Indicates if 3DS method data was successfully completed or not
 pub enum ThreeDsCompletionIndicator {
     /// 3DS method successfully completed
     #[serde(rename = "Y")]
diff --git a/crates/common_enums/src/enums.rs b/crates/common_enums/src/enums.rs
index 57b119b8d11..893a3b7dafa 100644
--- a/crates/common_enums/src/enums.rs
+++ b/crates/common_enums/src/enums.rs
@@ -241,7 +241,12 @@ pub enum RevenueRecoveryAlgorithmType {
     Cascading,
 }
 
-/// Pass this parameter to force 3DS or non 3DS auth for this payment. Some connectors will still force 3DS auth even in case of passing 'no_three_ds' here and vice versa. Default value is 'no_three_ds' if not set
+/// Specifies the type of cardholder authentication to be applied for a payment.
+///
+/// - `ThreeDs`: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
+/// - `NoThreeDs`: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.
+///
+/// Note: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.
 #[derive(
     Clone,
     Copy,
@@ -395,7 +400,9 @@ pub enum BlocklistDataKind {
     ExtendedCardBin,
 }
 
-/// Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors
+/// Specifies how the payment is captured.
+/// - `automatic`: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
+/// - `manual`: Funds are authorized but not captured. A separate request to the `/payments/{payment_id}/capture` endpoint is required to capture the funds.
 #[derive(
     Clone,
     Copy,
@@ -416,16 +423,16 @@ pub enum BlocklistDataKind {
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum CaptureMethod {
-    /// Post the payment authorization, the capture will be executed on the full amount immediately
+    /// Post the payment authorization, the capture will be executed on the full amount immediately.
     #[default]
     Automatic,
-    /// The capture will happen only if the merchant triggers a Capture API request
+    /// The capture will happen only if the merchant triggers a Capture API request. Allows for a single capture of the authorized amount.
     Manual,
-    /// The capture will happen only if the merchant triggers a Capture API request
+    /// The capture will happen only if the merchant triggers a Capture API request. Allows for multiple partial captures up to the authorized amount.
     ManualMultiple,
-    /// The capture can be scheduled to automatically get triggered at a specific date & time
+    /// The capture can be scheduled to automatically get triggered at a specific date & time.
     Scheduled,
-    /// Handles separate auth and capture sequentially; same as `Automatic` for most connectors.
+    /// Handles separate auth and capture sequentially; effectively the same as `Automatic` for most connectors.
     SequentialAutomatic,
 }
 
@@ -494,7 +501,7 @@ pub enum CallConnectorAction {
     HandleResponse(Vec<u8>),
 }
 
-/// The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.
+/// The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
 #[allow(clippy::upper_case_acronyms)]
 #[derive(
     Clone,
@@ -1555,7 +1562,8 @@ pub enum MerchantStorageScheme {
     RedisKv,
 }
 
-/// The status of the current payment that was made
+/// Represents the overall status of a payment intent.
+/// The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).
 #[derive(
     Clone,
     Copy,
@@ -1642,9 +1650,10 @@ impl IntentStatus {
     }
 }
 
-/// Indicates that you intend to make future payments with the payment methods used for this Payment. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete.
-/// - On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment
-/// - Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.
+/// Specifies how the payment method can be used for future payments.
+/// - `off_session`: The payment method can be used for future payments when the customer is not present.
+/// - `on_session`: The payment method is intended for use only when the customer is present during checkout.
+/// If omitted, defaults to `on_session`.
 #[derive(
     Clone,
     Copy,
diff --git a/crates/openapi/src/routes/payments.rs b/crates/openapi/src/routes/payments.rs
index ee659e1f707..6160b68b44b 100644
--- a/crates/openapi/src/routes/payments.rs
+++ b/crates/openapi/src/routes/payments.rs
@@ -1,24 +1,8 @@
 /// Payments - Create
 ///
-/// **Creates a payment object when amount and currency are passed.**
+/// Creates a payment resource, which represents a customer's intent to pay.
+/// This endpoint is the starting point for various payment flows:
 ///
-/// This API is also used to create a mandate by passing the `mandate_object`.
-///
-/// Depending on the user journey you wish to achieve, you may opt to complete all the steps in a single request **by attaching a payment method, setting `confirm=true` and `capture_method = automatic`** in the *Payments/Create API* request.
-///
-/// Otherwise, To completely process a payment you will have to **create a payment, attach a payment method, confirm and capture funds**. For that you could use the following sequence of API requests -
-///
-/// 1. Payments - Create
-///
-/// 2. Payments - Update
-///
-/// 3. Payments - Confirm
-///
-/// 4. Payments - Capture.
-///
-/// You will require the 'API - Key' from the Hyperswitch dashboard to make the first call, and use the 'client secret' returned in this API along with your 'publishable key' to make subsequent API calls from your client.
-///
-/// This page lists the various combinations in which the Payments - Create API can be used and the details about the various fields in the requests and responses.
 #[utoipa::path(
     post,
     path = "/payments",
@@ -26,12 +10,12 @@
         content = PaymentsCreateRequest,
         examples(
             (
-                "Create a payment with minimal fields" = (
+                "1. Create a payment with minimal fields" = (
                     value = json!({"amount": 6540,"currency": "USD"})
                 )
             ),
             (
-                "Create a payment with customer details and metadata" = (
+                "2. Create a payment with customer details and metadata" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -53,7 +37,7 @@
                 )
             ),
             (
-                "Create a 3DS payment" = (
+                "3. Create a 3DS payment" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -62,7 +46,7 @@
                 )
             ),
             (
-                "Create a manual capture payment" = (
+                "4. Create a manual capture payment (basic)" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -71,7 +55,7 @@
                 )
             ),
             (
-                "Create a setup mandate payment" = (
+                "5. Create a setup mandate payment" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -117,7 +101,7 @@
                 )
             ),
             (
-                "Create a recurring payment with mandate_id" = (
+                "6. Create a recurring payment with mandate_id" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -130,7 +114,7 @@
                 )
             ),
             (
-                "Create a payment and save the card" = (
+                "7. Create a payment and save the card" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -160,7 +144,7 @@
                 )
             ),
             (
-                "Create a payment using an already saved card's token" = (
+                "8. Create a payment using an already saved card's token" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -173,7 +157,7 @@
                 )
             ),
             (
-                "Create a manual capture payment" = (
+                "9. Create a payment with billing details" = (
                     value = json!({
                     "amount": 6540,
                     "currency": "USD",
@@ -203,7 +187,222 @@
         ),
     ),
     responses(
-        (status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi),
+        (status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi,
+            examples(
+                ("1. Response for minimal payment creation (requires payment method)" = (
+                    value = json!({
+                        "payment_id": "pay_syxxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "requires_payment_method",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "client_secret": "pay_syxxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:00:00Z",
+                        "amount_capturable": 6540,
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "expires_on": "2023-10-26T10:15:00Z"
+                    })
+                )),
+                ("2. Response for payment with customer details (requires payment method)" = (
+                    value = json!({
+                        "payment_id": "pay_custmeta_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "requires_payment_method",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "customer_id": "cus_abcdefgh",
+                        "customer": {
+                            "id": "cus_abcdefgh",
+                            "name": "John Dough",
+                            "email": "john@example.com",
+                            "phone": "9123456789"
+                        },
+                        "description": "Its my first payment request",
+                        "statement_descriptor_name": "joseph",
+                        "statement_descriptor_suffix": "JS",
+                        "metadata": {
+                            "udf1": "some-value",
+                            "udf2": "some-value"
+                        },
+                        "client_secret": "pay_custmeta_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:05:00Z",
+                        "ephemeral_key": {
+                            "customer_id": "cus_abcdefgh",
+                            "secret": "epk_ephemeralxxxxxxxxxxxx"
+                        },
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "expires_on": "2023-10-26T10:20:00Z"
+                    })
+                )),
+                ("3. Response for 3DS payment creation (requires payment method)" = (
+                    value = json!({
+                        "payment_id": "pay_3ds_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "requires_payment_method",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "authentication_type": "three_ds",
+                        "client_secret": "pay_3ds_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:10:00Z",
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "expires_on": "2023-10-26T10:25:00Z"
+                    })
+                )),
+                ("4. Response for basic manual capture payment (requires payment method)" = (
+                    value = json!({
+                        "payment_id": "pay_manualcap_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "requires_payment_method",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "capture_method": "manual",
+                        "client_secret": "pay_manualcap_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:15:00Z",
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "expires_on": "2023-10-26T10:30:00Z"
+                    })
+                )),
+                ("5. Response for successful setup mandate payment" = (
+                    value = json!({
+                        "payment_id": "pay_mandatesetup_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "succeeded",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "amount_capturable": 0,
+                        "amount_received": 6540,
+                        "connector": "fauxpay",
+                        "customer_id": "StripeCustomer123",
+                        "mandate_id": "man_xxxxxxxxxxxx",
+                        "mandate_data": {
+                            "customer_acceptance": {
+                                "acceptance_type": "online",
+                                "accepted_at": "1963-05-03T04:07:52.723Z",
+                                "online": { "ip_address": "127.0.0.1", "user_agent": "amet irure esse" }
+                            },
+                            "mandate_type": { "single_use": { "amount": 6540, "currency": "USD" } }
+                        },
+                        "setup_future_usage": "on_session",
+                        "payment_method": "card",
+                        "payment_method_data": {
+                            "card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
+                        },
+                        "authentication_type": "no_three_ds",
+                        "client_secret": "pay_mandatesetup_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:20:00Z",
+                        "ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "merchant_connector_id": "mca_mcaconnectorxxxx",
+                        "connector_transaction_id": "txn_connectortransidxxxx"
+                    })
+                )),
+                ("6. Response for successful recurring payment with mandate_id" = (
+                    value = json!({
+                        "payment_id": "pay_recurring_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "succeeded",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "amount_capturable": 0,
+                        "amount_received": 6540,
+                        "connector": "fauxpay",
+                        "customer_id": "StripeCustomer",
+                        "mandate_id": "{{mandate_id}}",
+                        "off_session": true,
+                        "payment_method": "card",
+                        "authentication_type": "no_three_ds",
+                        "client_secret": "pay_recurring_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:22:00Z",
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "merchant_connector_id": "mca_mcaconnectorxxxx",
+                        "connector_transaction_id": "txn_connectortransidxxxx"
+                    })
+                )),
+                ("7. Response for successful payment with card saved" = (
+                    value = json!({
+                        "payment_id": "pay_savecard_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "succeeded",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "amount_capturable": 0,
+                        "amount_received": 6540,
+                        "connector": "fauxpay",
+                        "customer_id": "StripeCustomer123",
+                        "setup_future_usage": "on_session",
+                        "payment_method": "card",
+                        "payment_method_data": {
+                            "card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
+                        },
+                        "authentication_type": "no_three_ds",
+                        "client_secret": "pay_savecard_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:25:00Z",
+                        "ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "merchant_connector_id": "mca_mcaconnectorxxxx",
+                        "connector_transaction_id": "txn_connectortransidxxxx",
+                        "payment_token": null // Assuming payment_token is for subsequent use, not in this response.
+                    })
+                )),
+                ("8. Response for successful payment using saved card token" = (
+                    value = json!({
+                        "payment_id": "pay_token_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "succeeded",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "amount_capturable": 0,
+                        "amount_received": 6540,
+                        "connector": "fauxpay",
+                        "payment_method": "card",
+                        "payment_token": "{{payment_token}}",
+                        "client_secret": "pay_token_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:27:00Z",
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "merchant_connector_id": "mca_mcaconnectorxxxx",
+                        "connector_transaction_id": "txn_connectortransidxxxx"
+                    })
+                )),
+                ("9. Response for payment with billing details (requires payment method)" = (
+                    value = json!({
+                        "payment_id": "pay_manualbill_xxxxxxxxxxxx",
+                        "merchant_id": "merchant_myyyyyyyyyyyy",
+                        "status": "requires_payment_method",
+                        "amount": 6540,
+                        "currency": "USD",
+                        "customer_id": "cus_abcdefgh",
+                        "customer": {
+                            "id": "cus_abcdefgh",
+                            "name": "John Dough", 
+                            "email": "john@example.com", 
+                            "phone": "9123456789"
+                        },
+                        "billing": {
+                            "address": {
+                                "line1": "1467", "line2": "Harrison Street", "city": "San Fransico",
+                                "state": "California", "zip": "94122", "country": "US",
+                                "first_name": "joseph", "last_name": "Doe"
+                            },
+                            "phone": { "number": "9123456789", "country_code": "+91" }
+                        },
+                        "client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
+                        "created": "2023-10-26T10:30:00Z",
+                        "ephemeral_key": { "customer_id": "cus_abcdefgh", "secret": "epk_ephemeralxxxxxxxxxxxx" },
+                        "profile_id": "pro_pzzzzzzzzzzz",
+                        "attempt_count": 1,
+                        "expires_on": "2023-10-26T10:45:00Z"
+                    })
+                ))
+            )
+        ),
         (status = 400, description = "Missing Mandatory fields")
     ),
     tag = "Payments",
@@ -294,15 +493,12 @@ pub fn payments_update() {}
 
 /// Payments - Confirm
 ///
-/// **Use this API to confirm the payment and forward the payment to the payment processor.**
+/// Confirms a payment intent that was previously created with `confirm: false`. This action attempts to authorize the payment with the payment processor.
 ///
-/// Alternatively you can confirm the payment within the *Payments/Create* API by setting `confirm=true`. After confirmation, the payment could either:
-///
-/// 1. fail with `failed` status or
-///
-/// 2. transition to a `requires_customer_action` status with a `next_action` block or
-///
-/// 3. succeed with either `succeeded` in case of automatic capture or `requires_capture` in case of manual capture
+/// Expected status transitions after confirmation:
+/// - `succeeded`: If authorization is successful and `capture_method` is `automatic`.
+/// - `requires_capture`: If authorization is successful and `capture_method` is `manual`.
+/// - `failed`: If authorization fails.
 #[utoipa::path(
     post,
     path = "/payments/{payment_id}/confirm",
@@ -352,7 +548,13 @@ pub fn payments_confirm() {}
 
 /// Payments - Capture
 ///
-/// To capture the funds for an uncaptured payment
+/// Captures the funds for a previously authorized payment intent where `capture_method` was set to `manual` and the payment is in a `requires_capture` state.
+///
+/// Upon successful capture, the payment status usually transitions to `succeeded`.
+/// The `amount_to_capture` can be specified in the request body; it must be less than or equal to the payment's `amount_capturable`. If omitted, the full capturable amount is captured.
+///
+/// A payment must be in a capturable state (e.g., `requires_capture`). Attempting to capture an already `succeeded` (and fully captured) payment or one in an invalid state will lead to an error.
+///
 #[utoipa::path(
     post,
     path = "/payments/{payment_id}/capture",