chore: Added docs for payment connector create (#394)

Co-authored-by: Sanchith Hegde <22217505+SanchithHegde@users.noreply.github.com>

crates/api_models/src/admin.rs

@@ -33,6 +33,7 @@ pub struct CreateMerchantAccount {
     pub webhook_details: Option<WebhookDetails>,
 
     /// The routing algorithm to be used for routing payments to desired connectors
+    #[schema(value_type = Option<Object>,example = json!({"type": "single", "data": "stripe"}))]
     pub routing_algorithm: Option<serde_json::Value>,
 
     /// A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false.
@@ -163,33 +164,101 @@ pub struct MerchantConnectorId {
     pub merchant_id: String,
     pub merchant_connector_id: i32,
 }
-//Merchant Connector Account CRUD
+
-#[derive(Debug, Clone, Serialize, Deserialize)]
+/// Create a new Payment Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc."
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct PaymentConnectorCreate {
+    /// Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking.
+    #[schema(value_type = ConnectorType, example = "payment_processor")]
     pub connector_type: api_enums::ConnectorType,
+    /// Name of the Connector
+    #[schema(example = "stripe")]
     pub connector_name: String,
+    /// Unique ID of the connector
+    #[schema(example = 42)]
     pub merchant_connector_id: Option<i32>,
+    /// Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object.
+    #[schema(value_type = Option<Object>,example = json!({ "auth_type": "HeaderKey","api_key": "Basic MyVerySecretApiKey" }))]
     pub connector_account_details: Option<Secret<serde_json::Value>>,
+    /// A boolean value to indicate if the connector is in Test mode. By default, its value is false.
+    #[schema(default = false, example = false)]
     pub test_mode: Option<bool>,
+    /// A boolean value to indicate if the connector is disabled. By default, its value is false.
+    #[schema(default = false, example = false)]
     pub disabled: Option<bool>,
+    /// Refers to the Parent Merchant ID if the merchant being created is a sub-merchant
+    #[schema(example = json!([
+        {
+            "payment_method": "wallet",
+            "payment_method_types": [
+                "upi_collect",
+                "upi_intent"
+            ],
+            "payment_method_issuers": [
+                "labore magna ipsum",
+                "aute"
+            ],
+            "payment_schemes": [
+                "Discover",
+                "Discover"
+            ],
+            "accepted_currencies": [
+                "AED",
+                "AED"
+            ],
+            "accepted_countries": [
+                "in",
+                "us"
+            ],
+            "minimum_amount": 1,
+            "maximum_amount": 68607706,
+            "recurring_enabled": true,
+            "installment_payment_enabled": true
+        }
+    ]))]
     pub payment_methods_enabled: Option<Vec<PaymentMethods>>,
+    /// 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>,max_length = 255,example = json!({ "city": "NY", "unit": "245" }))]
     pub metadata: Option<serde_json::Value>,
 }
-
+/// Details of all the payment methods enabled for the connector for the given merchant account
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(deny_unknown_fields)]
 pub struct PaymentMethods {
+    /// Type of payment method.
+    #[schema(value_type = PaymentMethodType,example = "card")]
     pub payment_method: api_enums::PaymentMethodType,
+    /// Subtype of payment method
+    #[schema(value_type = Option<Vec<PaymentMethodSubType>>,example = json!(["credit"]))]
     pub payment_method_types: Option<Vec<api_enums::PaymentMethodSubType>>,
+    /// List of payment method issuers to be enabled for this payment method
+    #[schema(example = json!(["HDFC"]))]
     pub payment_method_issuers: Option<Vec<String>>,
+    /// List of payment schemes accepted or has the processing capabilities of the processor
+    #[schema(example = json!(["MASTER","VISA","DINERS"]))]
     pub payment_schemes: Option<Vec<String>>,
+    /// List of currencies accepted or has the processing capabilities of the processor
+    #[schema(value_type = Option<Vec<Currency>>,example = json!(["USD","EUR","AED"]))]
     pub accepted_currencies: Option<Vec<api_enums::Currency>>,
+    ///  List of Countries accepted or has the processing capabilities of the processor
+    #[schema(example = json!(["US","IN"]))]
     pub accepted_countries: Option<Vec<String>>,
+    /// Minimum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents)
+    #[schema(example = 1)]
     pub minimum_amount: Option<i32>,
+    /// Maximum amount supported by the processor. To be represented in the lowest denomination of
+    /// the target currency (For example, for USD it should be in cents)
+    #[schema(example = 1313)]
     pub maximum_amount: Option<i32>,
+    /// Boolean to enable recurring payments / mandates. Default is true.
+    #[schema(default = true, example = false)]
     pub recurring_enabled: bool,
+    /// Boolean to enable installment / EMI / BNPL payments. Default is true.
+    #[schema(default = true, example = false)]
     pub installment_payment_enabled: bool,
+    /// Type of payment experience enabled with the connector
+    #[schema(value_type = Option<Vec<PaymentExperience>>,example = json!(["redirect_to_url"]))]
     pub payment_experience: Option<Vec<payment_methods::PaymentExperience>>,
 }
 

