feat(connector): Add support for passive churn recovery webhooks (juspay#7109)

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

Author: 3 people

api-reference-v2/openapi_spec.json

@@ -13397,6 +13397,19 @@
           }
         }
       },
+      "PaymentAttemptFeatureMetadata": {
+        "type": "object",
+        "properties": {
+          "revenue_recovery": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentAttemptRevenueRecoveryData"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
       "PaymentAttemptResponse": {
         "type": "object",
         "required": [
@@ -13405,7 +13418,8 @@
           "amount",
           "authentication_type",
           "created_at",
-          "modified_at"
+          "modified_at",
+          "connector_payment_id"
         ],
         "properties": {
           "id": {
@@ -13501,9 +13515,7 @@
           },
           "connector_payment_id": {
             "type": "string",
-            "description": "A unique identifier for a payment provided by the connector",
-            "example": "993672945374576J",
-            "nullable": true
+            "description": "A unique identifier for a payment provided by the connector"
           },
           "payment_method_id": {
             "type": "string",
@@ -13520,6 +13532,27 @@
             "type": "string",
             "description": "Value passed in X-CLIENT-VERSION header during payments confirm request by the client",
             "nullable": true
+          },
+          "feature_metadata": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentAttemptFeatureMetadata"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
+      "PaymentAttemptRevenueRecoveryData": {
+        "type": "object",
+        "properties": {
+          "attempt_triggered_by": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/TriggeredBy"
+              }
+            ],
+            "nullable": true
           }
         }
       },
@@ -21526,6 +21559,13 @@
           "payout"
         ]
       },
+      "TriggeredBy": {
+        "type": "string",
+        "enum": [
+          "internal",
+          "external"
+        ]
+      },
       "UIWidgetFormLayout": {
         "type": "string",
         "enum": [

api-reference/openapi_spec.json

@@ -26144,6 +26144,13 @@
           "payout"
         ]
       },
