feat(payouts): implement list and filter APIs (#3651)

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

Author: kashif-m

crates/api_models/src/events/payouts.rs

@@ -1,7 +1,8 @@
 use common_utils::events::{ApiEventMetric, ApiEventsType};
 
 use crate::payouts::{
-    PayoutActionRequest, PayoutCreateRequest, PayoutCreateResponse, PayoutRetrieveRequest,
+    PayoutActionRequest, PayoutCreateRequest, PayoutCreateResponse, PayoutListConstraints,
+    PayoutListFilterConstraints, PayoutListFilters, PayoutListResponse, PayoutRetrieveRequest,
 };
 
 impl ApiEventMetric for PayoutRetrieveRequest {
@@ -27,3 +28,27 @@ impl ApiEventMetric for PayoutActionRequest {
         Some(ApiEventsType::Payout)
     }
 }
+
+impl ApiEventMetric for PayoutListConstraints {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        Some(ApiEventsType::Payout)
+    }
+}
+
+impl ApiEventMetric for PayoutListFilterConstraints {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        Some(ApiEventsType::Payout)
+    }
+}
+
+impl ApiEventMetric for PayoutListResponse {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        Some(ApiEventsType::Payout)
+    }
+}
+
+impl ApiEventMetric for PayoutListFilters {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        Some(ApiEventsType::Payout)
+    }
+}

crates/api_models/src/payments.rs

@@ -2,6 +2,7 @@ use std::{collections::HashMap, fmt, num::NonZeroI64};
 
 use cards::CardNumber;
 use common_utils::{
+    consts::default_payments_list_limit,
     crypto,
     ext_traits::Encode,
     pii::{self, Email},
@@ -3197,7 +3198,7 @@ pub struct PaymentListConstraints {
 
     /// limit on the number of objects to return
     #[schema(default = 10, maximum = 100)]
-    #[serde(default = "default_limit")]
+    #[serde(default = "default_payments_list_limit")]
     pub limit: u32,
 
     /// The time at which payment is created
@@ -3283,7 +3284,7 @@ pub struct PaymentListFilterConstraints {
     /// The identifier for customer
     pub customer_id: Option<String>,
     /// The limit on the number of objects. The default limit is 10 and max limit is 20
-    #[serde(default = "default_limit")]
+    #[serde(default = "default_payments_list_limit")]
     pub limit: u32,
     /// The starting point within a list of objects
     pub offset: Option<u32>,
@@ -3353,10 +3354,6 @@ pub struct VerifyResponse {
     pub error_message: Option<String>,
 }
 
-fn default_limit() -> u32 {
-    10
-}
-
 #[derive(Default, Debug, serde::Deserialize, serde::Serialize)]
 pub struct PaymentsRedirectionResponse {
     pub redirect_url: String,

crates/api_models/src/payouts.rs

@@ -1,10 +1,12 @@
 use cards::CardNumber;
 use common_utils::{
+    consts::default_payouts_list_limit,
     crypto,
     pii::{self, Email},
 };
 use masking::Secret;
 use serde::{Deserialize, Serialize};
+use time::PrimitiveDateTime;
 use utoipa::ToSchema;
 
 use crate::{enums as api_enums, payments};
@@ -393,6 +395,54 @@ pub struct PayoutCreateResponse {
 
     /// The business profile that is associated with this payment
     pub profile_id: String,
+
+    /// Time when the payout was created
+    #[schema(example = "2022-09-10T10:11:12Z")]
+    #[serde(with = "common_utils::custom_serde::iso8601::option")]
+    pub created: Option<PrimitiveDateTime>,
+
+    /// List of attempts
+    #[schema(value_type = Option<Vec<PayoutAttemptResponse>>)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub attempts: Option<Vec<PayoutAttemptResponse>>,
+}
+
+#[derive(
+    Default, Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema,
+)]
+pub struct PayoutAttemptResponse {
+    /// Unique identifier for the attempt
+    pub attempt_id: String,
+    /// The status of the attempt
+    #[schema(value_type = PayoutStatus, example = "failed")]
+    pub status: api_enums::PayoutStatus,
+    /// The payout attempt amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,
+    pub amount: i64,
+    /// The currency of the amount of the payout attempt
+    #[schema(value_type = Option<Currency>, example = "USD")]
+    pub currency: Option<api_enums::Currency>,
+    /// The connector used for the payout
+    pub connector: Option<String>,
+    /// Connector's error code in case of failures
+    pub error_code: Option<String>,
+    /// Connector's error message in case of failures
+    pub error_message: Option<String>,
+    /// The payout method that was used
+    #[schema(value_type = Option<PayoutType>, example = "bank")]
+    pub payment_method: Option<api_enums::PayoutType>,
+    /// Payment Method Type
+    #[schema(value_type = Option<PaymentMethodType>, example = "bacs")]
+    pub payout_method_type: Option<api_enums::PaymentMethodType>,
+    /// A unique identifier for a payout provided by the connector
+    pub connector_transaction_id: Option<String>,
+    /// If the payout was cancelled the reason provided here
+    pub cancellation_reason: Option<String>,
+    /// Provide a reference to a stored payout method
+    pub payout_token: Option<String>,
+    /// error code unified across the connectors is received here if there was an error while calling connector
+    pub unified_code: Option<String>,
+    /// error message unified across the connectors is received here if there was an error while calling connector
+    pub unified_message: Option<String>,
 }
 
 #[derive(Default, Debug, Clone, Deserialize, ToSchema)]
@@ -430,3 +480,96 @@ pub struct PayoutActionRequest {
     )]
     pub payout_id: String,
 }
