Bug: Docs: Adding More descriptive details in the Payouts module



We have received feedback about the Payout Module in API ref lacking in description of the various fields.
diff --git a/crates/api_models/src/payments.rs b/crates/api_models/src/payments.rs
index a466288b416..37f696e90f3 100644
--- a/crates/api_models/src/payments.rs
+++ b/crates/api_models/src/payments.rs
@@ -3668,6 +3668,7 @@ pub struct PaymentsResponse {
     /// Providing this field will automatically set `capture` to true
     #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(with = "common_utils::custom_serde::iso8601::option")]
+    #[remove_in(PaymentsCreateResponseOpenApi)]
     pub capture_on: Option<PrimitiveDateTime>,
 
     /// This is the instruction for capture/ debit the money from the users' card. On the other hand authorization refers to blocking the amount on the users' payment method.
diff --git a/crates/api_models/src/payouts.rs b/crates/api_models/src/payouts.rs
index 9509df8c591..c3ae760215b 100644
--- a/crates/api_models/src/payouts.rs
+++ b/crates/api_models/src/payouts.rs
@@ -21,8 +21,7 @@ pub enum PayoutRequest {
 #[derive(Default, Debug, Deserialize, Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct PayoutCreateRequest {
-    /// Unique identifier for the payout. This ensures idempotency for multiple payouts
-    /// that have been done by a single merchant. This field is auto generated and is returned in the API response.
+    /// Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response, **not required to be included in the Payout Create/Update Request.**
     #[schema(
         value_type = Option<String>,
         min_length = 30,
@@ -31,8 +30,7 @@ pub struct PayoutCreateRequest {
     )]
     pub payout_id: Option<String>, // TODO: #1321 https://github.com/juspay/hyperswitch/issues/1321
 
-    /// This is an identifier for the merchant account. This is inferred from the API key
-    /// provided during the request
+    /// This is an identifier for the merchant account. This is inferred from the API key provided during the request, **not required to be included in the Payout Create/Update Request.**
     #[schema(max_length = 255, value_type = Option<String>, example = "merchant_1668273825")]
     pub merchant_id: Option<id_type::MerchantId>,
 
@@ -52,15 +50,15 @@ pub struct PayoutCreateRequest {
     }))]
     pub routing: Option<serde_json::Value>,
 
-    /// This allows the merchant to manually select a connector with which the payout can go through
+    /// This field allows the merchant to manually select a connector with which the payout can go through.
     #[schema(value_type = Option<Vec<PayoutConnectors>>, max_length = 255, example = json!(["wise", "adyen"]))]
     pub connector: Option<Vec<api_enums::PayoutConnectors>>,
 
-    /// The boolean value to create payout with connector
+    /// This field is used when merchant wants to confirm the payout, thus useful for the payout _Confirm_ request. Ideally merchants should _Create_ a payout, _Update_ it (if required), then _Confirm_ it.
     #[schema(value_type = bool, example = true, default = false)]
     pub confirm: Option<bool>,
 
-    /// The payout_type of the payout request can be specified here
+    /// The payout_type of the payout request can be specified here, this is a mandatory field to _Confirm_ the payout, i.e., should be passed in _Create_ request, if not then should be updated in the payout _Update_ request, then only it can be confirmed.
     #[schema(value_type = PayoutType, example = "card")]
     pub payout_type: Option<api_enums::PayoutType>,
 