+      "TriggeredBy": {
+        "type": "string",
+        "enum": [
+          "internal",
+          "external"
+        ]
+      },
       "UIWidgetFormLayout": {
         "type": "string",
         "enum": [

crates/api_models/Cargo.toml

@@ -22,6 +22,7 @@ customer_v2 = ["common_utils/customer_v2"]
 payment_methods_v2 = ["common_utils/payment_methods_v2"]
 dynamic_routing = []
 control_center_theme = ["dep:actix-web", "dep:actix-multipart"]
+revenue_recovery = []
 
 [dependencies]
 actix-multipart = { version = "0.6.1", optional = true }

crates/api_models/src/payments.rs

@@ -1511,8 +1511,8 @@ pub struct PaymentAttemptResponse {
     pub payment_method_subtype: Option<api_enums::PaymentMethodType>,
 
     /// A unique identifier for a payment provided by the connector
-    #[schema(value_type = Option<String>, example = "993672945374576J")]
-    pub connector_payment_id: Option<String>,
+    #[schema(value_type = String)]
+    pub connector_payment_id: Option<common_utils::types::ConnectorTransactionId>,
 
     /// Identifier for Payment Method used for the payment attempt
     #[schema(value_type = Option<String>, example = "12345_pm_01926c58bc6e77c09e809964e72af8c8")]
@@ -1522,6 +1522,24 @@ pub struct PaymentAttemptResponse {
     pub client_source: Option<String>,
     /// Value passed in X-CLIENT-VERSION header during payments confirm request by the client
     pub client_version: Option<String>,
+
+    /// Additional data that might be required by hyperswitch, to enable some specific features.
+    pub feature_metadata: Option<PaymentAttemptFeatureMetadata>,
+}
+
+#[cfg(feature = "v2")]
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
+pub struct PaymentAttemptFeatureMetadata {
+    /// Revenue recovery metadata that might be required by hyperswitch.
+    pub revenue_recovery: Option<PaymentAttemptRevenueRecoveryData>,
+}
+
+#[cfg(feature = "v2")]
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
+pub struct PaymentAttemptRevenueRecoveryData {
+    /// Flag to find out whether an attempt was created by external or internal system.
+    #[schema(value_type = Option<TriggeredBy>, example = "internal")]
+    pub attempt_triggered_by: common_enums::TriggeredBy,
 }
 
 #[derive(
@@ -5563,6 +5581,26 @@ pub struct PaymentsRetrieveResponse {
     pub attempts: Option<Vec<PaymentAttemptResponse>>,
 }
 
+#[cfg(feature = "v2")]
+impl PaymentsRetrieveResponse {
+    pub fn find_attempt_in_attempts_list_using_connector_transaction_id(
+        self,
+        connector_transaction_id: &common_utils::types::ConnectorTransactionId,
+    ) -> Option<PaymentAttemptResponse> {
+        self.attempts
+            .as_ref()
+            .and_then(|attempts| {
+                attempts.iter().find(|attempt| {
+                    attempt
+                        .connector_payment_id
+                        .as_ref()
+                        .is_some_and(|txn_id| txn_id == connector_transaction_id)
+                })
+            })
+            .cloned()
+    }
+}
+
 #[derive(Debug, serde::Deserialize, serde::Serialize, Clone)]
 #[cfg(feature = "v2")]
 pub struct PaymentStartRedirectionRequest {

crates/api_models/src/webhooks.rs

@@ -57,6 +57,14 @@ pub enum IncomingWebhookEvent {
     PayoutExpired,
     #[cfg(feature = "payouts")]
     PayoutReversed,
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    RecoveryPaymentFailure,
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    RecoveryPaymentSuccess,
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    RecoveryPaymentPending,
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    RecoveryInvoiceCancel,
 }
 
 pub enum WebhookFlow {
@@ -71,6 +79,8 @@ pub enum WebhookFlow {
     Mandate,
     ExternalAuthentication,
     FraudCheck,
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    Recovery,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
@@ -197,6 +207,11 @@ impl From<IncomingWebhookEvent> for WebhookFlow {
             | IncomingWebhookEvent::PayoutCreated
             | IncomingWebhookEvent::PayoutExpired
             | IncomingWebhookEvent::PayoutReversed => Self::Payout,
+            #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+            IncomingWebhookEvent::RecoveryInvoiceCancel
+            | IncomingWebhookEvent::RecoveryPaymentFailure
+            | IncomingWebhookEvent::RecoveryPaymentPending
+            | IncomingWebhookEvent::RecoveryPaymentSuccess => Self::Recovery,
         }
     }
 }
@@ -236,6 +251,14 @@ pub enum ObjectReferenceId {
     ExternalAuthenticationID(AuthenticationIdType),
     #[cfg(feature = "payouts")]
     PayoutId(PayoutIdType),
+    #[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+    InvoiceId(InvoiceIdType),
+}
+
+#[cfg(all(feature = "revenue_recovery", feature = "v2"))]
+#[derive(Clone)]
+pub enum InvoiceIdType {
+    ConnectorInvoiceId(String),
 }
 
 pub struct IncomingWebhookDetails {
@@ -303,3 +326,15 @@ pub struct ConnectorWebhookSecrets {
     pub secret: Vec<u8>,
     pub additional_secret: Option<masking::Secret<String>>,
 }
+
+#[cfg(all(feature = "v2", feature = "revenue_recovery"))]
+impl IncomingWebhookEvent {
+    pub fn is_recovery_transaction_event(&self) -> bool {
+        matches!(
+            self,
+            Self::RecoveryPaymentFailure
+                | Self::RecoveryPaymentSuccess
+                | Self::RecoveryPaymentPending
+        )
+    }
+}

crates/common_enums/src/enums.rs

@@ -7591,3 +7591,28 @@ pub enum PaymentConnectorTransmission {
     /// Payment Connector call succeeded
     ConnectorCallSucceeded,
 }
+
+#[derive(
+    Clone,
+    Copy,
+    Debug,
+    Default,
+    Eq,
+    Hash,
+    PartialEq,
+    serde::Deserialize,
+    serde::Serialize,
+    strum::Display,
+    strum::EnumString,
+    ToSchema,
+)]
+#[router_derive::diesel_enum(storage_type = "db_enum")]
+#[strum(serialize_all = "snake_case")]
+#[serde(rename_all = "snake_case")]
+pub enum TriggeredBy {
+    /// Denotes payment attempt is been created by internal system.
+    #[default]
+    Internal,
+    /// Denotes payment attempt is been created by external system.
+    External,
+}

crates/common_utils/src/ext_traits.rs

@@ -4,6 +4,8 @@
 use error_stack::ResultExt;
 use masking::{ExposeInterface, PeekInterface, Secret, Strategy};
 use quick_xml::de;
+#[cfg(all(feature = "logs", feature = "async_ext"))]
+use router_env::logger;
 use serde::{Deserialize, Serialize};
 
 use crate::{
@@ -295,28 +297,34 @@ impl<T> StringExt<T> for String {
 /// Extending functionalities of Wrapper types for idiomatic
 #[cfg(feature = "async_ext")]
 #[cfg_attr(feature = "async_ext", async_trait::async_trait)]
-pub trait AsyncExt<A, B> {
+pub trait AsyncExt<A> {
     /// Output type of the map function
     type WrappedSelf<T>;
 
     /// Extending map by allowing functions which are async
-    async fn async_map<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_map<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = B> + Send;
 
     /// Extending the `and_then` by allowing functions which are async
-    async fn async_and_then<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_and_then<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = Self::WrappedSelf<B>> + Send;
+
+    /// Extending `unwrap_or_else` to allow async fallback
+    async fn async_unwrap_or_else<F, Fut>(self, func: F) -> A
+    where
+        F: FnOnce() -> Fut + Send,
+        Fut: futures::Future<Output = A> + Send;
 }
 
 #[cfg(feature = "async_ext")]
 #[cfg_attr(feature = "async_ext", async_trait::async_trait)]
-impl<A: Send, B, E: Send> AsyncExt<A, B> for Result<A, E> {
+impl<A: Send, E: Send + std::fmt::Debug> AsyncExt<A> for Result<A, E> {
     type WrappedSelf<T> = Result<T, E>;
-    async fn async_and_then<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_and_then<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = Self::WrappedSelf<B>> + Send,
@@ -327,7 +335,7 @@ impl<A: Send, B, E: Send> AsyncExt<A, B> for Result<A, E> {
         }
     }
 
-    async fn async_map<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_map<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = B> + Send,
@@ -337,13 +345,28 @@ impl<A: Send, B, E: Send> AsyncExt<A, B> for Result<A, E> {
             Err(err) => Err(err),
         }
     }
+
+    async fn async_unwrap_or_else<F, Fut>(self, func: F) -> A
+    where
+        F: FnOnce() -> Fut + Send,
+        Fut: futures::Future<Output = A> + Send,
+    {
+        match self {
+            Ok(a) => a,
+            Err(_err) => {
+                #[cfg(feature = "logs")]
+                logger::error!("Error: {:?}", _err);
+                func().await
+            }
+        }
+    }
 }
 
 #[cfg(feature = "async_ext")]
 #[cfg_attr(feature = "async_ext", async_trait::async_trait)]
-impl<A: Send, B> AsyncExt<A, B> for Option<A> {
+impl<A: Send> AsyncExt<A> for Option<A> {
     type WrappedSelf<T> = Option<T>;
-    async fn async_and_then<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_and_then<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = Self::WrappedSelf<B>> + Send,
@@ -354,7 +377,7 @@ impl<A: Send, B> AsyncExt<A, B> for Option<A> {
         }
     }
 
-    async fn async_map<F, Fut>(self, func: F) -> Self::WrappedSelf<B>
+    async fn async_map<F, B, Fut>(self, func: F) -> Self::WrappedSelf<B>
     where
         F: FnOnce(A) -> Fut + Send,
         Fut: futures::Future<Output = B> + Send,
@@ -364,6 +387,17 @@ impl<A: Send, B> AsyncExt<A, B> for Option<A> {
             None => None,
         }
     }
+
+    async fn async_unwrap_or_else<F, Fut>(self, func: F) -> A
+    where
+        F: FnOnce() -> Fut + Send,
+        Fut: futures::Future<Output = A> + Send,
+    {
+        match self {
+            Some(a) => a,
+            None => func().await,
+        }
+    }
 }
 
 /// Extension trait for validating application configuration. This trait provides utilities to