feat: add docs for PaymentsRequest & PaymentsResponse (#385)

crates/api_models/src/admin.rs

@@ -26,7 +26,7 @@ pub struct CreateMerchantAccount {
     pub merchant_details: Option<MerchantDetails>,
 
     /// The URL to redirect after the completion of the operation
-    #[schema(max_length = 255, example = "www.example.com/success")]
+    #[schema(max_length = 255, example = "https://www.example.com/success")]
     pub return_url: Option<String>,
 
     /// Webhook related details

crates/api_models/src/enums.rs

@@ -51,12 +51,15 @@ pub enum AttemptStatus {
     strum::Display,
     strum::EnumString,
     frunk::LabelledGeneric,
+    ToSchema,
 )]
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum AuthenticationType {
+    /// If the card is enrolled for 3DS authentication, the 3DS based authentication will be activated. The liability of chargeback shift to the issuer
     #[default]
     ThreeDs,
+    /// 3DS based authentication will not be activated. The liability of chargeback stays with the merchant.
     NoThreeDs,
 }
 
@@ -72,14 +75,19 @@ pub enum AuthenticationType {
     strum::Display,
     strum::EnumString,
     frunk::LabelledGeneric,
+    ToSchema,
 )]
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum CaptureMethod {
+    /// Post the payment authorization, the capture will be executed on the full amount immediately
     #[default]
     Automatic,
+    /// The capture will happen only if the merchant triggers a Capture API request
     Manual,
+    /// The capture will happen only if the merchant triggers a Capture API request
     ManualMultiple,
+    /// The capture can be scheduled to automatically get triggered at a specific date & time
     Scheduled,
 }
 
@@ -94,6 +102,7 @@ pub enum CaptureMethod {
     serde::Deserialize,
     serde::Serialize,
     frunk::LabelledGeneric,
+    ToSchema,
 )]
 #[strum(serialize_all = "snake_case")]
 #[serde(rename_all = "snake_case")]
@@ -262,6 +271,7 @@ pub enum EventType {
     Default,
     Eq,
     PartialEq,
+    ToSchema,
     serde::Deserialize,
     serde::Serialize,
     strum::Display,
@@ -294,6 +304,7 @@ pub enum IntentStatus {
     strum::Display,
     strum::EnumString,
     frunk::LabelledGeneric,
+    ToSchema,
 )]
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
@@ -396,6 +407,7 @@ pub enum PaymentMethodType {
     Eq,
     Hash,
     PartialEq,
+    ToSchema,
     serde::Deserialize,
     serde::Serialize,
     strum::Display,
@@ -485,6 +497,7 @@ pub enum MandateStatus {
     Default,
     Eq,
     PartialEq,
+    ToSchema,
     serde::Deserialize,
     serde::Serialize,
     strum::Display,

crates/api_models/src/payments.rs

@@ -15,43 +15,122 @@ pub enum PaymentOp {
     Confirm,
 }
 
-#[derive(Default, Debug, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Default, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct PaymentsRequest {
+    /// Unique identifier for the payment. This ensures impotency for multiple payments
+    /// that have been done by a single merchant. This field is auto generated and is returned in the API response.
+    #[schema(
+        value_type = Option<String>,
+        min_length = 30,
+        max_length = 30,
+        example = "pay_mbabizu24mvu3mela5njyhpit4"
+    )]
     #[serde(default, deserialize_with = "payment_id_type::deserialize_option")]
     pub payment_id: Option<PaymentIdType>,
+    /// 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")]
     pub merchant_id: Option<String>,
+    /// 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.,
+    #[schema(value_type = Option<u64>, example = 6540)]
     #[serde(default, deserialize_with = "amount::deserialize_option")]
     pub amount: Option<Amount>,
+    /// This allows the merchant to manually select a connector with which the payment can go through
+    #[schema(value_type = Option<Connector>, max_length = 255, example = "stripe")]
     pub connector: Option<api_enums::Connector>,
+    /// The currency of the payment request can be specified here
+    #[schema(value_type = Option<Currency>, example = "USD")]
     pub currency: Option<api_enums::Currency>,
+    /// 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.
+    #[schema(value_type = Option<CaptureMethod>, example = "PaymentProcessor")]
     pub capture_method: Option<api_enums::CaptureMethod>,
+    /// 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.
+    #[schema(example = 6540)]
     pub amount_to_capture: Option<i64>,
+    /// A timestamp (ISO 8601 code) that determines when the payment should be captured.
+    /// 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")]
     pub capture_on: Option<PrimitiveDateTime>,
+    /// Whether to confirm the payment (if applicable)
+    #[schema(default = false, example = true)]
     pub confirm: Option<bool>,
+    /// The identifier for the customer object. If not provided the customer ID will be autogenerated.
+    #[schema(max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
     pub customer_id: Option<String>,
+    /// description: The customer's email address
+    #[schema(max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
     pub email: Option<Secret<String, pii::Email>>,
+    /// description: The customer's name
+    #[schema(value_type = Option<String>, max_length = 255, example = "John Test")]
     pub name: Option<Secret<String>>,
+    /// The customer's phone number
+    #[schema(value_type = Option<String>, max_length = 255, example = "3141592653")]
     pub phone: Option<Secret<String>>,
