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 <mohammed.kashif@juspay.in>

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>,
+}