@@ -129,7 +127,7 @@ pub struct PayoutCreateRequest {
     #[schema(example = "It's my first payout request", value_type = String)]
     pub description: Option<String>,
 
-    /// Type of entity to whom the payout is being carried out to
+    /// Type of entity to whom the payout is being carried out to, select from the given list of options
     #[schema(value_type = PayoutEntityType, example = "Individual")]
     pub entity_type: Option<api_enums::PayoutEntityType>,
 
@@ -141,23 +139,22 @@ pub struct PayoutCreateRequest {
     #[schema(value_type = Option<Object>, example = r#"{ "udf1": "some-value", "udf2": "some-value" }"#)]
     pub metadata: Option<pii::SecretSerdeValue>,
 
-    /// Provide a reference to a stored payout method
+    /// Provide a reference to a stored payout method, used to process the payout.
     #[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
     pub payout_token: Option<String>,
 
-    /// The business profile to use for this payout, if not passed the default business profile
-    /// associated with the merchant account will be used.
+    /// The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.
     pub profile_id: Option<String>,
 
-    /// The send method for processing payouts
+    /// The send method which will be required for processing payouts, check options for better understanding.
     #[schema(value_type = PayoutSendPriority, example = "instant")]
     pub priority: Option<api_enums::PayoutSendPriority>,
 
-    /// Whether to get the payout link (if applicable)
+    /// Whether to get the payout link (if applicable). Merchant need to specify this during the Payout _Create_, this field can not be updated during Payout _Update_.
     #[schema(default = false, example = true)]
     pub payout_link: Option<bool>,
 
-    /// custom payout link config for the particular payout
+    /// Custom payout link config for the particular payout, if payout link is to be generated.
     #[schema(value_type = Option<PayoutCreatePayoutLinkConfig>)]
     pub payout_link_config: Option<PayoutCreatePayoutLinkConfig>,
 
@@ -167,6 +164,7 @@ pub struct PayoutCreateRequest {
     pub session_expiry: Option<u32>,
 }
 
+/// Custom payout link config for the particular payout, if payout link is to be generated.
 #[derive(Default, Debug, Deserialize, Serialize, Clone, ToSchema)]
 pub struct PayoutCreatePayoutLinkConfig {
     /// The unique identifier for the collect link.
@@ -182,6 +180,7 @@ pub struct PayoutCreatePayoutLinkConfig {
     pub enabled_payment_methods: Option<Vec<link_utils::EnabledPaymentMethod>>,
 }
 
+/// The payout method information required for carrying out a payout
 #[derive(Debug, Clone, Deserialize, Serialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum PayoutMethodData {
@@ -486,7 +485,7 @@ pub struct PayoutCreateResponse {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub attempts: Option<Vec<PayoutAttemptResponse>>,
 
-    // If payout link is request, this represents response on
+    /// If payout link was requested, this contains the link's ID and the URL to render the payout widget
     #[schema(value_type = Option<PayoutLinkResponse>)]
     pub payout_link: Option<PayoutLinkResponse>,
 }
diff --git a/crates/common_enums/src/enums.rs b/crates/common_enums/src/enums.rs
index 3454a6ba020..e70cc20f266 100644
--- a/crates/common_enums/src/enums.rs
+++ b/crates/common_enums/src/enums.rs
@@ -2291,6 +2291,7 @@ pub enum PayoutStatus {
     RequiresVendorAccountCreation,
 }
 
+/// The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.
 #[derive(
     Clone,
     Copy,
@@ -2317,6 +2318,7 @@ pub enum PayoutType {
     Wallet,
 }
 
+/// Type of entity to whom the payout is being carried out to, select from the given list of options
 #[derive(
     Clone,
     Copy,
@@ -2350,6 +2352,7 @@ pub enum PayoutEntityType {
     Personal,
 }
 
+/// The send method which will be required for processing payouts, check options for better understanding.
 #[derive(
     Clone,
     Copy,
diff --git a/crates/common_utils/src/types.rs b/crates/common_utils/src/types.rs
index 02b49f52730..83d005dd637 100644
--- a/crates/common_utils/src/types.rs
+++ b/crates/common_utils/src/types.rs
@@ -690,7 +690,7 @@ mod amount_conversion_tests {
     Serialize, serde::Deserialize, Debug, Clone, PartialEq, Eq, FromSqlRow, AsExpression, ToSchema,
 )]
 #[diesel(sql_type = Jsonb)]
-/// Charge object for refunds
+/// Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details.
 pub struct ChargeRefunds {
     /// Identifier for charge created for the payment
     pub charge_id: String,

## 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).
-->
Closes #5235 

## 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
