Issue:
Bug: Updating the API reference documentation - payments



We have had feedback related to the API doc being outdated, and lacking proper visibility of the latest spec of the API collection.

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 -->


### 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).
-->
Partially closes #5174 

## 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


Testing:

Patch:
diff --git a/crates/api_models/src/payments.rs b/crates/api_models/src/payments.rs
index cd36c53a12b..2dc51a3783b 100644
--- a/crates/api_models/src/payments.rs
+++ b/crates/api_models/src/payments.rs
@@ -251,12 +251,12 @@ pub struct PaymentsRequest {
     #[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.
+    /// 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.
     #[schema(value_type = Option<i64>, example = 6540)]
     pub amount_to_capture: Option<MinorUnit>,
 
     /// Unique identifier for the payment. This ensures idempotency for multiple payments
-    /// that have been done by a single merchant. This field is auto generated and is returned in the API response.
+    /// 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.
     #[schema(
         value_type = Option<String>,
         min_length = 30,
@@ -272,13 +272,14 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub merchant_id: Option<String>,
 
+    /// Details of the routing configuration for that payment
     #[schema(value_type = Option<StraightThroughAlgorithm>, example = json!({
         "type": "single",
         "data": {"connector": "stripe", "merchant_connector_id": "mca_123"}
     }))]
     pub routing: Option<serde_json::Value>,
 
-    /// This allows to manually select a connector with which the payment can go through
+    /// This allows to manually select a connector with which the payment can go through.
     #[schema(value_type = Option<Vec<Connector>>, max_length = 255, example = json!(["stripe", "adyen"]))]
     pub connector: Option<Vec<api_enums::Connector>>,
 
@@ -298,7 +299,7 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub capture_on: Option<PrimitiveDateTime>,
 
-    /// Whether to confirm the payment (if applicable)
+    /// 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.
     #[schema(default = false, example = true)]
     pub confirm: Option<bool>,
 
@@ -341,7 +342,7 @@ pub struct PaymentsRequest {
     #[schema(example = "It's my first payment request")]
     pub description: Option<String>,
 
-    /// The URL to redirect after the completion of the operation
+    /// The URL to which you want the user to be redirected after the completion of the payment operation
     #[schema(value_type = Option<String>, example = "https://hyperswitch.io")]
     pub return_url: Option<Url>,
 
@@ -355,7 +356,7 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<PaymentMethod>, example = "card")]
     pub payment_method: Option<api_enums::PaymentMethod>,
 
-    /// Provide a reference to a stored payment method
+    /// As Hyperswitch tokenises the sensitive details about the payments method, it provides the payment_token as a reference to a stored payment method, ensuring that the sensitive details are not exposed in any manner.
     #[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
     pub payment_token: Option<String>,
 
@@ -392,7 +393,7 @@ pub struct PaymentsRequest {
     /// Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.
     pub mandate_data: Option<MandateData>,
 
-    /// We will be Passing this "CustomerAcceptance" object during Payments-Confirm. The customer_acceptance sub object is usually passed by the SDK or client
+    /// This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.
     #[schema(value_type = Option<CustomerAcceptance>)]
     pub customer_acceptance: Option<CustomerAcceptance>,
 
@@ -462,18 +463,17 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub feature_metadata: Option<FeatureMetadata>,
 
-    /// Whether to get the payment link (if applicable)
+    /// Whether to generate the payment link for this payment or not (if applicable)
     #[schema(default = false, example = true)]
     pub payment_link: Option<bool>,
 
     #[schema(value_type = Option<PaymentCreatePaymentLinkConfig>)]
     pub payment_link_config: Option<PaymentCreatePaymentLinkConfig>,
 
-    /// custom payment link config id set at business profile send only if business_specific_configs is configured
+    /// Custom payment link config id set at business profile, send only if business_specific_configs is configured
     pub payment_link_config_id: Option<String>,
 
-    /// The business profile to use for this payment, if not passed the default business profile
-    /// associated with the merchant account will be used.
+    /// The business profile to be used for this payment, if not passed the default business profile associated with the merchant account will be used. It is mandatory in case multiple business profiles have been set up.
     #[remove_in(PaymentsUpdateRequest, PaymentsConfirmRequest)]
     pub profile_id: Option<String>,
 
@@ -485,7 +485,7 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<PaymentType>)]
     pub payment_type: Option<api_enums::PaymentType>,
 