+
+#[derive(Clone, Debug, serde::Deserialize, ToSchema, serde::Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct PayoutListConstraints {
+    /// The identifier for customer
+    #[schema(example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
+    pub customer_id: Option<String>,
+
+    /// A cursor for use in pagination, fetch the next list after some object
+    #[schema(example = "pay_fafa124123")]
+    pub starting_after: Option<String>,
+
+    /// A cursor for use in pagination, fetch the previous list before some object
+    #[schema(example = "pay_fafa124123")]
+    pub ending_before: Option<String>,
+
+    /// limit on the number of objects to return
+    #[schema(default = 10, maximum = 100)]
+    #[serde(default = "default_payouts_list_limit")]
+    pub limit: u32,
+
+    /// The time at which payout is created
+    #[schema(example = "2022-09-10T10:11:12Z")]
+    #[serde(default, with = "common_utils::custom_serde::iso8601::option")]
+    pub created: Option<PrimitiveDateTime>,
+
+    /// The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).
+    #[serde(flatten)]
+    #[schema(value_type = Option<TimeRange>)]
+    pub time_range: Option<payments::TimeRange>,
+}
+
+#[derive(Clone, Debug, serde::Deserialize, ToSchema, serde::Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct PayoutListFilterConstraints {
+    /// The identifier for payout
+    #[schema(
+    value_type = Option<String>,
+    min_length = 30,
+    max_length = 30,
+    example = "payout_mbabizu24mvu3mela5njyhpit4"
+)]
+    pub payout_id: Option<String>,
+    /// The identifier for business profile
+    pub profile_id: Option<String>,
+    /// The identifier for customer
+    #[schema(example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
+    pub customer_id: Option<String>,
+    /// The limit on the number of objects. The default limit is 10 and max limit is 20
+    #[serde(default = "default_payouts_list_limit")]
+    pub limit: u32,
+    /// The starting point within a list of objects
+    pub offset: Option<u32>,
+    /// The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).
+    #[serde(flatten)]
+    #[schema(value_type = Option<TimeRange>)]
+    pub time_range: Option<payments::TimeRange>,
+    /// The list of connectors to filter payouts list
+    #[schema(value_type = Option<Vec<PayoutConnectors>>, max_length = 255, example = json!(["wise", "adyen"]))]
+    pub connector: Option<Vec<api_enums::PayoutConnectors>>,
+    /// The list of currencies to filter payouts list
+    #[schema(value_type = Currency, example = "USD")]
+    pub currency: Option<Vec<api_enums::Currency>>,
+    /// The list of payout status to filter payouts list
+    #[schema(value_type = Option<Vec<PayoutStatus>>, example = json!(["pending", "failed"]))]
+    pub status: Option<Vec<api_enums::PayoutStatus>>,
+    /// The list of payout methods to filter payouts list
+    #[schema(value_type = Option<Vec<PayoutType>>, example = json!(["bank", "card"]))]
+    pub payout_method: Option<Vec<common_enums::PayoutType>>,
+    /// Type of recipient
+    #[schema(value_type = PayoutEntityType, example = "Individual")]
+    pub entity_type: Option<common_enums::PayoutEntityType>,
+}
+
+#[derive(Clone, Debug, serde::Serialize, ToSchema)]
+pub struct PayoutListResponse {
+    /// The number of payouts included in the list
+    pub size: usize,
+    // The list of payouts response objects
+    pub data: Vec<PayoutCreateResponse>,
+}
+
+#[derive(Clone, Debug, serde::Serialize)]
+pub struct PayoutListFilters {
+    /// The list of available connector filters
+    pub connector: Vec<api_enums::PayoutConnectors>,
+    /// The list of available currency filters
+    pub currency: Vec<common_enums::Currency>,
+    /// The list of available payment status filters
+    pub status: Vec<common_enums::PayoutStatus>,
+    /// The list of available payment method filters
+    pub payout_method: Vec<common_enums::PayoutType>,
+}

crates/common_enums/src/enums.rs