+    /// The country code for the customer phone number
+    #[schema(max_length = 255, example = "+1")]
     pub phone_country_code: Option<String>,
+    /// 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`.
+    #[schema(example = true)]
     pub off_session: Option<bool>,
+    /// A description of the payment
+    #[schema(example = "It's my first payment request")]
     pub description: Option<String>,
+    /// The URL to redirect after the completion of the operation
+    #[schema(example = "https://hyperswitch.io")]
     pub return_url: Option<String>,
+    /// 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 transaction authentication can be set to undergo payer authentication.
+    #[schema(value_type = Option<AuthenticationType>, example = "no_three_ds", default = "three_ds")]
     pub authentication_type: Option<api_enums::AuthenticationType>,
+    /// The payment method information provided for making a payment
+    #[schema(example = "bank_transfer")]
     pub payment_method_data: Option<PaymentMethod>,
+    /// The payment method that is to be used
+    #[schema(value_type = Option<PaymentMethodType>, example = "bank_transfer")]
     pub payment_method: Option<api_enums::PaymentMethodType>,
+    /// Provide a reference to a stored payment method
+    #[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
     pub payment_token: Option<String>,
+
+    #[schema(value_type = Option<String>)]
     pub card_cvc: Option<Secret<String>>,
+    /// The shipping address for the payment
     pub shipping: Option<Address>,
+    /// The billing address for the payment
     pub billing: Option<Address>,
+    /// 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.
+    #[schema(max_length = 255, example = "Juspay Router")]
     pub statement_descriptor_name: Option<String>,
+    /// 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 22 characters for the concatenated descriptor.
+    #[schema(max_length = 255, example = "Payment for shoes purchase")]
     pub statement_descriptor_suffix: Option<String>,
+    /// 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.
     pub metadata: Option<Metadata>,
+    /// It's a token used for client side verification.
+    #[schema(example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
     pub client_secret: Option<String>,
+    /// Provide mandate information for creating a mandate
     pub mandate_data: Option<MandateData>,
+    /// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
+    #[schema(max_length = 255, example = "mandate_iwer89rnjef349dni3")]
     pub mandate_id: Option<String>,
+    /// Additional details required by 3DS 2.0
+    #[schema(value_type = Option<Object>, example = r#"{
+        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
+        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
+        "language": "nl-NL",
+        "color_depth": 24,
+        "screen_height": 723,
+        "screen_width": 1536,
+        "time_zone": 0,
+        "java_enabled": true,
+        "java_script_enabled":true
+    }"#)]
     pub browser_info: Option<serde_json::Value>,
 }
 
@@ -147,10 +226,12 @@ impl MandateIds {
     }
 }
 
-#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct MandateData {
+    /// A concent from the customer to store the payment method
     pub customer_acceptance: CustomerAcceptance,
+    /// A way to select the type of mandate used
     pub mandate_type: MandateType,
 }
 
@@ -160,16 +241,24 @@ pub struct SingleUseMandate {
     pub currency: api_enums::Currency,
 }
 
-#[derive(Clone, Eq, PartialEq, Copy, Debug, Default, serde::Serialize, serde::Deserialize)]
+#[derive(
+    Clone, Eq, PartialEq, Copy, Debug, Default, ToSchema, serde::Serialize, serde::Deserialize,
+)]
 pub struct MandateAmountData {
+    /// The maximum amount to be debited for the mandate transaction
+    #[schema(example = 6540)]
     pub amount: i64,
+    /// The currency for the transaction
+    #[schema(value_type = Currency, example = "USD")]
     pub currency: api_enums::Currency,
 }
 
-#[derive(Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum MandateType {
+    /// If the mandate should only be valid for 1 off-session use
     SingleUse(MandateAmountData),
+    /// If the mandate should be valid for multiple debits
     MultiUse(Option<MandateAmountData>),
 }
 
@@ -179,16 +268,21 @@ impl Default for MandateType {
     }
 }
 
-#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct CustomerAcceptance {
+    /// Type of acceptance provided by the
+    #[schema(example = "online")]
     pub acceptance_type: AcceptanceType,
+    /// Specifying when the customer acceptance was provided
+    #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(default, with = "common_utils::custom_serde::iso8601::option")]
     pub accepted_at: Option<PrimitiveDateTime>,
+    /// Information required for online mandate generation
     pub online: Option<OnlineMandate>,
 }
 
-#[derive(Default, Debug, serde::Deserialize, serde::Serialize, PartialEq, Eq, Clone)]
+#[derive(Default, Debug, serde::Deserialize, serde::Serialize, PartialEq, Eq, Clone, ToSchema)]
 #[serde(rename_all = "lowercase")]
 pub enum AcceptanceType {
     Online,
@@ -196,52 +290,74 @@ pub enum AcceptanceType {
     Offline,
 }
 
-#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Default, Eq, PartialEq, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct OnlineMandate {
+    /// Ip address of the customer machine from which the mandate was created
+    #[schema(value_type = String, example = "123.32.25.123")]
     pub ip_address: Secret<String, pii::IpAddress>,
+    /// The user-agent of the customer's browser
     pub user_agent: String,
 }
 
