feat(payouts): add domain type for PayoutId (#8395)

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

Author: kashif-m

api-reference/v1/openapi_spec_v1.json

@@ -24303,6 +24303,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",
@@ -24609,6 +24616,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",
@@ -24902,13 +24916,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": {
@@ -24955,6 +24969,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",
@@ -25249,6 +25270,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",
@@ -25479,6 +25507,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

@@ -19579,7 +19579,19 @@
         "additionalProperties": false
       },
       "PayoutActionRequest": {
-        "type": "object"
+        "type": "object",
+        "required": [
+          "payout_id"
+        ],
+        "properties": {
+          "payout_id": {
+            "type": "string",
+            "description": "Unique identifier for the payout. This ensures idempotency for multiple payouts\nthat have been done by a single merchant. This field is auto generated and is returned in the API response.",
+            "example": "187282ab-40ef-47a9-9206-5099ba31e432",
+            "maxLength": 30,
+            "minLength": 30
+          }
+        }
       },
       "PayoutAttemptResponse": {
         "type": "object",
@@ -19746,6 +19758,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",
@@ -20001,6 +20020,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",
@@ -20279,13 +20305,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": {
@@ -20332,6 +20358,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

@@ -16,7 +16,7 @@ use utoipa::ToSchema;
 
 use crate::{enums as api_enums, payment_methods::RequiredFieldInfo, payments};
 
-#[derive(Debug, Deserialize, Serialize, Clone, ToSchema)]
+#[derive(Debug, Serialize, Clone, ToSchema)]
 pub enum PayoutRequest {
     PayoutActionRequest(PayoutActionRequest),
     PayoutCreateRequest(Box<PayoutCreateRequest>),
@@ -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,
@@ -638,7 +646,7 @@ pub struct PayoutRetrieveBody {
     pub merchant_id: Option<id_type::MerchantId>,
 }
 
-#[derive(Default, Debug, Serialize, ToSchema, Clone, Deserialize)]
+#[derive(Debug, Serialize, ToSchema, Clone, Deserialize)]
 pub struct PayoutRetrieveRequest {
     /// Unique identifier for the payout. This ensures idempotency for multiple payouts
     /// that have been done by a single merchant. This field is auto generated and is returned in the API response.
@@ -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)
@@ -660,9 +668,7 @@ pub struct PayoutRetrieveRequest {
     pub merchant_id: Option<id_type::MerchantId>,
 }
 
-#[derive(
-    Default, Debug, Deserialize, Serialize, Clone, ToSchema, router_derive::PolymorphicSchema,
-)]
+#[derive(Debug, Serialize, Clone, ToSchema, router_derive::PolymorphicSchema)]
 #[generate_schemas(PayoutCancelRequest, PayoutFulfillRequest)]
 pub struct PayoutActionRequest {
     /// Unique identifier for the payout. This ensures idempotency for multiple payouts
@@ -673,8 +679,7 @@ pub struct PayoutActionRequest {
         max_length = 30,
         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 +727,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 +760,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 +834,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 +879,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

@@ -11,6 +11,7 @@ mod merchant;
 mod merchant_connector_account;
 mod organization;
 mod payment;
+mod payout;
 mod profile;
 mod profile_acquirer;
 mod refunds;
@@ -27,6 +28,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,10 @@
+crate::id_type!(
+    PayoutId,
+    "A domain type for payout_id that can be used for payout ids"
+);
+crate::impl_id_type_methods!(PayoutId, "payout_id");
+crate::impl_debug_id_type!(PayoutId);
+crate::impl_try_from_cow_str_id_type!(PayoutId, "payout_id");
+crate::impl_generate_id_id_type!(PayoutId, "payout");
+crate::impl_queryable_id_type!(PayoutId);
+crate::impl_to_sql_from_sql_id_type!(PayoutId);