diff --git a/api-reference/openapi_spec.json b/api-reference/openapi_spec.json
index cfb57ca8722e..eeb68e9d0473 100644
--- a/api-reference/openapi_spec.json
+++ b/api-reference/openapi_spec.json
@@ -191,7 +191,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PaymentsResponse"
+                  "$ref": "#/components/schemas/PaymentsCreateResponseOpenApi"
                 }
               }
             }
@@ -270,7 +270,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PaymentsResponse"
+                  "$ref": "#/components/schemas/PaymentsCreateResponseOpenApi"
                 }
               }
             }
@@ -401,7 +401,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PaymentsResponse"
+                  "$ref": "#/components/schemas/PaymentsCreateResponseOpenApi"
                 }
               }
             }
@@ -5284,6 +5284,7 @@
       },
       "AttemptStatus": {
         "type": "string",
+        "description": "The status of the attempt",
         "enum": [
           "started",
           "authentication_failed",
@@ -5350,6 +5351,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",
         "enum": [
           "three_ds",
           "no_three_ds"
@@ -7117,6 +7119,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",
         "enum": [
           "automatic",
           "manual",
@@ -7198,6 +7201,7 @@
       },
       "CaptureStatus": {
         "type": "string",
+        "description": "The status of the capture",
         "enum": [
           "started",
           "charged",
@@ -7745,6 +7749,7 @@
       },
       "ConnectorMetadata": {
         "type": "object",
+        "description": "additional data related to some connectors",
         "properties": {
           "apple_pay": {
             "allOf": [
@@ -8361,6 +8366,7 @@
       },
       "CustomerAcceptance": {
         "type": "object",
+        "description": "We will be Passing this \"CustomerAcceptance\" object during Payments-Confirm. The customer_acceptance sub object is usually passed by the SDK or client",
         "required": [
           "acceptance_type"
         ],
@@ -8453,6 +8459,7 @@
       },
       "CustomerDetails": {
         "type": "object",
+        "description": "Passing this object creates a new customer or attaches an existing customer to the payment",
         "required": [
           "id"
         ],
@@ -8496,6 +8503,7 @@
       },
       "CustomerDetailsResponse": {
         "type": "object",
+        "description": "Details of customer attached to this payment",
         "properties": {
           "id": {
             "type": "string",
@@ -8868,6 +8876,7 @@
       },
       "DeviceChannel": {
         "type": "string",
+        "description": "Device Channel indicating whether request is coming from App or Browser",
         "enum": [
           "APP",
           "BRW"
@@ -9038,6 +9047,7 @@
       },
       "DisputeStage": {
         "type": "string",
+        "description": "Stage of the dispute",
         "enum": [
           "pre_dispute",
           "dispute",
@@ -9046,6 +9056,7 @@
       },
       "DisputeStatus": {
         "type": "string",
+        "description": "Status of the dispute",
         "enum": [
           "dispute_opened",
           "dispute_expired",
@@ -9122,6 +9133,7 @@
       },
       "EphemeralKeyCreateResponse": {
         "type": "object",
+        "description": "ephemeral_key for the customer_id mentioned",
         "required": [
           "customer_id",
           "created_at",
@@ -9384,6 +9396,7 @@
       },
       "ExternalAuthenticationDetailsResponse": {
         "type": "object",
+        "description": "Details of external authentication",
         "required": [
           "status"
         ],
@@ -9428,6 +9441,7 @@
       },
       "FeatureMetadata": {
         "type": "object",
+        "description": "additional data that might be required by hyperswitch",
         "properties": {
           "redirect_response": {
             "allOf": [
@@ -9832,6 +9846,7 @@
       },
       "FutureUsage": {
         "type": "string",
+        "description": "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.",
         "enum": [
           "off_session",
           "on_session"
@@ -10646,6 +10661,7 @@
       },
       "IntentStatus": {
         "type": "string",
+        "description": "The status of the current payment that was made",
         "enum": [
           "succeeded",
           "failed",
@@ -11653,13 +11669,14 @@
       },
       "MerchantConnectorDetailsWrap": {
         "type": "object",
+        "description": "Merchant connector details used to make payments.",
         "required": [
           "creds_identifier"
         ],
         "properties": {
           "creds_identifier": {
             "type": "string",
-            "description": "Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info in this field. And do not send the string \"null\"."
+            "description": "Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info, like encoded_data in this field. And do not send the string \"null\"."
           },
           "encoded_data": {
             "allOf": [
@@ -13130,6 +13147,7 @@
       },
       "PaymentChargeRequest": {
         "type": "object",
+        "description": "Fee information to be charged on the payment being collected",
         "required": [
           "charge_type",
           "fees",
@@ -13153,6 +13171,7 @@
       },
       "PaymentChargeResponse": {
         "type": "object",
+        "description": "Fee information to be charged on the payment being collected",
         "required": [
           "charge_type",
           "application_fees",
@@ -13207,7 +13226,8 @@
           {
             "type": "object"
           }
-        ]
+        ],
+        "description": "custom payment link config for the particular payment"
       },
       "PaymentExperience": {
         "type": "string",
@@ -13390,6 +13410,7 @@
       },
       "PaymentLinkStatus": {
         "type": "string",
+        "description": "Status Of the Payment Link",
         "enum": [
           "active",
           "expired"
@@ -13913,7 +13934,8 @@
               }
             }
           }
-        ]
+        ],
+        "description": "The payment method information provided for making a payment"
       },
       "PaymentMethodDataResponse": {
         "oneOf": [
@@ -14341,6 +14363,7 @@
       },
       "PaymentMethodStatus": {
         "type": "string",
+        "description": "Payment Method Status",
         "enum": [
           "active",
           "inactive",
@@ -14703,13 +14726,6 @@
             "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",
-            "example": "merchant_1668273825",
-            "nullable": true,
-            "maxLength": 255
-          },
           "routing": {
             "allOf": [
               {
@@ -14755,13 +14771,6 @@
             ],
             "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
-          },
           "confirm": {
             "type": "boolean",
             "description": "Whether to confirm the payment (if applicable)",
@@ -14833,12 +14842,6 @@
             "example": "187282ab-40ef-47a9-9206-5099ba31e432",
             "nullable": true
           },
-          "card_cvc": {
-            "type": "string",
-            "description": "This is used along with the payment_token field while collecting during saved card payments. This field will be deprecated soon, use the payment_method_data.card_token object instead",
-            "deprecated": true,
-            "nullable": true
-          },
           "shipping": {
             "allOf": [
               {
@@ -14960,14 +14963,6 @@
             ],
             "nullable": true
           },
-          "feature_metadata": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/FeatureMetadata"
-              }
-            ],
-            "nullable": true
-          },
           "payment_link": {
             "type": "boolean",
             "description": "Whether to get the payment link (if applicable)",
@@ -15006,7 +15001,7 @@
           },
           "frm_metadata": {
             "type": "object",
-            "description": "additional data related to some frm connectors",
+            "description": "additional data related to some frm(Fraud Risk Management) connectors",
             "nullable": true
           },
           "request_external_three_ds_authentication": {
@@ -15064,13 +15059,6 @@
             "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",
-            "example": "merchant_1668273825",
-            "nullable": true,
-            "maxLength": 255
-          },
           "routing": {
             "allOf": [
               {
@@ -15116,13 +15104,6 @@
             ],
             "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
-          },
           "confirm": {
             "type": "boolean",
             "description": "Whether to confirm the payment (if applicable)",
@@ -15194,12 +15175,6 @@
             "example": "187282ab-40ef-47a9-9206-5099ba31e432",
             "nullable": true
           },
-          "card_cvc": {
-            "type": "string",
-            "description": "This is used along with the payment_token field while collecting during saved card payments. This field will be deprecated soon, use the payment_method_data.card_token object instead",
-            "deprecated": true,
-            "nullable": true
-          },
           "shipping": {
             "allOf": [
               {
@@ -15308,14 +15283,6 @@
             "description": "Use this parameter to restrict the Payment Method Types to show for a given PaymentIntent",
             "nullable": true
           },
-          "retry_action": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/RetryAction"
-              }
-            ],
-            "nullable": true
-          },
           "metadata": {
             "type": "object",
             "description": "You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.",
@@ -15329,14 +15296,6 @@
             ],
             "nullable": true
           },
-          "feature_metadata": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/FeatureMetadata"
-              }
-            ],
-            "nullable": true
-          },
           "payment_link": {
             "type": "boolean",
             "description": "Whether to get the payment link (if applicable)",
@@ -15388,7 +15347,7 @@
           },
           "frm_metadata": {
             "type": "object",
-            "description": "additional data related to some frm connectors",
+            "description": "additional data related to some frm(Fraud Risk Management) connectors",
             "nullable": true
           },
           "request_external_three_ds_authentication": {
@@ -15415,126 +15374,645 @@
           }
         }
       },
-      "PaymentsExternalAuthenticationRequest": {
+      "PaymentsCreateResponseOpenApi": {
         "type": "object",
         "required": [
-          "client_secret",
-          "device_channel",
-          "threeds_method_comp_ind"
+          "status",
+          "amount",
+          "net_amount",
+          "amount_capturable",
+          "amount_received",
+          "currency",
+          "payment_method",
+          "attempt_count"
         ],
         "properties": {
-          "client_secret": {
+          "payment_id": {
             "type": "string",
-            "description": "Client Secret"
+            "description": "Unique identifier for the payment. This ensures idempotency for multiple payments\nthat have been done by a single merchant.",
+            "example": "pay_mbabizu24mvu3mela5njyhpit4",
+            "nullable": true,
+            "maxLength": 30,
+            "minLength": 30
           },
-          "sdk_information": {
+          "merchant_id": {
+            "type": "string",
+            "description": "This is an identifier for the merchant account. This is inferred from the API key\nprovided during the request",
+            "example": "merchant_1668273825",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "status": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/SdkInformation"
+                "$ref": "#/components/schemas/IntentStatus"
               }
             ],
-            "nullable": true
+            "default": "requires_confirmation"
           },
-          "device_channel": {
-            "$ref": "#/components/schemas/DeviceChannel"
+          "amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,",
+            "example": 6540
           },
-          "threeds_method_comp_ind": {
-            "$ref": "#/components/schemas/ThreeDsCompletionIndicator"
-          }
-        }
-      },
-      "PaymentsExternalAuthenticationResponse": {
-        "type": "object",
-        "required": [
-          "trans_status",
-          "three_ds_requestor_url"
-        ],
-        "properties": {
-          "trans_status": {
-            "$ref": "#/components/schemas/TransactionStatus"
+          "net_amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The payment net amount. net_amount = amount + surcharge_details.surcharge_amount + surcharge_details.tax_amount,\nIf no surcharge_details, net_amount = amount",
+            "example": 6540
           },
-          "acs_url": {
+          "amount_capturable": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The maximum amount that could be captured from the payment",
+            "example": 6540,
+            "minimum": 100
+          },
+          "amount_received": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.",
+            "example": 6540
+          },
+          "connector": {
             "type": "string",
-            "description": "Access Server URL to be used for challenge submission",
+            "description": "The connector used for the payment",
+            "example": "stripe",
             "nullable": true
           },
-          "challenge_request": {
+          "client_secret": {
             "type": "string",
-            "description": "Challenge request which should be sent to acs_url",
+            "description": "It's a token used for client side verification.",
+            "example": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
             "nullable": true
           },
-          "acs_reference_number": {
+          "created": {
             "type": "string",
-            "description": "Unique identifier assigned by the EMVCo",
+            "format": "date-time",
+            "description": "Time when the payment was created",
+            "example": "2022-09-10T10:11:12Z",
             "nullable": true
           },
-          "acs_trans_id": {
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          },
+          "customer_id": {
             "type": "string",
-            "description": "Unique identifier assigned by the ACS to identify a single transaction",
-            "nullable": true
+            "description": "The identifier for the customer object. If not provided the customer ID will be autogenerated.\nThis field will be deprecated soon. Please refer to `customer.id`",
+            "deprecated": true,
+            "example": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
+            "nullable": true,
+            "maxLength": 64,
+            "minLength": 1
           },
-          "three_dsserver_trans_id": {
+          "description": {
             "type": "string",
-            "description": "Unique identifier assigned by the 3DS Server to identify a single transaction",
+            "description": "A description of the payment",
+            "example": "It's my first payment request",
             "nullable": true
           },
-          "acs_signed_content": {
-            "type": "string",
-            "description": "Contains the JWS object created by the ACS for the ARes message",
+          "refunds": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RefundResponse"
+            },
+            "description": "List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order",
             "nullable": true
           },
-          "three_ds_requestor_url": {
-            "type": "string",
-            "description": "Three DS Requestor URL"
-          }
-        }
-      },
-      "PaymentsIncrementalAuthorizationRequest": {
-        "type": "object",
-        "required": [
-          "amount"
-        ],
-        "properties": {
-          "amount": {
-            "type": "integer",
-            "format": "int64",
-            "description": "The total amount including previously authorized amount and additional amount",
-            "example": 6540
+          "disputes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DisputeResponsePaymentsRetrieve"
+            },
+            "description": "List of dispute that happened on this intent",
+            "nullable": true
           },
-          "reason": {
-            "type": "string",
-            "description": "Reason for incremental authorization",
+          "attempts": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentAttemptResponse"
+            },
+            "description": "List of attempts that happened on this intent",
             "nullable": true
-          }
-        }
-      },
-      "PaymentsRequest": {
-        "type": "object",
-        "properties": {
-          "amount": {
-            "type": "integer",
-            "format": "int64",
-            "description": "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 ¥100 since ¥ is a zero-decimal currency",
-            "example": 6540,
+          },
+          "captures": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CaptureResponse"
+            },
+            "description": "List of captures done on latest attempt",
+            "nullable": true
+          },
+          "mandate_id": {
+            "type": "string",
+            "description": "A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments",
+            "example": "mandate_iwer89rnjef349dni3",
             "nullable": true,
-            "minimum": 0
+            "maxLength": 255
           },
-          "currency": {
+          "mandate_data": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/Currency"
+                "$ref": "#/components/schemas/MandateData"
               }
             ],
             "nullable": true
           },
-          "amount_to_capture": {
-            "type": "integer",
-            "format": "int64",
-            "description": "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.",
-            "example": 6540,
+          "setup_future_usage": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FutureUsage"
+              }
+            ],
             "nullable": true
           },
-          "payment_id": {
+          "off_session": {
+            "type": "boolean",
+            "description": "Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true.",
+            "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": [
+              {
+                "$ref": "#/components/schemas/CaptureMethod"
+              }
+            ],
+            "nullable": true
+          },
+          "payment_method": {
+            "$ref": "#/components/schemas/PaymentMethod"
+          },
+          "payment_method_data": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentMethodDataResponseWithBilling"
+              }
+            ],
+            "nullable": true
+          },
+          "payment_token": {
+            "type": "string",
+            "description": "Provide a reference to a stored payment method",
+            "example": "187282ab-40ef-47a9-9206-5099ba31e432",
+            "nullable": true
+          },
+          "shipping": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/Address"
+              }
+            ],
+            "nullable": true
+          },
+          "billing": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/Address"
+              }
+            ],
+            "nullable": true
+          },
+          "order_details": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OrderDetailsWithAmount"
+            },
+            "description": "Information about the product , quantity and amount for connectors. (e.g. Klarna)",
+            "example": "[{\n        \"product_name\": \"gillete creme\",\n        \"quantity\": 15,\n        \"amount\" : 900\n    }]",
+            "nullable": true
+          },
+          "email": {
+            "type": "string",
+            "description": "description: The customer's email address\nThis field will be deprecated soon. Please refer to `customer.email` object",
+            "deprecated": true,
+            "example": "johntest@test.com",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "name": {
+            "type": "string",
+            "description": "description: The customer's name\nThis field will be deprecated soon. Please refer to `customer.name` object",
+            "deprecated": true,
+            "example": "John Test",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "phone": {
+            "type": "string",
+            "description": "The customer's phone number\nThis field will be deprecated soon. Please refer to `customer.phone` object",
+            "deprecated": true,
+            "example": "9123456789",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "return_url": {
+            "type": "string",
+            "description": "The URL to redirect after the completion of the operation",
+            "example": "https://hyperswitch.io",
+            "nullable": true
+          },
+          "authentication_type": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/AuthenticationType"
+              }
+            ],
+            "default": "three_ds",
+            "nullable": true
+          },
+          "statement_descriptor_name": {
+            "type": "string",
+            "description": "For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters.",
+            "example": "Hyperswitch Router",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "statement_descriptor_suffix": {
+            "type": "string",
+            "description": "Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 255 characters for the concatenated descriptor.",
+            "example": "Payment for shoes purchase",
+            "nullable": true,
+            "maxLength": 255
+          },
+          "next_action": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/NextActionData"
+              }
+            ],
+            "nullable": true
+          },
+          "cancellation_reason": {
+            "type": "string",
+            "description": "If the payment was cancelled the reason provided here",
+            "nullable": true
+          },
+          "error_code": {
+            "type": "string",
+            "description": "If there was an error while calling the connectors the code is received here",
+            "example": "E0001",
+            "nullable": true
+          },
+          "error_message": {
+            "type": "string",
+            "description": "If there was an error while calling the connector the error message is received here",
+            "example": "Failed while verifying the card",
+            "nullable": true
+          },
+          "payment_experience": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentExperience"
+              }
+            ],
+            "nullable": true
+          },
+          "payment_method_type": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentMethodType"
+              }
+            ],
+            "nullable": true
+          },
+          "connector_label": {
+            "type": "string",
+            "description": "The connector used for this payment along with the country and business details",
+            "example": "stripe_US_food",
+            "nullable": true
+          },
+          "business_country": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CountryAlpha2"
+              }
+            ],
+            "nullable": true
+          },
+          "business_label": {
+            "type": "string",
+            "description": "The business label of merchant for this payment",
+            "nullable": true
+          },
+          "business_sub_label": {
+            "type": "string",
+            "description": "The business_sub_label for this payment",
+            "nullable": true
+          },
+          "allowed_payment_method_types": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentMethodType"
+            },
+            "description": "Allowed Payment Method Types for a given PaymentIntent",
+            "nullable": true
+          },
+          "ephemeral_key": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EphemeralKeyCreateResponse"
+              }
+            ],
+            "nullable": true
+          },
+          "manual_retry_allowed": {
+            "type": "boolean",
+            "description": "If true the payment can be retried with same or different payment method which means the confirm call can be made again.",
+            "nullable": true
+          },
+          "connector_transaction_id": {
+            "type": "string",
+            "description": "A unique identifier for a payment provided by the connector",
+            "example": "993672945374576J",
+            "nullable": true
+          },
+          "frm_message": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FrmMessage"
+              }
+            ],
+            "nullable": true
+          },
+          "metadata": {
+            "type": "object",
+            "description": "You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.",
+            "nullable": true
+          },
+          "connector_metadata": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ConnectorMetadata"
+              }
+            ],
+            "nullable": true
+          },
+          "feature_metadata": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FeatureMetadata"
+              }
+            ],
+            "nullable": true
+          },
+          "reference_id": {
+            "type": "string",
+            "description": "reference(Identifier) to the payment at connector side",
+            "example": "993672945374576J",
+            "nullable": true
+          },
+          "payment_link": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentLinkResponse"
+              }
+            ],
+            "nullable": true
+          },
+          "profile_id": {
+            "type": "string",
+            "description": "The business profile that is associated with this payment",
+            "nullable": true
+          },
+          "surcharge_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RequestSurchargeDetails"
+              }
+            ],
+            "nullable": true
+          },
+          "attempt_count": {
+            "type": "integer",
+            "format": "int32",
+            "description": "total number of attempts associated with this payment"
+          },
+          "merchant_decision": {
+            "type": "string",
+            "description": "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",
+            "nullable": true
+          },
+          "merchant_connector_id": {
+            "type": "string",
+            "description": "Identifier of the connector ( merchant connector account ) which was chosen to make the payment",
+            "nullable": true
+          },
+          "incremental_authorization_allowed": {
+            "type": "boolean",
+            "description": "If true, incremental authorization can be performed on this payment, in case the funds authorized initially fall short.",
+            "nullable": true
+          },
+          "authorization_count": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Total number of authorizations happened in an incremental_authorization payment",
+            "nullable": true
+          },
+          "incremental_authorizations": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/IncrementalAuthorizationResponse"
+            },
+            "description": "List of incremental authorizations happened to the payment",
+            "nullable": true
+          },
+          "external_authentication_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ExternalAuthenticationDetailsResponse"
+              }
+            ],
+            "nullable": true
+          },
+          "external_3ds_authentication_attempted": {
+            "type": "boolean",
+            "description": "Flag indicating if external 3ds authentication is made or not",
+            "nullable": true
+          },
+          "expires_on": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Date Time for expiry of the payment",
+            "example": "2022-09-10T10:11:12Z",
+            "nullable": true
+          },
+          "fingerprint": {
+            "type": "string",
+            "description": "Payment Fingerprint, to identify a particular card.\nIt is a 20 character long alphanumeric code.",
+            "nullable": true
+          },
+          "browser_info": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BrowserInformation"
+              }
+            ],
+            "nullable": true
+          },
+          "payment_method_id": {
+            "type": "string",
+            "description": "Identifier for Payment Method",
+            "nullable": true
+          },
+          "payment_method_status": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentMethodStatus"
+              }
+            ],
+            "nullable": true
+          },
+          "updated": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Date time at which payment was updated",
+            "example": "2022-09-10T10:11:12Z",
+            "nullable": true
+          },
+          "charges": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentChargeResponse"
+              }
+            ],
+            "nullable": true
+          },
+          "frm_metadata": {
+            "type": "object",
+            "description": "You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. FRM Metadata is useful for storing additional, structured information on an object related to FRM.",
+            "nullable": true
+          }
+        }
+      },
+      "PaymentsExternalAuthenticationRequest": {
+        "type": "object",
+        "required": [
+          "client_secret",
+          "device_channel",
+          "threeds_method_comp_ind"
+        ],
+        "properties": {
+          "client_secret": {
+            "type": "string",
+            "description": "Client Secret"
+          },
+          "sdk_information": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/SdkInformation"
+              }
+            ],
+            "nullable": true
+          },
+          "device_channel": {
+            "$ref": "#/components/schemas/DeviceChannel"
+          },
+          "threeds_method_comp_ind": {
+            "$ref": "#/components/schemas/ThreeDsCompletionIndicator"
+          }
+        }
+      },
+      "PaymentsExternalAuthenticationResponse": {
+        "type": "object",
+        "required": [
+          "trans_status",
+          "three_ds_requestor_url"
+        ],
+        "properties": {
+          "trans_status": {
+            "$ref": "#/components/schemas/TransactionStatus"
+          },
+          "acs_url": {
+            "type": "string",
+            "description": "Access Server URL to be used for challenge submission",
+            "nullable": true
+          },
+          "challenge_request": {
+            "type": "string",
+            "description": "Challenge request which should be sent to acs_url",
+            "nullable": true
+          },
+          "acs_reference_number": {
+            "type": "string",
+            "description": "Unique identifier assigned by the EMVCo(Europay, Mastercard and Visa)",
+            "nullable": true
+          },
+          "acs_trans_id": {
+            "type": "string",
+            "description": "Unique identifier assigned by the ACS to identify a single transaction",
+            "nullable": true
+          },
+          "three_dsserver_trans_id": {
+            "type": "string",
+            "description": "Unique identifier assigned by the 3DS Server to identify a single transaction",
+            "nullable": true
+          },
+          "acs_signed_content": {
+            "type": "string",
+            "description": "Contains the JWS object created by the ACS for the ARes(Authentication Response) message",
+            "nullable": true
+          },
+          "three_ds_requestor_url": {
+            "type": "string",
+            "description": "Three DS Requestor URL"
+          }
+        }
+      },
+      "PaymentsIncrementalAuthorizationRequest": {
+        "type": "object",
+        "required": [
+          "amount"
+        ],
+        "properties": {
+          "amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The total amount including previously authorized amount and additional amount",
+            "example": 6540
+          },
+          "reason": {
+            "type": "string",
+            "description": "Reason for incremental authorization",
+            "nullable": true
+          }
+        }
+      },
+      "PaymentsRequest": {
+        "type": "object",
+        "properties": {
+          "amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "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 ¥100 since ¥ is a zero-decimal currency",
+            "example": 6540,
+            "nullable": true,
+            "minimum": 0
+          },
+          "currency": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/Currency"
+              }
+            ],
+            "nullable": true
+          },
+          "amount_to_capture": {
+            "type": "integer",
+            "format": "int64",
+            "description": "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.",
+            "example": 6540,
+            "nullable": true
+          },
+          "payment_id": {
             "type": "string",
             "description": "Unique identifier for the payment. This ensures idempotency for multiple payments\nthat have been done by a single merchant. This field is auto generated and is returned in the API response.",
             "example": "pay_mbabizu24mvu3mela5njyhpit4",
@@ -15909,7 +16387,7 @@
           },
           "frm_metadata": {
             "type": "object",
-            "description": "additional data related to some frm connectors",
+            "description": "additional data related to some frm(Fraud Risk Management) connectors",
             "nullable": true
           },
           "request_external_three_ds_authentication": {
@@ -15995,7 +16473,7 @@
           "amount_received": {
             "type": "integer",
             "format": "int64",
-            "description": "The amount which is already captured from the payment",
+            "description": "The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.",
             "example": 6540
           },
           "connector": {
@@ -16048,7 +16526,7 @@
             "items": {
               "$ref": "#/components/schemas/RefundResponse"
             },
-            "description": "List of refund that happened on this intent",
+            "description": "List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order",
             "nullable": true
           },
           "disputes": {
@@ -16077,7 +16555,7 @@
           },
           "mandate_id": {
             "type": "string",
-            "description": "A unique identifier to link the payment to a mandate, can be use instead of payment_method_data",
+            "description": "A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments",
             "example": "mandate_iwer89rnjef349dni3",
             "nullable": true,
             "maxLength": 255
@@ -16347,7 +16825,7 @@
           },
           "reference_id": {
             "type": "string",
-            "description": "reference to the payment at connector side",
+            "description": "reference(Identifier) to the payment at connector side",
             "example": "993672945374576J",
             "nullable": true
           },
@@ -16389,7 +16867,7 @@
           },
           "incremental_authorization_allowed": {
             "type": "boolean",
-            "description": "If true incremental authorization can be performed on this payment",
+            "description": "If true, incremental authorization can be performed on this payment, in case the funds authorized initially fall short.",
             "nullable": true
           },
           "authorization_count": {
@@ -16422,13 +16900,13 @@
           "expires_on": {
             "type": "string",
             "format": "date-time",
-            "description": "Date Time expiry of the payment",
+            "description": "Date Time for expiry of the payment",
             "example": "2022-09-10T10:11:12Z",
             "nullable": true
           },
           "fingerprint": {
             "type": "string",
-            "description": "Payment Fingerprint",
+            "description": "Payment Fingerprint, to identify a particular card.\nIt is a 20 character long alphanumeric code.",
             "nullable": true
           },
           "browser_info": {
@@ -16441,7 +16919,7 @@
           },
           "payment_method_id": {
             "type": "string",
-            "description": "Payment Method Id",
+            "description": "Identifier for Payment Method",
             "nullable": true
           },
           "payment_method_status": {
@@ -16642,13 +17120,6 @@
             "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",
-            "example": "merchant_1668273825",
-            "nullable": true,
-            "maxLength": 255
-          },
           "routing": {
             "allOf": [
               {
@@ -16694,13 +17165,6 @@
             ],
             "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
-          },
           "confirm": {
             "type": "boolean",
             "description": "Whether to confirm the payment (if applicable)",
@@ -16772,12 +17236,6 @@
             "example": "187282ab-40ef-47a9-9206-5099ba31e432",
             "nullable": true
           },
-          "card_cvc": {
-            "type": "string",
-            "description": "This is used along with the payment_token field while collecting during saved card payments. This field will be deprecated soon, use the payment_method_data.card_token object instead",
-            "deprecated": true,
-            "nullable": true
-          },
           "shipping": {
             "allOf": [
               {
@@ -16886,14 +17344,6 @@
             ],
             "nullable": true
           },
-          "feature_metadata": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/FeatureMetadata"
-              }
-            ],
-            "nullable": true
-          },
           "payment_link": {
             "type": "boolean",
             "description": "Whether to get the payment link (if applicable)",
@@ -16940,7 +17390,7 @@
           },
           "frm_metadata": {
             "type": "object",
-            "description": "additional data related to some frm connectors",
+            "description": "additional data related to some frm(Fraud Risk Management) connectors",
             "nullable": true
           },
           "request_external_three_ds_authentication": {
@@ -18211,6 +18661,7 @@
             }
           }
         ],