-#[derive(Default, Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Default, Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize, ToSchema)]
 pub struct CCard {
+    /// The card number
+    #[schema(value_type = String, example = "4242424242424242")]
     pub card_number: Secret<String, pii::CardNumber>,
+    /// The card's expiry month
+    #[schema(value_type = String, example = "24")]
     pub card_exp_month: Secret<String>,
+    /// The card's expiry year
+    #[schema(value_type = String, example = "24")]
     pub card_exp_year: Secret<String>,
+    /// The card holder's name
+    #[schema(value_type = String, example = "John Test")]
     pub card_holder_name: Secret<String>,
+    /// The CVC number for the card
+    #[schema(value_type = String, example = "242")]
     pub card_cvc: Secret<String>,
 }
 
-#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum KlarnaRedirectIssuer {
     Stripe,
 }
 
-#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum KlarnaSdkIssuer {
     Klarna,
 }
 
-#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum PayLaterData {
+    /// For KlarnaRedirect as PayLater Option
     KlarnaRedirect {
+        /// The issuer name of the redirect
         issuer_name: KlarnaRedirectIssuer,
+        /// The billing email
         billing_email: String,
+        // The billing country code
         billing_country: String,
     },
+    /// For Klarna Sdk as PayLater Option
     KlarnaSdk {
+        /// The issuer name of the redirect
         issuer_name: KlarnaSdkIssuer,
+        /// The token for the sdk workflow
         token: String,
     },
+    /// For Affirm redirect flow
     AffirmRedirect {
+        /// The billing email address
         billing_email: String,
     },
 }
 
-#[derive(Debug, Clone, Eq, PartialEq, Default, serde::Deserialize, serde::Serialize)]
+#[derive(Debug, Clone, Eq, PartialEq, Default, serde::Deserialize, serde::Serialize, ToSchema)]
 pub enum PaymentMethod {
     #[serde(rename(deserialize = "card"))]
     Card(CCard),
@@ -256,9 +372,12 @@ pub enum PaymentMethod {
     Paypal,
 }
 
-#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize)]
+#[derive(Eq, PartialEq, Clone, Debug, serde::Deserialize, serde::Serialize, ToSchema)]
 pub struct WalletData {
+    /// The issuer of the wallet
+    #[schema(value_type = WalletIssuer)]
     pub issuer_name: api_enums::WalletIssuer,
+    /// Token generated for the wallet
     pub token: Option<String>,
 }
 
@@ -312,13 +431,16 @@ impl Default for PaymentIdType {
     Debug,
     Eq,
     PartialEq,
+    ToSchema,
     serde::Deserialize,
     serde::Serialize,
     frunk::LabelledGeneric,
 )]
 #[serde(deny_unknown_fields)]
 pub struct Address {
+    /// Provide the address details
     pub address: Option<AddressDetails>,
+
     pub phone: Option<PhoneDetails>,
 }
 
@@ -379,12 +501,17 @@ pub struct AddressDetails {
     Default,
     Eq,
     PartialEq,
+    ToSchema,
     serde::Deserialize,
     serde::Serialize,
     frunk::LabelledGeneric,
 )]
 pub struct PhoneDetails {
+    /// The contact number
+    #[schema(value_type = Option<String>, example = "9999999999")]
     pub number: Option<Secret<String>>,
+    /// The country code attached to the number
+    #[schema(example = "+1")]
     pub country_code: Option<String>,
 }
 
@@ -407,7 +534,7 @@ pub struct UrlDetails {
 pub struct AuthenticationForStartResponse {
     pub authentication: UrlDetails,
 }
-#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum NextActionType {
     RedirectToUrl,
@@ -415,54 +542,131 @@ pub enum NextActionType {
     InvokeSdkClient,
     TriggerApi,
 }
-#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, ToSchema)]
 pub struct NextAction {
+    /// Specifying the action type to be performed next
     #[serde(rename = "type")]
     pub next_action_type: NextActionType,
+    /// Contains the url for redirection flow
+    #[schema(example = "https://router.juspay.io/redirect/fakushdfjlksdfasklhdfj")]
     pub redirect_to_url: Option<String>,
 }
 
-#[derive(Setter, Clone, Default, Debug, Eq, PartialEq, serde::Serialize)]
+#[derive(Setter, Clone, Default, Debug, Eq, PartialEq, serde::Serialize, ToSchema)]
 pub struct PaymentsResponse {
+    /// Unique identifier for the payment. This ensures impotency for multiple payments
+    /// that have been done by a single merchant.
+    #[schema(
+        min_length = 30,
+        max_length = 30,
+        example = "pay_mbabizu24mvu3mela5njyhpit4"
+    )]
     pub payment_id: Option<String>,
+    /// 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")]
     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,
+    /// 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.,
+    #[schema(example = 100)]
     pub amount: i64,
+    /// The maximum amount that could be captured from the payment
+    #[schema(minimum = 100, example = 6540)]
     pub amount_capturable: Option<i64>,
+    /// The amount which is already captured from the payment
+    #[schema(minimum = 100, example = 6540)]
     pub amount_received: Option<i64>,
