feat(payouts): add domain type for PayoutId

api-reference/v1/openapi_spec_v1.json

@@ -24074,6 +24074,13 @@
           "client_secret"
         ],
         "properties": {
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",
@@ -24380,6 +24387,13 @@
             "example": "merchant_1668273825",
             "maxLength": 255
           },
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",
@@ -24673,13 +24687,13 @@
               "starting_after": {
                 "type": "string",
                 "description": "A cursor for use in pagination, fetch the next list after some object",
-                "example": "pay_fafa124123",
+                "example": "payout_fafa124123",
                 "nullable": true
               },
               "ending_before": {
                 "type": "string",
                 "description": "A cursor for use in pagination, fetch the previous list before some object",
-                "example": "pay_fafa124123",
+                "example": "payout_fafa124123",
                 "nullable": true
               },
               "limit": {
@@ -24726,6 +24740,13 @@
                 "maxLength": 30,
                 "minLength": 30
               },
+              "merchant_order_reference_id": {
+                "type": "string",
+                "description": "The merchant order reference ID for payout",
+                "example": "merchant_order_ref_123",
+                "nullable": true,
+                "maxLength": 255
+              },
               "profile_id": {
                 "type": "string",
                 "description": "The identifier for business profile",
@@ -25020,6 +25041,13 @@
       "PayoutUpdateRequest": {
         "type": "object",
         "properties": {
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",
@@ -25250,6 +25278,13 @@
           "currency"
         ],
         "properties": {
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",

api-reference/v2/openapi_spec_v2.json

@@ -19729,6 +19729,13 @@
             "nullable": true,
             "maxLength": 255
           },
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",
@@ -19984,6 +19991,13 @@
             "example": "merchant_1668273825",
             "maxLength": 255
           },
+          "merchant_order_reference_id": {
+            "type": "string",
+            "description": "Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.",
+            "example": "merchant_order_ref_123",
+            "nullable": true,
+            "maxLength": 255
+          },
           "amount": {
             "type": "integer",
             "format": "int64",
@@ -20262,13 +20276,13 @@
               "starting_after": {
                 "type": "string",
                 "description": "A cursor for use in pagination, fetch the next list after some object",
-                "example": "pay_fafa124123",
+                "example": "payout_fafa124123",
                 "nullable": true
               },
               "ending_before": {
                 "type": "string",
                 "description": "A cursor for use in pagination, fetch the previous list before some object",
-                "example": "pay_fafa124123",
+                "example": "payout_fafa124123",
                 "nullable": true
               },
               "limit": {
@@ -20315,6 +20329,13 @@
                 "maxLength": 30,
                 "minLength": 30
               },
+              "merchant_order_reference_id": {
+                "type": "string",
+                "description": "The merchant order reference ID for payout",
+                "example": "merchant_order_ref_123",
+                "nullable": true,
+                "maxLength": 255
+              },
               "profile_id": {
                 "type": "string",
                 "description": "The identifier for business profile",

crates/api_models/src/events/payouts.rs

@@ -9,31 +9,31 @@ use crate::payouts::{
 impl ApiEventMetric for PayoutRetrieveRequest {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {
         Some(ApiEventsType::Payout {
-            payout_id: self.payout_id.clone(),
+            payout_id: self.payout_id.to_owned(),
         })
     }
 }
 
 impl ApiEventMetric for PayoutCreateRequest {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {
         self.payout_id.as_ref().map(|id| ApiEventsType::Payout {
-            payout_id: id.clone(),
+            payout_id: id.to_owned(),
         })
     }
 }
 
 impl ApiEventMetric for PayoutCreateResponse {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {
         Some(ApiEventsType::Payout {
-            payout_id: self.payout_id.clone(),
+            payout_id: self.payout_id.to_owned(),
         })
     }
 }
 
 impl ApiEventMetric for PayoutActionRequest {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {
         Some(ApiEventsType::Payout {
-            payout_id: self.payout_id.clone(),
+            payout_id: self.payout_id.to_owned(),
         })
     }
 }
@@ -65,7 +65,7 @@ impl ApiEventMetric for PayoutListFilters {
 impl ApiEventMetric for PayoutLinkInitiateRequest {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {
         Some(ApiEventsType::Payout {
-            payout_id: self.payout_id.clone(),
+            payout_id: self.payout_id.to_owned(),
         })
     }
 }

crates/api_models/src/payouts.rs

@@ -37,13 +37,17 @@ pub struct PayoutCreateRequest {
         example = "187282ab-40ef-47a9-9206-5099ba31e432"
     )]
     #[remove_in(PayoutsCreateRequest, PayoutUpdateRequest, PayoutConfirmRequest)]
-    pub payout_id: Option<String>, // TODO: #1321 https://github.com/juspay/hyperswitch/issues/1321
+    pub payout_id: Option<id_type::PayoutId>,
 
     /// This is an identifier for the merchant account. This is inferred from the API key provided during the request, **not required to be included in the Payout Create/Update Request.**
     #[schema(max_length = 255, value_type = Option<String>, example = "merchant_1668273825")]
     #[remove_in(PayoutsCreateRequest, PayoutUpdateRequest, PayoutConfirmRequest)]
     pub merchant_id: Option<id_type::MerchantId>,
 
+    /// Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.
+    #[schema(value_type = Option<String>, max_length = 255, example = "merchant_order_ref_123")]
+    pub merchant_order_reference_id: Option<String>,
+
     /// The payout amount. Amount for the payout 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 = 1000)]
     #[mandatory_in(PayoutsCreateRequest = u64)]
@@ -399,13 +403,17 @@ pub struct PayoutCreateResponse {
         max_length = 30,
         example = "187282ab-40ef-47a9-9206-5099ba31e432"
     )]
-    pub payout_id: String, // TODO: Update this to PayoutIdType similar to PaymentIdType
+    pub payout_id: id_type::PayoutId,
 
     /// This is an identifier for the merchant account. This is inferred from the API key
     /// provided during the request
     #[schema(max_length = 255, value_type = String, example = "merchant_1668273825")]
     pub merchant_id: id_type::MerchantId,
 
+    /// Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.
+    #[schema(value_type = Option<String>, max_length = 255, example = "merchant_order_ref_123")]
+    pub merchant_order_reference_id: Option<String>,
+
     /// The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,
     #[schema(value_type = i64, example = 1000)]
     pub amount: common_utils::types::MinorUnit,
@@ -648,7 +656,7 @@ pub struct PayoutRetrieveRequest {
         max_length = 30,
         example = "187282ab-40ef-47a9-9206-5099ba31e432"
     )]
-    pub payout_id: String,
+    pub payout_id: id_type::PayoutId,
 
     /// `force_sync` with the connector to get payout details
     /// (defaults to false)
@@ -674,7 +682,7 @@ pub struct PayoutActionRequest {
         example = "187282ab-40ef-47a9-9206-5099ba31e432"
     )]
     #[serde(skip_deserializing)]
-    pub payout_id: String,
+    pub payout_id: id_type::PayoutId,
 }
 
 #[derive(Default, Debug, ToSchema, Clone, Deserialize)]