crates/api_models/src/payment_methods.rs

@@ -2,6 +2,7 @@ use std::collections;
 
 use common_utils::pii;
 use serde::de;
+use utoipa::ToSchema;
 
 use crate::enums as api_enums;
 
@@ -238,15 +239,22 @@ pub struct CustomerPaymentMethod {
     pub created: Option<time::PrimitiveDateTime>,
 }
 
-#[derive(Eq, PartialEq, Hash, Clone, Debug, serde::Serialize, serde::Deserialize)]
+#[derive(Eq, PartialEq, Hash, Clone, Debug, serde::Serialize, serde::Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 #[non_exhaustive]
 pub enum PaymentExperience {
+    /// The URL to which the customer needs to be redirected for completing the payment.The URL to
+    /// which the customer needs to be redirected for completing the payment.
     RedirectToUrl,
+    /// Contains the data for invoking the sdk client for completing the payment.
     InvokeSdkClient,
+    /// The QR code data to be displayed to the customer.
     DisplayQrCode,
+    /// Contains data to finish one click payment.
     OneClick,
+    /// Redirect customer to link wallet
     LinkWallet,
+    /// Contains the data for invoking the sdk client for completing the payment.
     InvokePaymentApp,
 }
 

crates/router/src/openapi.rs

@@ -56,6 +56,7 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::enums::RoutingAlgorithm,
         api_models::enums::PaymentMethodType,
         api_models::enums::PaymentMethodSubType,
+        api_models::enums::ConnectorType,
         api_models::enums::Currency,
         api_models::enums::IntentStatus,
         api_models::enums::CaptureMethod,
@@ -64,6 +65,8 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::enums::WalletIssuer,
         api_models::enums::Connector,
         api_models::enums::PaymentMethodType,
+        api_models::admin::PaymentConnectorCreate,
+        api_models::admin::PaymentMethods,
         api_models::payments::AddressDetails,
         api_models::payments::Address,
         api_models::payments::OrderDetails,
@@ -85,6 +88,7 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::payments::CustomerAcceptance,
         api_models::payments::PaymentsRequest,
         api_models::payments::PaymentsResponse,
+        api_models::payment_methods::PaymentExperience,
         crate::types::api::admin::MerchantAccountResponse,
         crate::types::api::admin::MerchantConnectorId,
         crate::types::api::admin::MerchantDetails,

crates/router/src/routes/admin.rs

@@ -98,9 +98,19 @@ pub async fn delete_merchant_account(
     .await
 }
 
-//payment connector api
+/// PaymentsConnectors - Create
+///
+/// Create a new Payment Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc."
+#[utoipa::path(
+    post,
+    path = "/account/{account_id}/connectors",
+    request_body = PaymentConnectorCreate,
+    responses(
+        (status = 200, description = "Payment Connector Created", body = PaymentConnectorCreate),
+        (status = 400, description = "Missing Mandatory fields")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentConnectorsCreate))]
-// #[post("/{merchant_id}/connectors")]
 pub async fn payment_connector_create(
     state: web::Data<AppState>,
     req: HttpRequest,

openapi/generated.json

@@ -280,11 +280,25 @@
           "globalpay",
           "klarna",
           "payu",
+          "rapyd",
           "shift4",
           "stripe",
+          "worldline",
           "worldpay"
         ]
       },