+    /// The connector used for the payment
+    #[schema(example = "stripe")]
     pub connector: Option<String>,
+    /// It's a token used for client side verification.
+    #[schema(value_type = Option<String>, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
     pub client_secret: Option<Secret<String>>,
+    /// Time when the payment was created
+    #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(with = "common_utils::custom_serde::iso8601::option")]
     pub created: Option<PrimitiveDateTime>,
+    /// The currency of the amount of the payment
+    #[schema(value_type = Currency, example = "USD")]
     pub currency: String,
+    /// The identifier for the customer object. If not provided the customer ID will be autogenerated.
+    #[schema(max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
     pub customer_id: Option<String>,
+    /// 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
+    #[schema(value_type = Option<Vec<RefundResponse>>)]
     pub refunds: Option<Vec<refunds::RefundResponse>>,
+    /// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
+    #[schema(max_length = 255, example = "mandate_iwer89rnjef349dni3")]
     pub mandate_id: Option<String>,
+    /// Provided mandate information for creating a mandate
     pub mandate_data: Option<MandateData>,
+    /// 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>,
+    /// 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.
+    #[schema(example = true)]
     pub off_session: Option<bool>,
+    /// A timestamp (ISO 8601 code) that determines when the payment should be captured.
+    /// Providing this field will automatically set `capture` to true
+    #[schema(example = "2022-09-10T10:11:12Z")]
     #[serde(with = "common_utils::custom_serde::iso8601::option")]
     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.
+    #[schema(value_type = Option<CaptureMethod>, example = "PaymentProcessor")]
     pub capture_method: Option<api_enums::CaptureMethod>,
+    /// The payment method that is to be used
+    #[schema(value_type = PaymentMethodType, example = "bank_transfer")]
     #[auth_based]
     pub payment_method: Option<api_enums::PaymentMethodType>,
+    /// The payment method information provided for making a payment
+    #[schema(value_type = Option<PaymentMethod>, example = "bank_transfer")]
     #[auth_based]
     pub payment_method_data: Option<PaymentMethodDataResponse>,
+    /// Provide a reference to a stored payment method
+    #[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
     pub payment_token: Option<String>,
+    /// The shipping address for the payment
     pub shipping: Option<Address>,
+    /// The billing address for the payment
     pub billing: Option<Address>,
+    /// 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>)]
     pub metadata: Option<serde_json::Value>,
+    /// description: The customer's email address
+    #[schema(max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
     pub email: Option<Secret<String, pii::Email>>,
+    /// description: The customer's name
+    #[schema(value_type = Option<String>, max_length = 255, example = "John Test")]
     pub name: Option<Secret<String>>,
+    /// The customer's phone number
+    #[schema(value_type = Option<String>, max_length = 255, example = "3141592653")]
     pub phone: Option<Secret<String>>,
+    /// The URL to redirect after the completion of the operation
+    #[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
+    #[schema(value_type = Option<AuthenticationType>, example = "no_three_ds", default = "three_ds")]
     pub authentication_type: Option<api_enums::AuthenticationType>,
+    /// 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.
+    #[schema(max_length = 255, example = "Juspay Router")]
     pub statement_descriptor_name: Option<String>,
+    /// 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.
+    #[schema(max_length = 255, example = "Payment for shoes purchase")]
     pub statement_descriptor_suffix: Option<String>,
+    /// Additional information required for redirection
     pub next_action: Option<NextAction>,
+    /// If the payment was cancelled the reason provided here
     pub cancellation_reason: Option<String>,
+    /// If there was an error while calling the connectors the code is received here
+    #[schema(example = "E0001")]
     pub error_code: Option<String>,
+    /// If there was an error while calling the connector the error message is received here
+    #[schema(example = "Failed while verifying the card")]
     pub error_message: Option<String>,
 }
 
@@ -754,15 +958,22 @@ pub struct PaymentsRetrieveRequest {
     pub connector: Option<String>,
 }
 
-#[derive(Debug, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Debug, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 pub struct OrderDetails {
+    /// Name of the product that is being purchased
+    #[schema(max_length = 255, example = "shirt")]
     pub product_name: String,
+    /// The quantity of the product to be purchased
+    #[schema(example = 1)]
     pub quantity: u16,
 }
 
-#[derive(Default, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize, Clone)]
+#[derive(Default, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
 pub struct Metadata {
+    /// Information about the product and quantity for specific connectors. (e.g. Klarna)
     pub order_details: Option<OrderDetails>,
+    /// Any other metadata that is to be provided
+    #[schema(value_type = Object, example = r#"{ "city": "NY", "unit": "245" }"#)]
     #[serde(flatten)]
     pub data: serde_json::Value,
 }

crates/router/Cargo.toml

@@ -69,7 +69,7 @@ time = { version = "0.3.17", features = ["serde", "serde-well-known", "std"] }
 tokio = { version = "1.24.1", features = ["macros", "rt-multi-thread"] }
 url = { version = "2.3.1", features = ["serde"] }
 # Switch to the crates.io release of `utoipa` when the `preserve_order` feature is available in the release