+        "description": "Details required for recurring payment",
         "discriminator": {
           "propertyName": "type"
         }
@@ -18615,6 +19066,7 @@
       },
       "RequestSurchargeDetails": {
         "type": "object",
+        "description": "details of surcharge applied on this payment, if applicable",
         "required": [
           "surcharge_amount"
         ],
@@ -18718,6 +19170,7 @@
         "properties": {
           "client_secret": {
             "type": "string",
+            "description": "It's a token used for client side verification.",
             "nullable": true
           }
         }
@@ -18734,30 +19187,37 @@
         ],
         "properties": {
           "payment_link_id": {
-            "type": "string"
+            "type": "string",
+            "description": "Identifier for Payment Link"
           },
           "merchant_id": {
-            "type": "string"
+            "type": "string",
+            "description": "Identifier for Merchant"
           },
           "link_to_pay": {
-            "type": "string"
+            "type": "string",
+            "description": "Payment Link"
           },
           "amount": {
             "type": "integer",
             "format": "int64",
+            "description": "The payment amount. Amount for the payment in the lowest denomination of the currency",
             "example": 6540
           },
           "created_at": {
             "type": "string",
-            "format": "date-time"
+            "format": "date-time",
+            "description": "Date and time of Payment Link creation"
           },
           "expiry": {
             "type": "string",
             "format": "date-time",
+            "description": "Date and time of Expiration for Payment Link",
             "nullable": true
           },
           "description": {
             "type": "string",
+            "description": "Description for Payment Link",
             "nullable": true
           },
           "status": {
@@ -18775,6 +19235,7 @@
       },
       "RetryAction": {
         "type": "string",
+        "description": "Denotes the retry action",
         "enum": [
           "manual_retry",
           "requeue"
@@ -19164,6 +19625,7 @@
       },
       "SdkInformation": {
         "type": "object",
+        "description": "SDK Information if request is from SDK",
         "required": [
           "sdk_app_id",
           "sdk_enc_data",
@@ -19815,6 +20277,7 @@
       },
       "TransactionStatus": {
         "type": "string",
+        "description": "Indicates the transaction status",
         "enum": [
           "Y",
           "N",
diff --git a/crates/api_models/src/admin.rs b/crates/api_models/src/admin.rs
index b11037c2a43b..e1ebb547f051 100644
--- a/crates/api_models/src/admin.rs
+++ b/crates/api_models/src/admin.rs
@@ -857,9 +857,11 @@ pub struct ToggleAllKVResponse {
     #[schema(example = true)]
     pub kv_enabled: bool,
 }
+
+/// Merchant connector details used to make payments.
 #[derive(Debug, Clone, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, ToSchema)]
 pub struct MerchantConnectorDetailsWrap {
-    /// Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info in this field. And do not send the string "null".
+    /// Creds Identifier is to uniquely identify the credentials. Do not send any sensitive info, like encoded_data in this field. And do not send the string "null".
     pub creds_identifier: String,
     /// Merchant connector details type type. Base64 Encode the credentials and send it in  this type and send as a string.
     #[schema(value_type = Option<MerchantConnectorDetails>, example = r#"{
diff --git a/crates/api_models/src/enums.rs b/crates/api_models/src/enums.rs
index 514e44337c17..1f2896700e9e 100644
--- a/crates/api_models/src/enums.rs
+++ b/crates/api_models/src/enums.rs
@@ -572,6 +572,7 @@ mod test {
     }
 }
 
+/// Denotes the retry action
 #[derive(
     Debug,
     serde::Deserialize,
diff --git a/crates/api_models/src/ephemeral_key.rs b/crates/api_models/src/ephemeral_key.rs
index 42f5a0877673..d7ee7bd25171 100644
--- a/crates/api_models/src/ephemeral_key.rs
+++ b/crates/api_models/src/ephemeral_key.rs
@@ -2,6 +2,7 @@ use common_utils::id_type;
 use serde;
 use utoipa::ToSchema;
 
+/// ephemeral_key for the customer_id mentioned
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, Eq, PartialEq, ToSchema)]
 pub struct EphemeralKeyCreateResponse {
     /// customer_id to which this ephemeral key belongs to
diff --git a/crates/api_models/src/mandates.rs b/crates/api_models/src/mandates.rs
index 4adda0d9af45..f4089a16c22c 100644
--- a/crates/api_models/src/mandates.rs
+++ b/crates/api_models/src/mandates.rs
@@ -114,6 +114,7 @@ pub struct MandateListConstraints {
     pub created_time_gte: Option<PrimitiveDateTime>,
 }
 
+/// Details required for recurring payment
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
 #[serde(tag = "type", content = "data", rename_all = "snake_case")]
 pub enum RecurringDetails {
diff --git a/crates/api_models/src/payments.rs b/crates/api_models/src/payments.rs
index 2b06afc639f0..08388f8db2d1 100644
--- a/crates/api_models/src/payments.rs
+++ b/crates/api_models/src/payments.rs
@@ -179,6 +179,7 @@ mod client_secret_tests {
     }
 }
 
+/// Passing this object creates a new customer or attaches an existing customer to the payment
 #[derive(Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema, PartialEq)]
 pub struct CustomerDetails {
     /// The identifier for the customer.
@@ -202,6 +203,7 @@ pub struct CustomerDetails {
     pub phone_country_code: Option<String>,
 }
 
+/// Details of customer attached to this payment
 #[derive(Debug, Default, serde::Serialize, Clone, ToSchema, PartialEq, Setter)]
 pub struct CustomerDetailsResponse {
     /// The identifier for the customer.
@@ -267,6 +269,7 @@ pub struct PaymentsRequest {
     /// This is an identifier for the merchant account. This is inferred from the API key
     /// provided during the request
     #[schema(max_length = 255, example = "merchant_1668273825")]
+    #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub merchant_id: Option<String>,
 
     #[schema(value_type = Option<StraightThroughAlgorithm>, example = json!({
@@ -279,11 +282,9 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<Vec<Connector>>, max_length = 255, example = json!(["stripe", "adyen"]))]
     pub connector: Option<Vec<api_enums::Connector>>,
 
-    /// 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
     #[schema(value_type = Option<CaptureMethod>, example = "automatic")]
     pub capture_method: Option<api_enums::CaptureMethod>,
 
-    /// 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
     #[schema(value_type = Option<AuthenticationType>, example = "no_three_ds", default = "three_ds")]
     pub authentication_type: Option<api_enums::AuthenticationType>,
 
@@ -294,6 +295,7 @@ pub struct PaymentsRequest {
     /// Providing this field will automatically set `capture` to true
     #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(default, with = "common_utils::custom_serde::iso8601::option")]
+    #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub capture_on: Option<PrimitiveDateTime>,
 
     /// Whether to confirm the payment (if applicable)
@@ -342,16 +344,14 @@ pub struct PaymentsRequest {
     /// The URL to redirect after the completion of the operation
     #[schema(value_type = Option<String>, example = "https://hyperswitch.io")]
     pub return_url: Option<Url>,
-    /// 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.
+
     #[schema(value_type = Option<FutureUsage>, example = "off_session")]
     pub setup_future_usage: Option<api_enums::FutureUsage>,
 
-    /// The payment method information provided for making a payment
     #[schema(example = "bank_transfer")]
     #[serde(with = "payment_method_data_serde", default)]
     pub payment_method_data: Option<PaymentMethodDataRequest>,
 
-    /// The payment method that is to be used
     #[schema(value_type = Option<PaymentMethod>, example = "card")]
     pub payment_method: Option<api_enums::PaymentMethod>,
 
@@ -361,6 +361,7 @@ pub struct PaymentsRequest {
 
     /// This is used along with the payment_token field while collecting during saved card payments. This field will be deprecated soon, use the payment_method_data.card_token object instead
     #[schema(value_type = Option<String>, deprecated)]
+    #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub card_cvc: Option<Secret<String>>,
 
     /// The shipping address for the payment
@@ -391,7 +392,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>,
 
-    /// Passing this object during payments confirm . The customer_acceptance sub object is usually passed by the SDK or client
+    /// We will be Passing this "CustomerAcceptance" object during Payments-Confirm. The customer_acceptance sub object is usually passed by the SDK or client
     #[schema(value_type = Option<CustomerAcceptance>)]
     pub customer_acceptance: Option<CustomerAcceptance>,
 
@@ -418,7 +419,7 @@ pub struct PaymentsRequest {
     #[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
     pub payment_experience: Option<api_enums::PaymentExperience>,
 
-    /// Payment Method Type
+    /// Can be used to specify the Payment Method Type
     #[schema(value_type = Option<PaymentMethodType>, example = "google_pay")]
     pub payment_method_type: Option<api_enums::PaymentMethodType>,
 
@@ -434,7 +435,6 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsConfirmRequest)]
     pub business_label: Option<String>,
 
-    /// Merchant connector details used to make payments.
     #[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
     pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
 
@@ -448,23 +448,24 @@ pub struct PaymentsRequest {
 
     /// Denotes the retry action
     #[schema(value_type = Option<RetryAction>)]
+    #[remove_in(PaymentsCreateRequest)]
     pub retry_action: Option<api_enums::RetryAction>,
 
     /// You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.
     #[schema(value_type = Option<Object>, example = r#"{ "udf1": "some-value", "udf2": "some-value" }"#)]
     pub metadata: Option<pii::SecretSerdeValue>,
 
-    /// 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.
     pub connector_metadata: Option<ConnectorMetadata>,
 
-    /// additional data that might be required by hyperswitch
+    /// Additional data that might be required by hyperswitch based on the requested features by the merchants.
+    #[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
     pub feature_metadata: Option<FeatureMetadata>,
 
     /// Whether to get the payment link (if applicable)
     #[schema(default = false, example = true)]
     pub payment_link: Option<bool>,
 
-    /// custom payment link config for the particular payment
     #[schema(value_type = Option<PaymentCreatePaymentLinkConfig>)]
     pub payment_link_config: Option<PaymentCreatePaymentLinkConfig>,
 
@@ -473,7 +474,6 @@ pub struct PaymentsRequest {
     #[remove_in(PaymentsUpdateRequest, PaymentsConfirmRequest)]
     pub profile_id: Option<String>,
 
-    /// surcharge_details for this payment
     #[remove_in(PaymentsConfirmRequest)]
     #[schema(value_type = Option<RequestSurchargeDetails>)]
     pub surcharge_details: Option<RequestSurchargeDetails>,
@@ -490,7 +490,7 @@ pub struct PaymentsRequest {
     #[schema(example = 900)]
     pub session_expiry: Option<u32>,
 
-    /// additional data related to some frm 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>,
 
@@ -505,6 +505,7 @@ pub struct PaymentsRequest {
     pub charges: Option<PaymentChargeRequest>,
 }
 
+/// Fee information to be charged on the payment being collected
 #[derive(Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub struct PaymentChargeRequest {
@@ -530,6 +531,8 @@ impl PaymentsRequest {
             .map(|amount| MinorUnit::from(amount) + surcharge_amount)
     }
 }
+
+/// details of surcharge applied on this payment, if applicable
 #[derive(
     Default, Debug, Clone, serde::Serialize, serde::Deserialize, Copy, ToSchema, PartialEq,
 )]
@@ -905,6 +908,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
 #[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct CustomerAcceptance {
@@ -1462,6 +1466,7 @@ mod payment_method_data_serde {
     }
 }
 
+/// The payment method information provided for making a payment
 #[derive(Debug, Clone, serde::Deserialize, serde::Serialize, ToSchema, Eq, PartialEq)]
 pub struct PaymentMethodDataRequest {
     #[serde(flatten)]
@@ -3037,7 +3042,7 @@ pub struct PaymentsCaptureRequest {
     /// Concatenated with the statement descriptor suffix that’s set on the account to form the complete statement descriptor.
     pub statement_descriptor_prefix: Option<String>,
     /// Merchant connector details used to make payments.
-    #[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
+    #[schema(value_type = Option<MerchantConnectorDetailsWrap>, deprecated)]
     pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
 }
 
@@ -3290,7 +3295,18 @@ pub struct ReceiverDetails {
     amount_remaining: Option<i64>,
 }
 
-#[derive(Setter, Clone, Default, Debug, PartialEq, serde::Serialize, ToSchema)]
+#[derive(
+    Setter,
+    Clone,
+    Default,
+    Debug,
+    PartialEq,
+    serde::Serialize,
+    ToSchema,
+    router_derive::PolymorphicSchema,
+)]
+#[generate_schemas(PaymentsCreateResponseOpenApi)]
+
 pub struct PaymentsResponse {
     /// Unique identifier for the payment. This ensures idempotency for multiple payments
     /// that have been done by a single merchant.
@@ -3306,7 +3322,6 @@ pub struct PaymentsResponse {
     #[schema(max_length = 255, example = "merchant_1668273825")]
     pub merchant_id: Option<String>,
 
-    /// The status of the current payment that was made
     #[schema(value_type = IntentStatus, example = "failed", default = "requires_confirmation")]
     pub status: api_enums::IntentStatus,
 
@@ -3323,7 +3338,7 @@ pub struct PaymentsResponse {
     #[schema(value_type = i64, minimum = 100, example = 6540)]
     pub amount_capturable: Option<MinorUnit>,
 
-    /// The amount which is already captured from the payment
+    /// The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.
     #[schema(value_type = i64, example = 6540)]
     pub amount_received: Option<MinorUnit>,
 
@@ -3355,14 +3370,13 @@ pub struct PaymentsResponse {
     )]
     pub customer_id: Option<id_type::CustomerId>,
 
-    /// Details of customer attached to this payment
     pub customer: Option<CustomerDetailsResponse>,
 
     /// A description of the payment
     #[schema(example = "It's my first payment request")]
     pub description: Option<String>,
 
-    /// List of refund that happened on this intent
+    /// List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order
     #[schema(value_type = Option<Vec<RefundResponse>>)]
     pub refunds: Option<Vec<refunds::RefundResponse>>,
 
@@ -3380,7 +3394,7 @@ pub struct PaymentsResponse {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub captures: Option<Vec<CaptureResponse>>,
 
-    /// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
+    /// A unique identifier to link the payment to a mandate, can be used instead of payment_method_data, in case of setting up recurring payments
     #[schema(max_length = 255, example = "mandate_iwer89rnjef349dni3")]
     pub mandate_id: Option<String>,
 
@@ -3454,7 +3468,7 @@ pub struct PaymentsResponse {
     #[schema(example = "https://hyperswitch.io")]
     pub return_url: Option<String>,
 
-    /// The transaction authentication can be set to undergo payer authentication. By default, the authentication will be marked as NO_THREE_DS
+    /// The transaction authentication can be set to undergo payer authentication. By default, the authentication will be marked as NO_THREE_DS, as the 3DS method helps with more robust payer authentication
     #[schema(value_type = Option<AuthenticationType>, example = "no_three_ds", default = "three_ds")]
     pub authentication_type: Option<api_enums::AuthenticationType>,
 
@@ -3481,16 +3495,18 @@ pub struct PaymentsResponse {
     pub error_message: Option<String>,
 
     /// error code unified across the connectors is received here if there was an error while calling connector
+    #[remove_in(PaymentsCreateResponseOpenApi)]
     pub unified_code: Option<String>,
 
     /// error message unified across the connectors is received here if there was an error while calling connector
+    #[remove_in(PaymentsCreateResponseOpenApi)]
     pub unified_message: Option<String>,
 
     /// Payment Experience for the current payment
     #[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
     pub payment_experience: Option<api_enums::PaymentExperience>,
 
-    /// Payment Method Type
+    /// Can be used to specify the Payment Method Type
     #[schema(value_type = Option<PaymentMethodType>, example = "gpay")]
     pub payment_method_type: Option<api_enums::PaymentMethodType>,
 
@@ -3537,10 +3553,11 @@ pub struct PaymentsResponse {
     #[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
 
-    /// reference to the payment at connector side
+    /// reference(Identifier) to the payment at connector side
     #[schema(value_type = Option<String>, example = "993672945374576J")]
     pub reference_id: Option<String>,
 
+    /// Details for Payment link
     pub payment_link: Option<PaymentLinkResponse>,
     /// The business profile that is associated with this payment
     pub profile_id: Option<String>,
@@ -3557,7 +3574,7 @@ pub struct PaymentsResponse {
     /// Identifier of the connector ( merchant connector account ) which was chosen to make the payment
     pub merchant_connector_id: Option<String>,
 
-    /// If true incremental authorization can be performed on this payment
+    /// If true, incremental authorization can be performed on this payment, in case the funds authorized initially fall short.
     pub incremental_authorization_allowed: Option<bool>,
 
     /// Total number of authorizations happened in an incremental_authorization payment
@@ -3572,19 +3589,20 @@ pub struct PaymentsResponse {
     /// Flag indicating if external 3ds authentication is made or not
     pub external_3ds_authentication_attempted: Option<bool>,
 
-    /// Date Time expiry of the payment
+    /// Date Time for expiry of the payment
     #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(default, with = "common_utils::custom_serde::iso8601::option")]
     pub expires_on: Option<PrimitiveDateTime>,
 
-    /// Payment Fingerprint
+    /// Payment Fingerprint, to identify a particular card.
+    /// It is a 20 character long alphanumeric code.
     pub fingerprint: Option<String>,
 
     #[schema(value_type = Option<BrowserInformation>)]
     /// The browser information used for this payment
     pub browser_info: Option<serde_json::Value>,
 
-    /// Payment Method Id
+    /// Identifier for Payment Method
     pub payment_method_id: Option<String>,
 
     /// Payment Method Status
@@ -3604,6 +3622,7 @@ pub struct PaymentsResponse {
     pub frm_metadata: Option<pii::SecretSerdeValue>,
 }
 
+/// Fee information to be charged on the payment being collected
 #[derive(Setter, Clone, Default, Debug, PartialEq, serde::Serialize, ToSchema)]
 pub struct PaymentChargeResponse {
     /// Identifier for charge created for the payment
@@ -3621,6 +3640,7 @@ pub struct PaymentChargeResponse {
     pub transfer_account_id: String,
 }
 
+/// Details of external authentication
 #[derive(Setter, Clone, Default, Debug, PartialEq, serde::Serialize, ToSchema)]
 pub struct ExternalAuthenticationDetailsResponse {
     /// Authentication Type - Challenge / Frictionless
@@ -4227,6 +4247,7 @@ pub struct ApplepaySessionRequest {
     pub initiative_context: String,
 }
 
+/// additional data related to some connectors
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
 pub struct ConnectorMetadata {
     pub apple_pay: Option<ApplepayConnectorMetadataRequest>,
@@ -4633,7 +4654,7 @@ pub struct PaymentsCancelRequest {
     /// The reason for the payment cancel
     pub cancellation_reason: Option<String>,
     /// Merchant connector details used to make payments.
-    #[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
+    #[schema(value_type = Option<MerchantConnectorDetailsWrap>, deprecated)]
     pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
 }
 
@@ -4665,6 +4686,7 @@ pub struct PaymentsExternalAuthenticationRequest {
     pub threeds_method_comp_ind: ThreeDsCompletionIndicator,
 }
 
+/// Indicates if 3DS method data was successfully completed or not
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
 pub struct PaymentsManualUpdateRequest {
     /// The identifier for the payment
@@ -4697,6 +4719,7 @@ pub enum ThreeDsCompletionIndicator {
     NotAvailable,
 }
 
+/// Device Channel indicating whether request is coming from App or Browser
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema, Eq, PartialEq)]
 pub enum DeviceChannel {
     #[serde(rename = "APP")]
@@ -4705,6 +4728,7 @@ pub enum DeviceChannel {
     Browser,
 }
 
+/// SDK Information if request is from SDK
 #[derive(Default, Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
 pub struct SdkInformation {
     /// Unique ID created on installations of the 3DS Requestor App on a Consumer Device
@@ -4723,7 +4747,7 @@ pub struct SdkInformation {
 
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
 pub struct PaymentsExternalAuthenticationResponse {
-    /// Indicates the trans status
+    /// Indicates the transaction status
     #[serde(rename = "trans_status")]
     #[schema(value_type = TransactionStatus)]
     pub transaction_status: common_enums::TransactionStatus,
@@ -4731,13 +4755,13 @@ pub struct PaymentsExternalAuthenticationResponse {
     pub acs_url: Option<String>,
     /// Challenge request which should be sent to acs_url
     pub challenge_request: Option<String>,
-    /// Unique identifier assigned by the EMVCo
+    /// Unique identifier assigned by the EMVCo(Europay, Mastercard and Visa)
     pub acs_reference_number: Option<String>,
     /// Unique identifier assigned by the ACS to identify a single transaction
     pub acs_trans_id: Option<String>,
     /// Unique identifier assigned by the 3DS Server to identify a single transaction
     pub three_dsserver_trans_id: Option<String>,
-    /// Contains the JWS object created by the ACS for the ARes message
+    /// Contains the JWS object created by the ACS for the ARes(Authentication Response) message
     pub acs_signed_content: Option<String>,
     /// Three DS Requestor URL
     pub three_ds_requestor_url: String,
@@ -4768,6 +4792,7 @@ pub struct PaymentsStartRequest {
     pub attempt_id: String,
 }
 
+/// additional data that might be required by hyperswitch
 #[derive(Debug, Clone, serde::Deserialize, serde::Serialize, ToSchema)]
 pub struct FeatureMetadata {
     /// Redirection response coming in request as metadata field only for redirection scenarios
@@ -4959,6 +4984,7 @@ mod tests {
 
 #[derive(Default, Debug, serde::Deserialize, Clone, ToSchema, serde::Serialize)]
 pub struct RetrievePaymentLinkRequest {
+    /// It's a token used for client side verification.
     pub client_secret: Option<String>,
 }
 
@@ -4970,16 +4996,24 @@ pub struct PaymentLinkResponse {
 
 #[derive(Clone, Debug, serde::Serialize, ToSchema)]
 pub struct RetrievePaymentLinkResponse {
+    /// Identifier for Payment Link
     pub payment_link_id: String,
+    /// Identifier for Merchant
     pub merchant_id: String,
+    /// Payment Link
     pub link_to_pay: String,
+    /// The payment amount. Amount for the payment in the lowest denomination of the currency
     #[schema(value_type = i64, example = 6540)]
     pub amount: MinorUnit,
+    /// Date and time of Payment Link creation
     #[serde(with = "common_utils::custom_serde::iso8601")]
     pub created_at: PrimitiveDateTime,
+    /// Date and time of Expiration for Payment Link
     #[serde(with = "common_utils::custom_serde::iso8601::option")]
     pub expiry: Option<PrimitiveDateTime>,
+    /// Description for Payment Link
     pub description: Option<String>,
+    /// Status Of the Payment Link
     pub status: PaymentLinkStatus,
     #[schema(value_type = Option<Currency>)]
     pub currency: Option<api_enums::Currency>,
@@ -5090,6 +5124,7 @@ pub struct PaymentLinkListResponse {
     pub data: Vec<PaymentLinkResponse>,
 }
 
+/// custom payment link config for the particular payment
 #[derive(Clone, Debug, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
 pub struct PaymentCreatePaymentLinkConfig {
     #[serde(flatten)]
@@ -5111,6 +5146,7 @@ pub struct OrderDetailsWithStringAmount {
     pub product_img_link: Option<String>,
 }
 
+/// Status Of the Payment Link
 #[derive(PartialEq, Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum PaymentLinkStatus {
diff --git a/crates/common_enums/src/enums.rs b/crates/common_enums/src/enums.rs
index 5ee0bae6d617..2d64a61450da 100644
--- a/crates/common_enums/src/enums.rs
+++ b/crates/common_enums/src/enums.rs
@@ -19,6 +19,7 @@ pub mod diesel_exports {
     };
 }
 
+/// The status of the attempt
 #[derive(
     Clone,
     Copy,
@@ -205,6 +206,7 @@ impl AttemptStatus {
     }
 }
 
+/// 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
 #[derive(
     Clone,
     Copy,
@@ -232,6 +234,7 @@ pub enum AuthenticationType {
     NoThreeDs,
 }
 
+/// The status of the capture
 #[derive(
     Clone,
     Copy,
@@ -308,6 +311,7 @@ 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
 #[derive(
     Clone,
     Copy,
@@ -1164,6 +1168,7 @@ pub enum MerchantStorageScheme {
     RedisKv,
 }
 
+/// The status of the current payment that was made
 #[derive(
     Clone,
     Copy,
@@ -1197,6 +1202,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.
 #[derive(
     Clone,
     Copy,
@@ -1251,6 +1257,7 @@ pub enum PaymentMethodIssuerCode {
     JpBacs,
 }
 
+/// Payment Method Status
 #[derive(
     Clone,
     Copy,
@@ -1603,6 +1610,7 @@ pub enum CardNetwork {
     Maestro,
 }
 
+/// Stage of the dispute
 #[derive(
     Clone,
     Copy,
@@ -1627,6 +1635,7 @@ pub enum DisputeStage {
     PreArbitration,
 }
 
+/// Status of the dispute
 #[derive(
     Clone,
     Debug,
@@ -2499,6 +2508,7 @@ pub enum RoleScope {
     Organization,
 }
 
+/// Indicates the transaction status
 #[derive(
     Clone,
     Default,
diff --git a/crates/openapi/src/openapi.rs b/crates/openapi/src/openapi.rs
index a259559c51d7..3b37824be355 100644
--- a/crates/openapi/src/openapi.rs
+++ b/crates/openapi/src/openapi.rs
@@ -350,6 +350,7 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::payments::PaymentsUpdateRequest,
         api_models::payments::PaymentsConfirmRequest,
         api_models::payments::PaymentsResponse,
+        api_models::payments::PaymentsCreateResponseOpenApi,
         api_models::payments::PaymentsStartRequest,
         api_models::payments::PaymentRetrieveBody,
         api_models::payments::PaymentsRetrieveRequest,
diff --git a/crates/openapi/src/routes/payments.rs b/crates/openapi/src/routes/payments.rs
index a93be8828a2d..66e6ce429629 100644
--- a/crates/openapi/src/routes/payments.rs
+++ b/crates/openapi/src/routes/payments.rs
@@ -191,7 +191,7 @@
         ),
     ),
     responses(
-        (status = 200, description = "Payment created", body = PaymentsResponse),
+        (status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi),
         (status = 400, description = "Missing Mandatory fields")
     ),
     tag = "Payments",
@@ -268,7 +268,7 @@ pub fn payments_retrieve() {}
      )
     ),
     responses(
-        (status = 200, description = "Payment updated", body = PaymentsResponse),
+        (status = 200, description = "Payment updated", body = PaymentsCreateResponseOpenApi),
         (status = 400, description = "Missing mandatory fields")
     ),
     tag = "Payments",
@@ -326,7 +326,7 @@ pub fn payments_update() {}
      )
     ),
     responses(
-        (status = 200, description = "Payment confirmed", body = PaymentsResponse),
+        (status = 200, description = "Payment confirmed", body = PaymentsCreateResponseOpenApi),
         (status = 400, description = "Missing mandatory fields")
     ),
     tag = "Payments",