+      "ConnectorType": {
+        "type": "string",
+        "enum": [
+          "payment_processor",
+          "payment_vas",
+          "fin_operations",
+          "fiz_operations",
+          "networks",
+          "banking_entities",
+          "non_banking_finance"
+        ]
+      },
       "CreateMerchantAccount": {
         "type": "object",
         "required": [
@@ -320,13 +334,7 @@
             "$ref": "#/components/schemas/WebhookDetails"
           },
           "routing_algorithm": {
-            "$ref": "#/components/schemas/RoutingAlgorithm"
+            "type": "object"
-          },
-          "custom_routing_rules": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/CustomRoutingRules"
-            }
           },
           "sub_merchants_enabled": {
             "type": "boolean",
@@ -479,174 +487,6 @@
           "ZAR"
         ]
       },
-      "CustomRoutingRules": {
-        "type": "object",
-        "properties": {
-          "payment_methods_incl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PaymentMethodType"
-            },
-            "example": [
-              "card",
-              "upi"
-            ]
-          },
-          "payment_methods_excl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PaymentMethodType"
-            },
-            "example": [
-              "card",
-              "upi"
-            ]
-          },
-          "payment_method_types_incl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PaymentMethodSubType"
-            },
-            "example": [
-              "credit_card",
-              "debit_card"
-            ]
-          },
-          "payment_method_types_excl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/PaymentMethodSubType"
-            },
-            "example": [
-              "credit_card",
-              "debit_card"
-            ]
-          },
-          "payment_method_issuers_incl": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "The List of payment method issuers to include for this routing rule"
-            },
-            "example": [
-              "Citibank",
-              "JPMorgan"
-            ]
-          },
-          "payment_method_issuers_excl": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "The List of payment method issuers to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list."
-            },
-            "example": [
-              "Citibank",
-              "JPMorgan"
-            ]
-          },
-          "countries_incl": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "The List of countries to include for this routing rule"
-            },
-            "example": [
-              "US",
-              "UK"
-            ]
-          },
-          "countries_excl": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "The List of countries to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list."
-            },
-            "example": [
-              "US",
-              "UK"
-            ]
-          },
-          "currencies_incl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Currency"
-            },
-            "example": [
-              "EUR",
-              "USD"
-            ]
-          },
-          "currencies_excl": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Currency"
-            },
-            "example": [
-              "EUR",
-              "USD"
-            ]
-          },
-          "metadata_filters_keys": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "List of Metadata Filter keys to apply for the Routing Rule. The filters are presented as 2 arrays of keys and value. This property contains all the keys."
-            },
-            "example": [
-              "platform",
-              "Category"
-            ]
-          },
-          "metadata_filters_values": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "List of Metadata Filters to apply for the Routing Rule. The filters are presented as 2 arrays of keys and value. This property contains all the values."
-            },
-            "example": [
-              "android",
-              "Category_Electronics"
-            ]
-          },
-          "connectors_pecking_order": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "The pecking order of payment connectors (or processors) to be used for routing. The first connector in the array will be attempted for routing. If it fails, the second connector will be used till the list is exhausted."
-            },
-            "example": [
-              "stripe",
-              "adyen",
-              "brain_tree"
-            ]
-          },
-          "connectors_traffic_weightage_key": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "description": "An Array of Connectors (as Keys) with the associated percentage of traffic to be routed through the given connector (Expressed as an array of values)"
-            },
-            "example": [
-              "stripe",
-              "adyen",
-              "brain_tree"
-            ]
-          },
-          "connectors_traffic_weightage_value": {
-            "type": "array",
-            "items": {
-              "type": "integer",
-              "format": "int32",
-              "description": "An Array of Weightage (expressed in percentage) that needs to be associated with the respective connectors (Expressed as an array of keys)"
-            },
-            "example": [
-              50,
-              30,
-              20
-            ]
-          }
-        }
-      },
       "CustomerAcceptance": {
         "type": "object",
         "required": [
@@ -793,13 +633,7 @@
             "$ref": "#/components/schemas/WebhookDetails"
           },
           "routing_algorithm": {
-            "$ref": "#/components/schemas/RoutingAlgorithm"
+            "type": "object"
-          },
-          "custom_routing_rules": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/CustomRoutingRules"
-            }
           },
           "sub_merchants_enabled": {
             "type": "boolean",
@@ -1074,6 +908,94 @@
           }
         ]
       },