-utoipa = { git = "https://github.com/juhaku/utoipa", rev = "2a5c09d953f14dc78af655bbcfd016ce9a71baa0", features = ["preserve_order"] }
+utoipa = { git = "https://github.com/juhaku/utoipa", rev = "2a5c09d953f14dc78af655bbcfd016ce9a71baa0", features = ["preserve_order", "time"] }
 uuid = { version = "1.2.2", features = ["serde", "v4"] }
 
 # First party crates

crates/router/src/openapi.rs

@@ -44,7 +44,8 @@ Never share your secret api keys. Keep them guarded and secure.
     ),
     paths(
         crate::routes::refunds::refunds_create,
-        crate::routes::admin::merchant_account_create
+        crate::routes::admin::merchant_account_create,
+        crate::routes::payments::payments_create
     ),
     components(schemas(
         crate::types::api::refunds::RefundRequest,
@@ -57,7 +58,34 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::enums::PaymentMethodType,
         api_models::enums::PaymentMethodSubType,
         api_models::enums::Currency,
+        api_models::enums::IntentStatus,
+        api_models::enums::CaptureMethod,
+        api_models::enums::FutureUsage,
+        api_models::enums::AuthenticationType,
+        api_models::enums::WalletIssuer,
+        api_models::enums::Connector,
+        api_models::enums::PaymentMethodType,
         api_models::payments::AddressDetails,
+        api_models::payments::Address,
+        api_models::payments::OrderDetails,
+        api_models::payments::NextActionType,
+        api_models::payments::Metadata,
+        api_models::payments::WalletData,
+        api_models::payments::KlarnaRedirectIssuer,
+        api_models::payments::KlarnaSdkIssuer,
+        api_models::payments::NextAction,
+        api_models::payments::PayLaterData,
+        api_models::payments::MandateData,
+        api_models::payments::PhoneDetails,
+        api_models::payments::PaymentMethod,
+        api_models::payments::MandateType,
+        api_models::payments::AcceptanceType,
+        api_models::payments::MandateAmountData,
+        api_models::payments::OnlineMandate,
+        api_models::payments::CCard,
+        api_models::payments::CustomerAcceptance,
+        api_models::payments::PaymentsRequest,
+        api_models::payments::PaymentsResponse,
         crate::types::api::admin::MerchantAccountResponse,
         crate::types::api::admin::MerchantConnectorId,
         crate::types::api::admin::MerchantDetails,

crates/router/src/routes/payments.rs

@@ -9,6 +9,18 @@ use crate::{
     types::api::{self as api_types, enums as api_enums, payments as payment_types},
 };
 
+/// Payments - Create
+///
+/// To create a new payment, against a merchant API key
+#[utoipa::path(
+    post,
+    path = "/payments",
+    request_body=PaymentsRequest,
+    responses(
+        (status = 200, description = "Payment created", body = PaymentsResponse),
+        (status = 400, description = "Missing Mandatory fields")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentsCreate))]
 // #[post("")]
 pub async fn payments_create(

openapi/generated.json

@@ -60,6 +60,42 @@
         "deprecated": false
       }
     },