@@ -722,12 +730,12 @@ pub struct PayoutListConstraints {
     pub customer_id: Option<id_type::CustomerId>,
 
     /// A cursor for use in pagination, fetch the next list after some object
-    #[schema(example = "pay_fafa124123")]
-    pub starting_after: Option<String>,
+    #[schema(example = "payout_fafa124123", value_type = Option<String>,)]
+    pub starting_after: Option<id_type::PayoutId>,
 
     /// A cursor for use in pagination, fetch the previous list before some object
-    #[schema(example = "pay_fafa124123")]
-    pub ending_before: Option<String>,
+    #[schema(example = "payout_fafa124123", value_type = Option<String>,)]
+    pub ending_before: Option<id_type::PayoutId>,
 
     /// limit on the number of objects to return
     #[schema(default = 10, maximum = 100)]
@@ -755,7 +763,10 @@ pub struct PayoutListFilterConstraints {
     max_length = 30,
     example = "187282ab-40ef-47a9-9206-5099ba31e432"
 )]
-    pub payout_id: Option<String>,
+    pub payout_id: Option<id_type::PayoutId>,
+    /// The merchant order reference ID for payout
+    #[schema(value_type = Option<String>, max_length = 255, example = "merchant_order_ref_123")]
+    pub merchant_order_reference_id: Option<String>,
     /// The identifier for business profile
     #[schema(value_type = Option<String>)]
     pub profile_id: Option<id_type::ProfileId>,