-    ///Request for an incremental authorization
+    ///Request an incremental authorization, i.e., increase the authorized amount on a confirmed payment before you capture it.
     pub request_incremental_authorization: Option<bool>,
 
     ///Will be used to expire client secret after certain amount of time to be supplied in seconds
@@ -493,7 +493,7 @@ pub struct PaymentsRequest {
     #[schema(example = 900)]
     pub session_expiry: Option<u32>,
 
-    /// additional data related to some frm(Fraud Risk Management) connectors
+    /// Additional data related to some frm(Fraud Risk Management) connectors
     #[schema(value_type = Option<Object>, example = r#"{ "coverage_request" : "fraud", "fulfillment_method" : "delivery" }"#)]
     pub frm_metadata: Option<pii::SecretSerdeValue>,
 
@@ -535,7 +535,7 @@ impl PaymentsRequest {
     }
 }
 
-/// details of surcharge applied on this payment, if applicable
+/// Details of surcharge applied on this payment, if applicable
 #[derive(
     Default, Debug, Clone, serde::Serialize, serde::Deserialize, Copy, ToSchema, PartialEq,
 )]
@@ -629,7 +629,7 @@ pub struct PaymentAttemptResponse {
     pub currency: Option<enums::Currency>,
     /// The connector used for the payment
     pub connector: Option<String>,
-    /// If there was an error while calling the connector the error message is received here
+    /// If there was an error while calling the connector, the error message is received here
     pub error_message: Option<String>,
     /// The payment method that is to be used
     #[schema(value_type = Option<PaymentMethod>, example = "bank_transfer")]
@@ -642,15 +642,15 @@ pub struct PaymentAttemptResponse {
     /// The transaction authentication can be set to undergo payer authentication. By default, the authentication will be marked as NO_THREE_DS
     #[schema(value_type = Option<AuthenticationType>, example = "no_three_ds", default = "three_ds")]
     pub authentication_type: Option<enums::AuthenticationType>,
-    /// If the payment was cancelled the reason provided here
+    /// 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
     pub mandate_id: Option<String>,
-    /// If there was an error while calling the connectors the code is received here
+    /// If there was an error while calling the connectors the error code is received here
     pub error_code: Option<String>,
     /// Provide a reference to a stored payment method
     pub payment_token: Option<String>,
-    /// additional data related to some connectors
+    /// Additional data related to some connectors
     pub connector_metadata: Option<serde_json::Value>,
     /// Payment Experience for the current payment
     #[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
@@ -658,12 +658,12 @@ 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
+    /// Reference to the payment at connector side
     #[schema(value_type = Option<String>, example = "993672945374576J")]
     pub reference_id: Option<String>,
-    /// error code unified across the connectors is received here if there was an error while calling connector
+    /// (This field is not live yet)Error code unified across the connectors is received here if there was an error while calling connector
     pub unified_code: Option<String>,
-    /// error message unified across the connectors is received here if there was an error while calling connector
+    /// (This field is not live yet)Error message unified across the connectors is received here if there was an error while calling connector
     pub unified_message: Option<String>,
     /// Value passed in X-CLIENT-SOURCE header during payments confirm request by the client
     pub client_source: Option<String>,
@@ -675,7 +675,7 @@ pub struct PaymentAttemptResponse {
     Default, Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema,
 )]
 pub struct CaptureResponse {
-    /// unique identifier for the capture
+    /// Unique identifier for the capture
     pub capture_id: String,
     /// The status of the capture
     #[schema(value_type = CaptureStatus, example = "charged")]
@@ -688,11 +688,11 @@ pub struct CaptureResponse {
     pub currency: Option<enums::Currency>,
     /// The connector used for the payment
     pub connector: String,
-    /// unique identifier for the parent attempt on which this capture is made
+    /// Unique identifier for the parent attempt on which this capture is made
     pub authorized_attempt_id: String,
-    /// A unique identifier for a capture provided by the connector
+    /// A unique identifier for this capture provided by the connector
     pub connector_capture_id: Option<String>,
-    /// sequence number of this capture
+    /// 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
     pub error_message: Option<String>,
@@ -700,7 +700,7 @@ pub struct CaptureResponse {
     pub error_code: Option<String>,
     /// If there was an error while calling the connectors the reason is received here
     pub error_reason: Option<String>,
-    /// reference to the capture at connector side
+    /// Reference to the capture at connector side
     pub reference_id: Option<String>,
 }
 
@@ -854,6 +854,7 @@ impl MandateIds {
     }
 }
 
+/// Passing this object during payments creates a mandate. The mandate_type sub object is passed by the server.
 // The fields on this struct are optional, as we want to allow the merchant to provide partial
 // information about creating mandates
 #[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
@@ -911,7 +912,7 @@ impl Default for MandateType {
     }
 }
 
-/// We will be Passing this "CustomerAcceptance" object during Payments-Confirm. The customer_acceptance sub object is usually passed by the SDK or client
+/// This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.
 #[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct CustomerAcceptance {
@@ -3383,7 +3384,7 @@ pub struct PaymentsResponse {
     #[schema(value_type = Option<Vec<RefundResponse>>)]
     pub refunds: Option<Vec<refunds::RefundResponse>>,
 
-    /// List of dispute that happened on this intent
+    /// List of disputes that happened on this intent
     #[schema(value_type = Option<Vec<DisputeResponsePaymentsRetrieve>>)]
     pub disputes: Option<Vec<disputes::DisputeResponsePaymentsRetrieve>>,
 
@@ -3486,7 +3487,7 @@ pub struct PaymentsResponse {
     /// Additional information required for redirection
     pub next_action: Option<NextActionData>,
 
-    /// If the payment was cancelled the reason provided here
+    /// If the payment was cancelled the reason will be provided here
     pub cancellation_reason: Option<String>,
 
     /// If there was an error while calling the connectors the code is received here
@@ -3548,11 +3549,11 @@ pub struct PaymentsResponse {
     #[schema(value_type = Option<Object>, example = r#"{ "udf1": "some-value", "udf2": "some-value" }"#)]
     pub metadata: Option<pii::SecretSerdeValue>,
 
-    /// additional data related to some connectors
+    /// Additional data related to some connectors
     #[schema(value_type = Option<ConnectorMetadata>)]
     pub connector_metadata: Option<serde_json::Value>, // This is Value because it is fetched from DB and before putting in DB the type is validated
 
-    /// additional data that might be required by hyperswitch
+    /// Additional data that might be required by hyperswitch, to enable some specific features.
     #[schema(value_type = Option<FeatureMetadata>)]
     pub feature_metadata: Option<serde_json::Value>, // This is Value because it is fetched from DB and before putting in DB the type is validated
 
@@ -3565,10 +3566,10 @@ pub struct PaymentsResponse {
     /// The business profile that is associated with this payment
     pub profile_id: Option<String>,
 
-    /// details of surcharge applied on this payment
+    /// Details of surcharge applied on this payment
     pub surcharge_details: Option<RequestSurchargeDetails>,
 
-    /// total number of attempts associated with this payment
+    /// Total number of attempts associated with this payment
     pub attempt_count: i16,
 
     /// Denotes the action(approve or reject) taken by merchant in case of manual review. Manual review can occur when the transaction is marked as risky by the frm_processor, payment processor or when there is underpayment/over payment incase of crypto payment
@@ -3605,10 +3606,10 @@ pub struct PaymentsResponse {
     /// The browser information used for this payment
     pub browser_info: Option<serde_json::Value>,
 
-    /// Identifier for Payment Method
+    /// Identifier for Payment Method used for the payment
     pub payment_method_id: Option<String>,
 
-    /// Payment Method Status
+    /// Payment Method Status, refers to the status of the payment method used for this payment.
     #[schema(value_type = Option<PaymentMethodStatus>)]
     pub payment_method_status: Option<common_enums::PaymentMethodStatus>,
 
@@ -4250,7 +4251,7 @@ pub struct ApplepaySessionRequest {
     pub initiative_context: String,
 }
 
-/// additional data related to some connectors
+/// Some connectors like Apple Pay, Airwallex and Noon might require some additional information, find specific details in the child attributes below.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
 pub struct ConnectorMetadata {
     pub apple_pay: Option<ApplepayConnectorMetadataRequest>,
@@ -5127,7 +5128,7 @@ pub struct PaymentLinkListResponse {
     pub data: Vec<PaymentLinkResponse>,
 }
 
-/// custom payment link config for the particular payment
+/// Configure a custom payment link for the particular payment
 #[derive(Clone, Debug, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
 pub struct PaymentCreatePaymentLinkConfig {
     #[serde(flatten)]
diff --git a/crates/common_enums/src/enums.rs b/crates/common_enums/src/enums.rs
index 2ad0ad35cb3..e6ab3435252 100644
--- a/crates/common_enums/src/enums.rs
+++ b/crates/common_enums/src/enums.rs
@@ -1203,7 +1203,7 @@ pub enum IntentStatus {
     PartiallyCapturedAndCapturable,
 }
 
-/// Indicates that you intend to make future payments with this Payment’s payment method. 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.
+/// 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.
 #[derive(
     Clone,
     Copy,
@@ -1506,7 +1506,7 @@ pub enum PaymentMethod {
     GiftCard,
 }
 
-/// To be used to specify the type of payment. Use 'setup_mandate' in case of zero auth flow.
+/// The type of the payment that differentiates between normal and various types of mandate payments. Use 'setup_mandate' in case of zero auth flow.
 #[derive(
     Clone,
     Copy,
diff --git a/crates/openapi/src/routes/payments.rs b/crates/openapi/src/routes/payments.rs
index 66e6ce42962..653fa16c75e 100644
--- a/crates/openapi/src/routes/payments.rs
+++ b/crates/openapi/src/routes/payments.rs
@@ -1,10 +1,12 @@
 /// Payments - Create
 ///
-/// **Creates a payment object when amount and currency are passed.** This API is also used to create a mandate by passing the `mandate_object`.
+/// **Creates a payment object when amount and currency are passed.**
 ///
-/// To completely process a payment you will have to create a payment, attach a payment method, confirm and capture funds.
+/// 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 or you could use the following sequence of API requests to achieve the same:
+/// 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
 ///
@@ -14,7 +16,9 @@
 ///
 /// 4. Payments - Capture.
 ///
-/// Use the client secret returned in this API along with your publishable key to make subsequent API calls from your client
+/// 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",
@@ -87,7 +91,7 @@
                     "setup_future_usage": "off_session",
                     "mandate_data": {
                       "customer_acceptance": {
-                        "acceptance_type": "offline",
+                        "acceptance_type": "online",
                         "accepted_at": "1963-05-03T04:07:52.723Z",
                         "online": {
                           "ip_address": "127.0.0.1",
@@ -102,7 +106,7 @@
                       }
                     },
                     "customer_acceptance": {
-                      "acceptance_type": "offline",
+                      "acceptance_type": "online",
                       "accepted_at": "1963-05-03T04:07:52.723Z",
                       "online": {
                         "ip_address": "127.0.0.1",
@@ -143,6 +147,14 @@
                         "card_cvc": "123"
                       }
                     },
+                    "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"
+                      }
+                    },
                     "setup_future_usage": "off_session"
                   })
                 )
@@ -312,7 +324,7 @@ pub fn payments_update() {}
                 }
               },
               "customer_acceptance": {
-                "acceptance_type": "offline",
+                "acceptance_type": "online",
                 "accepted_at": "1963-05-03T04:07:52.723Z",
                 "online": {
                   "ip_address": "127.0.0.1",