+    "/payments": {
+      "post": {
+        "tags": [
+          "crate::routes::payments"
+        ],
+        "summary": "Payments - Create",
+        "description": "Payments - Create\n\nTo create a new payment, against a merchant API key",
+        "operationId": "payments_create",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PaymentsRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Payment created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PaymentsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Missing Mandatory fields"
+          }
+        },
+        "deprecated": false
+      }
+    },
     "/refunds": {
       "post": {
         "tags": [
@@ -99,6 +135,24 @@
   },
   "components": {
     "schemas": {
+      "AcceptanceType": {
+        "type": "string",
+        "enum": [
+          "online",
+          "offline"
+        ]
+      },
+      "Address": {
+        "type": "object",
+        "properties": {
+          "address": {
+            "$ref": "#/components/schemas/AddressDetails"
+          },
+          "phone": {
+            "$ref": "#/components/schemas/PhoneDetails"
+          }
+        }
+      },
       "AddressDetails": {
         "type": "object",
         "properties": {
@@ -158,6 +212,79 @@
           }
         }
       },
+      "AuthenticationType": {
+        "type": "string",
+        "enum": [
+          "three_ds",
+          "no_three_ds"
+        ]
+      },
+      "CCard": {
+        "type": "object",
+        "required": [
+          "card_number",
+          "card_exp_month",
+          "card_exp_year",
+          "card_holder_name",
+          "card_cvc"
+        ],
+        "properties": {
+          "card_number": {
+            "type": "string",
+            "description": "The card number",
+            "example": "4242424242424242"
+          },
+          "card_exp_month": {
+            "type": "string",
+            "description": "The card's expiry month",
+            "example": "24"
+          },
+          "card_exp_year": {
+            "type": "string",
+            "description": "The card's expiry year",
+            "example": "24"
+          },
+          "card_holder_name": {
+            "type": "string",
+            "description": "The card holder's name",
+            "example": "John Test"
+          },
+          "card_cvc": {
+            "type": "string",
+            "description": "The CVC number for the card",
+            "example": "242"
+          }
+        }
+      },
+      "CaptureMethod": {
+        "type": "string",
+        "enum": [
+          "automatic",
+          "manual",
+          "manual_multiple",
+          "scheduled"
+        ]
+      },
+      "Connector": {
+        "type": "string",
+        "enum": [
+          "aci",
+          "adyen",
+          "applepay",
+          "authorizedotnet",
+          "braintree",
+          "checkout",
+          "cybersource",
+          "dummy",
+          "fiserv",
+          "globalpay",
+          "klarna",
+          "payu",
+          "shift4",
+          "stripe",
+          "worldpay"
+        ]
+      },
       "CreateMerchantAccount": {
         "type": "object",
         "required": [
@@ -186,7 +313,7 @@
           "return_url": {
             "type": "string",
             "description": "The URL to redirect after the completion of the operation",
-            "example": "www.example.com/success",
+            "example": "https://www.example.com/success",
             "maxLength": 255
           },
           "webhook_details": {
@@ -520,6 +647,117 @@
           }
         }
       },
+      "CustomerAcceptance": {
+        "type": "object",
+        "required": [
+          "acceptance_type"
+        ],
+        "properties": {
+          "acceptance_type": {
+            "$ref": "#/components/schemas/AcceptanceType"
+          },
+          "accepted_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Specifying when the customer acceptance was provided",
+            "example": "2022-09-10T10:11:12Z"
+          },
+          "online": {
+            "$ref": "#/components/schemas/OnlineMandate"
+          }
+        }
+      },
+      "FutureUsage": {
+        "type": "string",
+        "enum": [
+          "off_session",
+          "on_session"
+        ]
+      },
+      "IntentStatus": {
+        "type": "string",
+        "enum": [
+          "succeeded",
+          "failed",
+          "cancelled",
+          "processing",
+          "requires_customer_action",
+          "requires_payment_method",
+          "requires_confirmation",
+          "requires_capture"
+        ]
+      },
+      "KlarnaRedirectIssuer": {
+        "type": "string",
+        "enum": [
+          "stripe"
+        ]
+      },
+      "KlarnaSdkIssuer": {
+        "type": "string",
+        "enum": [
+          "klarna"
+        ]
+      },
+      "MandateAmountData": {
+        "type": "object",
+        "required": [
+          "amount",
+          "currency"
+        ],
+        "properties": {
+          "amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The maximum amount to be debited for the mandate transaction",
+            "example": 6540
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          }
+        }
+      },
+      "MandateData": {
+        "type": "object",
+        "required": [
+          "customer_acceptance",
+          "mandate_type"
+        ],
+        "properties": {
+          "customer_acceptance": {
+            "$ref": "#/components/schemas/CustomerAcceptance"
+          },
+          "mandate_type": {
+            "$ref": "#/components/schemas/MandateType"
+          }
+        }
+      },
+      "MandateType": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "single_use"
+            ],
+            "properties": {
+              "single_use": {
+                "$ref": "#/components/schemas/MandateAmountData"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "multi_use"
+            ],
+            "properties": {
+              "multi_use": {
+                "$ref": "#/components/schemas/MandateAmountData"
+              }
+            }
+          }
+        ]
+      },
       "MerchantAccountResponse": {
         "type": "object",
         "required": [
@@ -548,7 +786,7 @@
           "return_url": {
             "type": "string",
             "description": "The URL to redirect after the completion of the operation",
-            "example": "www.example.com/success",
+            "example": "https://www.example.com/success",
             "maxLength": 255
           },
           "webhook_details": {
@@ -678,6 +916,213 @@
           }
         }
       },