+      "PaymentConnectorCreate": {
+        "type": "object",
+        "description": "Create a new Payment Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc.\"",
+        "required": [
+          "connector_type",
+          "connector_name"
+        ],
+        "properties": {
+          "connector_type": {
+            "$ref": "#/components/schemas/ConnectorType"
+          },
+          "connector_name": {
+            "type": "string",
+            "description": "Name of the Connector",
+            "example": "stripe"
+          },
+          "merchant_connector_id": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Unique ID of the connector",
+            "example": 42
+          },
+          "connector_account_details": {
+            "type": "object"
+          },
+          "test_mode": {
+            "type": "boolean",
+            "description": "A boolean value to indicate if the connector is in Test mode. By default, its value is false.",
+            "default": false,
+            "example": false
+          },
+          "disabled": {
+            "type": "boolean",
+            "description": "A boolean value to indicate if the connector is disabled. By default, its value is false.",
+            "default": false,
+            "example": false
+          },
+          "payment_methods_enabled": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentMethods"
+            },
+            "example": [
+              {
+                "payment_method": "wallet",
+                "payment_method_types": [
+                  "upi_collect",
+                  "upi_intent"
+                ],
+                "payment_method_issuers": [
+                  "labore magna ipsum",
+                  "aute"
+                ],
+                "payment_schemes": [
+                  "Discover",
+                  "Discover"
+                ],
+                "accepted_currencies": [
+                  "AED",
+                  "AED"
+                ],
+                "accepted_countries": [
+                  "in",
+                  "us"
+                ],
+                "minimum_amount": 1,
+                "maximum_amount": 68607706,
+                "recurring_enabled": true,
+                "installment_payment_enabled": true
+              }
+            ]
+          },
+          "metadata": {
+            "type": "object"
+          }
+        }
+      },
+      "PaymentExperience": {
+        "type": "string",
+        "enum": [
+          "redirect_to_url",
+          "invoke_sdk_client",
+          "display_qr_code",
+          "one_click",
+          "link_wallet",
+          "invoke_payment_app"
+        ]
+      },
       "PaymentMethod": {
         "oneOf": [
           {
@@ -1151,6 +1073,106 @@
           "paypal"
         ]
       },
+      "PaymentMethods": {
+        "type": "object",
+        "description": "Details of all the payment methods enabled for the connector for the given merchant account",
+        "required": [
+          "payment_method",
+          "recurring_enabled",
+          "installment_payment_enabled"
+        ],
+        "properties": {
+          "payment_method": {
+            "$ref": "#/components/schemas/PaymentMethodType"
+          },
+          "payment_method_types": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentMethodSubType"
+            },
+            "example": [
+              "credit"
+            ]
+          },
+          "payment_method_issuers": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "List of payment method issuers to be enabled for this payment method"
+            },
+            "example": [
+              "HDFC"
+            ]
+          },
+          "payment_schemes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "List of payment schemes accepted or has the processing capabilities of the processor"
+            },
+            "example": [
+              "MASTER",
+              "VISA",
+              "DINERS"
+            ]
+          },
+          "accepted_currencies": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Currency"
+            },
+            "example": [
+              "USD",
+              "EUR",
+              "AED"
+            ]
+          },
+          "accepted_countries": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "List of Countries accepted or has the processing capabilities of the processor"
+            },
+            "example": [
+              "US",
+              "IN"
+            ]
+          },
+          "minimum_amount": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Minimum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents)",
+            "example": 1
+          },
+          "maximum_amount": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Maximum amount supported by the processor. To be represented in the lowest denomination of\nthe target currency (For example, for USD it should be in cents)",
+            "example": 1313
+          },
+          "recurring_enabled": {
+            "type": "boolean",
+            "description": "Boolean to enable recurring payments / mandates. Default is true.",
+            "default": true,
+            "example": false
+          },
+          "installment_payment_enabled": {
+            "type": "boolean",
+            "description": "Boolean to enable installment / EMI / BNPL payments. Default is true.",
+            "default": true,
+            "example": false
+          },
+          "payment_experience": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentExperience"
+            },
+            "example": [
+              "redirect_to_url"
+            ]
+          }
+        }
+      },
       "PaymentsRequest": {
         "type": "object",
         "properties": {
@@ -1585,6 +1607,14 @@
           },
           "error_message": {
             "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
           }
         }
       },