@@ -2028,6 +2028,7 @@ pub enum CanadaStatesAbbreviation {
     Debug,
     Default,
     Eq,
+    Hash,
     PartialEq,
     ToSchema,
     serde::Deserialize,

crates/common_utils/src/consts.rs

@@ -23,10 +23,23 @@ pub static FRM_CONFIGS_EG: &str = r#"
 pub const PAYMENTS_LIST_MAX_LIMIT_V1: u32 = 100;
 /// Maximum limit for payments list post api with filters
 pub const PAYMENTS_LIST_MAX_LIMIT_V2: u32 = 20;
+/// Default limit for payments list API
+pub fn default_payments_list_limit() -> u32 {
+    10
+}
 
 /// Maximum limit for payment link list get api
 pub const PAYMENTS_LINK_LIST_LIMIT: u32 = 100;
 
+/// Maximum limit for payouts list get api
+pub const PAYOUTS_LIST_MAX_LIMIT_GET: u32 = 100;
+/// Maximum limit for payouts list post api
+pub const PAYOUTS_LIST_MAX_LIMIT_POST: u32 = 20;
+/// Default limit for payouts list API
+pub fn default_payouts_list_limit() -> u32 {
+    10
+}
+
 /// surcharge percentage maximum precision length
 pub const SURCHARGE_PERCENTAGE_PRECISION_LENGTH: u8 = 2;
 

crates/data_models/src/payouts.rs

@@ -1,3 +1,100 @@
 pub mod payout_attempt;
 #[allow(clippy::module_inception)]
 pub mod payouts;
+
+use common_enums as storage_enums;
+use common_utils::consts;
+use time::PrimitiveDateTime;
+
+pub enum PayoutFetchConstraints {
+    Single { payout_id: String },
+    List(Box<PayoutListParams>),
+}
+
+pub struct PayoutListParams {
+    pub offset: u32,
+    pub starting_at: Option<PrimitiveDateTime>,
+    pub ending_at: Option<PrimitiveDateTime>,
+    pub connector: Option<Vec<api_models::enums::PayoutConnectors>>,
+    pub currency: Option<Vec<storage_enums::Currency>>,
+    pub status: Option<Vec<storage_enums::PayoutStatus>>,
+    pub payout_method: Option<Vec<common_enums::PayoutType>>,
+    pub profile_id: Option<String>,
+    pub customer_id: Option<String>,
+    pub starting_after_id: Option<String>,
+    pub ending_before_id: Option<String>,
+    pub entity_type: Option<common_enums::PayoutEntityType>,
+    pub limit: Option<u32>,
+}
+
+impl From<api_models::payouts::PayoutListConstraints> for PayoutFetchConstraints {
+    fn from(value: api_models::payouts::PayoutListConstraints) -> Self {
+        Self::List(Box::new(PayoutListParams {
+            offset: 0,
+            starting_at: value
+                .time_range
+                .map_or(value.created, |t| Some(t.start_time)),
+            ending_at: value.time_range.and_then(|t| t.end_time),
+            connector: None,
+            currency: None,
+            status: None,
+            payout_method: None,
+            profile_id: None,
+            customer_id: value.customer_id,
+            starting_after_id: value.starting_after,
+            ending_before_id: value.ending_before,
+            entity_type: None,
+            limit: Some(std::cmp::min(
+                value.limit,
+                consts::PAYOUTS_LIST_MAX_LIMIT_GET,
+            )),
+        }))
+    }
+}
+
+impl From<api_models::payments::TimeRange> for PayoutFetchConstraints {
+    fn from(value: api_models::payments::TimeRange) -> Self {
+        Self::List(Box::new(PayoutListParams {
+            offset: 0,
+            starting_at: Some(value.start_time),
+            ending_at: value.end_time,
+            connector: None,
+            currency: None,
+            status: None,
+            payout_method: None,
+            profile_id: None,
+            customer_id: None,
+            starting_after_id: None,
+            ending_before_id: None,
+            entity_type: None,
+            limit: None,
+        }))
+    }
+}
+
+impl From<api_models::payouts::PayoutListFilterConstraints> for PayoutFetchConstraints {
+    fn from(value: api_models::payouts::PayoutListFilterConstraints) -> Self {
+        if let Some(payout_id) = value.payout_id {
+            Self::Single { payout_id }
+        } else {
+            Self::List(Box::new(PayoutListParams {
+                offset: value.offset.unwrap_or_default(),
+                starting_at: value.time_range.map(|t| t.start_time),
+                ending_at: value.time_range.and_then(|t| t.end_time),
+                connector: value.connector,
+                currency: value.currency,
+                status: value.status,
+                payout_method: value.payout_method,
+                profile_id: value.profile_id,
+                customer_id: value.customer_id,
+                starting_after_id: None,
+                ending_before_id: None,
+                entity_type: value.entity_type,
+                limit: Some(std::cmp::min(
+                    value.limit,
+                    consts::PAYOUTS_LIST_MAX_LIMIT_POST,
+                )),
+            }))
+        }
+    }
+}