+      "Metadata": {
+        "allOf": [
+          {
+            "type": "object"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "order_details": {
+                "$ref": "#/components/schemas/OrderDetails"
+              }
+            }
+          }
+        ]
+      },
+      "NextAction": {
+        "type": "object",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/NextActionType"
+          },
+          "redirect_to_url": {
+            "type": "string",
+            "description": "Contains the url for redirection flow",
+            "example": "https://router.juspay.io/redirect/fakushdfjlksdfasklhdfj"
+          }
+        }
+      },
+      "NextActionType": {
+        "type": "string",
+        "enum": [
+          "redirect_to_url",
+          "display_qr_code",
+          "invoke_sdk_client",
+          "trigger_api"
+        ]
+      },
+      "OnlineMandate": {
+        "type": "object",
+        "required": [
+          "ip_address",
+          "user_agent"
+        ],
+        "properties": {
+          "ip_address": {
+            "type": "string",
+            "description": "Ip address of the customer machine from which the mandate was created",
+            "example": "123.32.25.123"
+          },
+          "user_agent": {
+            "type": "string",
+            "description": "The user-agent of the customer's browser"
+          }
+        }
+      },
+      "OrderDetails": {
+        "type": "object",
+        "required": [
+          "product_name",
+          "quantity"
+        ],
+        "properties": {
+          "product_name": {
+            "type": "string",
+            "description": "Name of the product that is being purchased",
+            "example": "shirt",
+            "maxLength": 255
+          },
+          "quantity": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The quantity of the product to be purchased",
+            "example": 1
+          }
+        }
+      },
+      "PayLaterData": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "klarna_redirect"
+            ],
+            "properties": {
+              "klarna_redirect": {
+                "type": "object",
+                "description": "For KlarnaRedirect as PayLater Option",
+                "required": [
+                  "issuer_name",
+                  "billing_email",
+                  "billing_country"
+                ],
+                "properties": {
+                  "issuer_name": {
+                    "$ref": "#/components/schemas/KlarnaRedirectIssuer"
+                  },
+                  "billing_email": {
+                    "type": "string",
+                    "description": "The billing email"
+                  },
+                  "billing_country": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "klarna_sdk"
+            ],
+            "properties": {
+              "klarna_sdk": {
+                "type": "object",
+                "description": "For Klarna Sdk as PayLater Option",
+                "required": [
+                  "issuer_name",
+                  "token"
+                ],
+                "properties": {
+                  "issuer_name": {
+                    "$ref": "#/components/schemas/KlarnaSdkIssuer"
+                  },
+                  "token": {
+                    "type": "string",
+                    "description": "The token for the sdk workflow"
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "affirm_redirect"
+            ],
+            "properties": {
+              "affirm_redirect": {
+                "type": "object",
+                "description": "For Affirm redirect flow",
+                "required": [
+                  "billing_email"
+                ],
+                "properties": {
+                  "billing_email": {
+                    "type": "string",
+                    "description": "The billing email address"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "PaymentMethod": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "Card"
+            ],
+            "properties": {
+              "Card": {
+                "$ref": "#/components/schemas/CCard"
+              }
+            }
+          },
+          {
+            "type": "string",
+            "enum": [
+              "BankTransfer"
+            ]
+          },
+          {
+            "type": "object",
+            "required": [
+              "Wallet"
+            ],
+            "properties": {
+              "Wallet": {
+                "$ref": "#/components/schemas/WalletData"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "PayLater"
+            ],
+            "properties": {
+              "PayLater": {
+                "$ref": "#/components/schemas/PayLaterData"
+              }
+            }
+          },
+          {
+            "type": "string",
+            "enum": [
+              "Paypal"
+            ]
+          }
+        ]
+      },
       "PaymentMethodSubType": {
         "type": "string",
         "enum": [
@@ -706,6 +1151,359 @@
           "paypal"
         ]
       },
+      "PaymentsRequest": {
+        "type": "object",
+        "properties": {
+          "payment_id": {
+            "type": "string",
+            "description": "Unique identifier for the payment. This ensures impotency 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",
+            "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",
+            "maxLength": 255
+          },
+          "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
+          },
+          "connector": {
+            "$ref": "#/components/schemas/Connector"
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          },
+          "capture_method": {
+            "$ref": "#/components/schemas/CaptureMethod"
+          },
+          "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.,\nIf not provided, the default amount_to_capture will be the payment amount.",
+            "example": 6540
+          },
+          "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"
+          },
+          "confirm": {
+            "type": "boolean",
+            "description": "Whether to confirm the payment (if applicable)",
+            "default": false,
+            "example": true
+          },
+          "customer_id": {
+            "type": "string",
+            "description": "The identifier for the customer object. If not provided the customer ID will be autogenerated.",
+            "example": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
+            "maxLength": 255
+          },
+          "email": {
+            "type": "string",
+            "description": "description: The customer's email address",
+            "example": "johntest@test.com",
+            "maxLength": 255
+          },
+          "name": {
+            "type": "string",
+            "description": "description: The customer's name",
+            "example": "John Test",
+            "maxLength": 255
+          },
+          "phone": {
+            "type": "string",
+            "description": "The customer's phone number",
+            "example": "3141592653",
+            "maxLength": 255
+          },
+          "phone_country_code": {
+            "type": "string",
+            "description": "The country code for the customer phone number",
+            "example": "+1",
+            "maxLength": 255
+          },
+          "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
+          },
+          "description": {
+            "type": "string",
+            "description": "A description of the payment",
+            "example": "It's my first payment request"
+          },
+          "return_url": {
+            "type": "string",
+            "description": "The URL to redirect after the completion of the operation",
+            "example": "https://hyperswitch.io"
+          },
+          "setup_future_usage": {
+            "$ref": "#/components/schemas/FutureUsage"
+          },
+          "authentication_type": {
+            "$ref": "#/components/schemas/AuthenticationType"
+          },
+          "payment_method_data": {
+            "$ref": "#/components/schemas/PaymentMethod"
+          },
+          "payment_method": {
+            "$ref": "#/components/schemas/PaymentMethodType"
+          },
+          "payment_token": {
+            "type": "string",
+            "description": "Provide a reference to a stored payment method",
+            "example": "187282ab-40ef-47a9-9206-5099ba31e432"
+          },
+          "card_cvc": {
+            "type": "string"
+          },
+          "shipping": {
+            "$ref": "#/components/schemas/Address"
+          },
+          "billing": {
+            "$ref": "#/components/schemas/Address"
+          },
+          "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": "Juspay Router",
+            "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 22 characters for the concatenated descriptor.",
+            "example": "Payment for shoes purchase",
+            "maxLength": 255
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/Metadata"
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "It's a token used for client side verification.",
+            "example": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"
+          },
+          "mandate_data": {
+            "$ref": "#/components/schemas/MandateData"
+          },
+          "mandate_id": {
+            "type": "string",
+            "description": "A unique identifier to link the payment to a mandate, can be use instead of payment_method_data",
+            "example": "mandate_iwer89rnjef349dni3",
+            "maxLength": 255
+          },
+          "browser_info": {
+            "type": "object"
+          }
+        }
+      },
+      "PaymentsResponse": {
+        "type": "object",
+        "required": [
+          "status",
+          "amount",
+          "currency",
+          "payment_method"
+        ],
+        "properties": {
+          "payment_id": {
+            "type": "string",
+            "description": "Unique identifier for the payment. This ensures impotency for multiple payments\nthat have been done by a single merchant.",
+            "example": "pay_mbabizu24mvu3mela5njyhpit4",
+            "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",
+            "maxLength": 255
+          },
+          "status": {
+            "$ref": "#/components/schemas/IntentStatus"
+          },
+          "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": 100
+          },
+          "amount_capturable": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The maximum amount that could be captured from the payment",
+            "example": 6540,
+            "minimum": 100.0
+          },
+          "amount_received": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The amount which is already captured from the payment",
+            "example": 6540,
+            "minimum": 100.0
+          },
+          "connector": {
+            "type": "string",
+            "description": "The connector used for the payment",
+            "example": "stripe"
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "It's a token used for client side verification.",
+            "example": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"
+          },
+          "created": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Time when the payment was created",
+            "example": "2022-09-10T10:11:12Z"
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          },
+          "customer_id": {
+            "type": "string",
+            "description": "The identifier for the customer object. If not provided the customer ID will be autogenerated.",
+            "example": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
+            "maxLength": 255
+          },
+          "description": {
+            "type": "string",
+            "description": "A description of the payment",
+            "example": "It's my first payment request"
+          },
+          "refunds": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RefundResponse"
+            }
+          },
+          "mandate_id": {
+            "type": "string",
+            "description": "A unique identifier to link the payment to a mandate, can be use instead of payment_method_data",
+            "example": "mandate_iwer89rnjef349dni3",
+            "maxLength": 255
+          },
+          "mandate_data": {
+            "$ref": "#/components/schemas/MandateData"
+          },
+          "setup_future_usage": {
+            "$ref": "#/components/schemas/FutureUsage"
+          },
+          "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
+          },
+          "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"
+          },
+          "capture_method": {
+            "$ref": "#/components/schemas/CaptureMethod"
+          },
+          "payment_method": {
+            "$ref": "#/components/schemas/PaymentMethodType"
+          },
+          "payment_method_data": {
+            "$ref": "#/components/schemas/PaymentMethod"
+          },
+          "payment_token": {
+            "type": "string",
+            "description": "Provide a reference to a stored payment method",
+            "example": "187282ab-40ef-47a9-9206-5099ba31e432"
+          },
+          "shipping": {
+            "$ref": "#/components/schemas/Address"
+          },
+          "billing": {
+            "$ref": "#/components/schemas/Address"
+          },
+          "metadata": {
+            "type": "object"
+          },
+          "email": {
+            "type": "string",
+            "description": "description: The customer's email address",
+            "example": "johntest@test.com",
+            "maxLength": 255
+          },
+          "name": {
+            "type": "string",
+            "description": "description: The customer's name",
+            "example": "John Test",
+            "maxLength": 255
+          },
+          "phone": {
+            "type": "string",
+            "description": "The customer's phone number",
+            "example": "3141592653",
+            "maxLength": 255
+          },
+          "return_url": {
+            "type": "string",
+            "description": "The URL to redirect after the completion of the operation",
+            "example": "https://hyperswitch.io"
+          },
+          "authentication_type": {
+            "$ref": "#/components/schemas/AuthenticationType"
+          },
+          "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": "Juspay Router",
+            "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",
+            "maxLength": 255
+          },
+          "next_action": {
+            "$ref": "#/components/schemas/NextAction"
+          },
+          "cancellation_reason": {
+            "type": "string",
+            "description": "If the payment was cancelled the reason provided here"
+          },
+          "error_code": {
+            "type": "string",
+            "description": "If there was an error while calling the connectors the code is received here",
+            "example": "E0001"
+          },
+          "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"
+          }
+        }
+      },
+      "PhoneDetails": {
+        "type": "object",
+        "properties": {
+          "number": {
+            "type": "string",
+            "description": "The contact number",
+            "example": "9999999999"
+          },
+          "country_code": {
+            "type": "string",
+            "description": "The country code attached to the number",
+            "example": "+1"
+          }
+        }
+      },
       "RefundRequest": {
         "type": "object",
         "required": [
@@ -817,6 +1615,29 @@
         ],
         "example": "custom"
       },
+      "WalletData": {
+        "type": "object",
+        "required": [
+          "issuer_name"
+        ],
+        "properties": {
+          "issuer_name": {
+            "$ref": "#/components/schemas/WalletIssuer"
+          },
+          "token": {
+            "type": "string",
+            "description": "Token generated for the wallet"
+          }
+        }
+      },
+      "WalletIssuer": {
+        "type": "string",
+        "enum": [
+          "googlepay",
+          "applepay",
+          "paypal"
+        ]
+      },
       "WebhookDetails": {
         "type": "object",
         "properties": {