@@ -826,15 +837,16 @@ pub struct PayoutLinkResponse {
 pub struct PayoutLinkInitiateRequest {
     #[schema(value_type = String)]
     pub merchant_id: id_type::MerchantId,
-    pub payout_id: String,
+    #[schema(value_type = String)]
+    pub payout_id: id_type::PayoutId,
 }
 
 #[derive(Clone, Debug, serde::Serialize)]
 pub struct PayoutLinkDetails {
     pub publishable_key: Secret<String>,
     pub client_secret: Secret<String>,
     pub payout_link_id: String,
-    pub payout_id: String,
+    pub payout_id: id_type::PayoutId,
     pub customer_id: id_type::CustomerId,
     #[serde(with = "common_utils::custom_serde::iso8601")]
     pub session_expiry: PrimitiveDateTime,
@@ -870,7 +882,7 @@ pub struct RequiredFieldsOverrideRequest {
 #[derive(Clone, Debug, serde::Serialize)]
 pub struct PayoutLinkStatusDetails {
     pub payout_link_id: String,
-    pub payout_id: String,
+    pub payout_id: id_type::PayoutId,
     pub customer_id: id_type::CustomerId,
     #[serde(with = "common_utils::custom_serde::iso8601")]
     pub session_expiry: PrimitiveDateTime,

crates/api_models/src/webhooks.rs

@@ -98,7 +98,7 @@ pub enum WebhookResponseTracker {
     },
     #[cfg(feature = "payouts")]
     Payout {
-        payout_id: String,
+        payout_id: common_utils::id_type::PayoutId,
         status: common_enums::PayoutStatus,
     },
     #[cfg(feature = "v1")]

crates/common_utils/src/events.rs

@@ -12,7 +12,7 @@ pub trait ApiEventMetric {
 #[serde(tag = "flow_type", rename_all = "snake_case")]
 pub enum ApiEventsType {
     Payout {
-        payout_id: String,
+        payout_id: id_type::PayoutId,
     },
     #[cfg(feature = "v1")]
     Payment {

crates/common_utils/src/id_type.rs

@@ -10,6 +10,7 @@ mod merchant;
 mod merchant_connector_account;
 mod organization;
 mod payment;
+mod payout;
 mod profile;
 mod profile_acquirer;
 mod refunds;
@@ -26,6 +27,7 @@ use diesel::{
     serialize::{Output, ToSql},
     sql_types,
 };
+pub use payout::PayoutId;
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
 

crates/common_utils/src/id_type/payout.rs

@@ -0,0 +1,20 @@
+crate::id_type!(
+    PayoutId,
+    "A type for payout_id that can be used for payout ids"
+);
+crate::impl_id_type_methods!(PayoutId, "payout_id");
+
+// This is to display the `PayoutId` as PayoutId(abcd)
+crate::impl_debug_id_type!(PayoutId);
+crate::impl_default_id_type!(PayoutId, "payout");
+crate::impl_try_from_cow_str_id_type!(PayoutId, "payout_id");
+
+// Database related implementations so that this field can be used directly in the database tables
+crate::impl_queryable_id_type!(PayoutId);
+crate::impl_to_sql_from_sql_id_type!(PayoutId);
+
+impl std::fmt::Display for PayoutId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.get_string_repr())
+    }
+}

crates/common_utils/src/link_utils.rs

@@ -149,7 +149,7 @@ pub struct PayoutLinkData {
     /// Identifier for the customer
     pub customer_id: id_type::CustomerId,
     /// Identifier for the payouts resource
-    pub payout_id: String,
+    pub payout_id: id_type::PayoutId,
     /// Link to render the payout link
     pub link: url::Url,
     /// Client secret generated for authenticating frontend APIs

crates/diesel_models/src/events.rs

@@ -74,7 +74,7 @@ pub enum EventMetadata {
         payment_id: common_utils::id_type::GlobalPaymentId,
     },
     Payout {
-        payout_id: String,
+        payout_id: common_utils::id_type::PayoutId,
     },
     #[cfg(feature = "v1")]
     Refund {

crates/diesel_models/src/generic_link.rs

@@ -156,7 +156,7 @@ pub struct PaymentMethodCollectLinkData {
 #[diesel(primary_key(link_id))]
 pub struct PayoutLink {
     pub link_id: String,
-    pub primary_reference: String,
+    pub primary_reference: common_utils::id_type::PayoutId,
     pub merchant_id: common_utils::id_type::MerchantId,
     #[serde(with = "common_utils::custom_serde::iso8601")]
     pub created_at: PrimitiveDateTime,