Docs: API-Ref changes for Payouts (#5236)

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
Co-authored-by: Kashif <[email protected]>
Co-authored-by: Narayan Bhat <[email protected]>

Author: 4 people

api-reference/openapi_spec.json

@@ -7817,7 +7817,7 @@
       },
       "ChargeRefunds": {
         "type": "object",
-        "description": "Charge object for refunds",
+        "description": "Charge specific fields for controlling the revert of funds from either platform or connected account. Check sub-fields for more details.",
         "required": [
           "charge_id"
         ],
@@ -16251,13 +16251,6 @@
             "example": true,
             "nullable": true
           },
-          "capture_on": {
-            "type": "string",
-            "format": "date-time",
-            "description": "A timestamp (ISO 8601 code) that determines when the payment should be captured.\nProviding this field will automatically set `capture` to true",
-            "example": "2022-09-10T10:11:12Z",
-            "nullable": true
-          },
           "capture_method": {
             "allOf": [
               {
@@ -18313,7 +18306,8 @@
               }
             }
           }
-        ]
+        ],
+        "description": "Custom payout link config for the particular payout, if payout link is to be generated."
       },
       "PayoutCreateRequest": {
         "type": "object",
@@ -18332,15 +18326,15 @@
         "properties": {
           "payout_id": {
             "type": "string",
-            "description": "Unique identifier for the payout. This ensures idempotency for multiple payouts\nthat have been done by a single merchant. This field is auto generated and is returned in the API response.",
+            "description": "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.**",
             "example": "payout_mbabizu24mvu3mela5njyhpit4",
             "nullable": true,
             "maxLength": 30,
             "minLength": 30
           },
           "merchant_id": {
             "type": "string",
-            "description": "This is an identifier for the merchant account. This is inferred from the API key\nprovided during the request",
+            "description": "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.**",
             "example": "merchant_1668273825",
             "nullable": true,
             "maxLength": 255
@@ -18367,7 +18361,7 @@
             "items": {
               "$ref": "#/components/schemas/PayoutConnectors"
             },
-            "description": "This allows the merchant to manually select a connector with which the payout can go through",
+            "description": "This field allows the merchant to manually select a connector with which the payout can go through.",
             "example": [
               "wise",
               "adyen"
@@ -18376,7 +18370,7 @@
           },
           "confirm": {
             "type": "boolean",
-            "description": "The boolean value to create payout with connector",
+            "description": "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.",
             "default": false,
             "example": true
           },
@@ -18477,21 +18471,21 @@
           },
           "payout_token": {
             "type": "string",
-            "description": "Provide a reference to a stored payout method",
+            "description": "Provide a reference to a stored payout method, used to process the payout.",
             "example": "187282ab-40ef-47a9-9206-5099ba31e432",
             "nullable": true
           },
           "profile_id": {
             "type": "string",
-            "description": "The business profile to use for this payout, if not passed the default business profile\nassociated with the merchant account will be used.",
+            "description": "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.",
             "nullable": true
           },
           "priority": {
             "$ref": "#/components/schemas/PayoutSendPriority"
           },
           "payout_link": {
             "type": "boolean",
-            "description": "Whether to get the payout link (if applicable)",
+            "description": "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_.",
             "default": false,
             "example": true,
             "nullable": true
@@ -18713,6 +18707,7 @@
       },
       "PayoutEntityType": {
         "type": "string",
+        "description": "Type of entity to whom the payout is being carried out to, select from the given list of options",
         "enum": [
           "Individual",
           "Company",
@@ -18953,7 +18948,8 @@
               }
             }
           }
-        ]
+        ],
+        "description": "The payout method information required for carrying out a payout"
       },
       "PayoutRequest": {
         "oneOf": [
@@ -19034,6 +19030,7 @@
       },
       "PayoutSendPriority": {
         "type": "string",
+        "description": "The send method which will be required for processing payouts, check options for better understanding.",
         "enum": [
           "instant",
           "fast",
@@ -19063,6 +19060,7 @@
       },
       "PayoutType": {
         "type": "string",
+        "description": "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.",
         "enum": [
           "card",
           "bank",

crates/api_models/src/payments.rs

@@ -3674,6 +3674,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.

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>,
 }

crates/common_enums/src/enums.rs

@@ -2310,6 +2310,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,
@@ -2336,6 +2337,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,
@@ -2369,6 +2371,7 @@ pub enum PayoutEntityType {
     Personal,
 }
 
+/// The send method which will be required for processing payouts, check options for better understanding.
 #[derive(
     Clone,
     Copy,

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,