feat(router): add payment incoming webhooks support for v2

api-reference-v2/openapi_spec.json

@@ -13392,7 +13392,8 @@
             ],
             "nullable": true
           }
-        }
+        },
+        "additionalProperties": false
       },
       "PaymentsConfirmIntentResponse": {
         "type": "object",
@@ -15126,6 +15127,11 @@
           "force_sync": {
             "type": "boolean",
             "description": "A boolean used to indicate if the payment status should be fetched from the connector\nIf this is set to true, the status will be fetched from the connector"
+          },
+          "param": {
+            "type": "string",
+            "description": "These are the query params that are sent in case of redirect response.\nThese can be ingested by the connector to take necessary actions.",
+            "nullable": true
           }
         }
       },

crates/api_models/src/admin.rs

@@ -2007,7 +2007,7 @@ pub struct ProfileCreate {
 
     /// The URL to redirect after the completion of the operation
     #[schema(value_type = Option<String>, max_length = 255, example = "https://www.example.com/success")]
-    pub return_url: Option<url::Url>,
+    pub return_url: Option<common_utils::types::Url>,
 
     /// A boolean value to indicate if payment response hash needs to be enabled
     #[schema(default = true, example = true)]
@@ -2244,7 +2244,7 @@ pub struct ProfileResponse {
 
     /// The URL to redirect after the completion of the operation
     #[schema(value_type = Option<String>, max_length = 255, example = "https://www.example.com/success")]
-    pub return_url: Option<String>,
+    pub return_url: Option<common_utils::types::Url>,
 
     /// A boolean value to indicate if payment response hash needs to be enabled
     #[schema(default = true, example = true)]
@@ -2474,7 +2474,7 @@ pub struct ProfileUpdate {
 
     /// The URL to redirect after the completion of the operation
     #[schema(value_type = Option<String>, max_length = 255, example = "https://www.example.com/success")]
-    pub return_url: Option<url::Url>,
+    pub return_url: Option<common_utils::types::Url>,
 
     /// A boolean value to indicate if payment response hash needs to be enabled
     #[schema(default = true, example = true)]

crates/api_models/src/payments.rs

@@ -3652,6 +3652,7 @@ pub struct PaymentMethodDataResponseWithBilling {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, ToSchema)]
+#[cfg(feature = "v1")]
 pub enum PaymentIdType {
     /// The identifier for payment intent
     PaymentIntentId(id_type::PaymentId),
@@ -3663,6 +3664,20 @@ pub enum PaymentIdType {
     PreprocessingId(String),
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, ToSchema)]
+#[cfg(feature = "v2")]
+pub enum PaymentIdType {
+    /// The identifier for payment intent
+    PaymentIntentId(id_type::GlobalPaymentId),
+    /// The identifier for connector transaction
+    ConnectorTransactionId(String),
+    /// The identifier for payment attempt
+    PaymentAttemptId(String),
+    /// The identifier for preprocessing step
+    PreprocessingId(String),
+}
+
+#[cfg(feature = "v1")]
 impl fmt::Display for PaymentIdType {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
@@ -3687,6 +3702,7 @@ impl fmt::Display for PaymentIdType {
     }
 }
 
+#[cfg(feature = "v1")]
 impl Default for PaymentIdType {
     fn default() -> Self {
         Self::PaymentIntentId(Default::default())
@@ -4459,6 +4475,7 @@ pub struct PaymentsResponse {
 /// Request for Payment Intent Confirm
 #[cfg(feature = "v2")]
 #[derive(Debug, serde::Deserialize, serde::Serialize, ToSchema)]
+#[serde(deny_unknown_fields)]
 pub struct PaymentsConfirmIntentRequest {
     /// The URL to which you want the user to be redirected after the completion of the payment operation
     /// If this url is not passed, the url configured in the business profile will be used
@@ -4499,11 +4516,15 @@ pub struct PaymentsRetrieveRequest {
     /// If this is set to true, the status will be fetched from the connector
     #[serde(default)]
     pub force_sync: bool,
+
+    /// These are the query params that are sent in case of redirect response.
+    /// These can be ingested by the connector to take necessary actions.
+    pub param: Option<String>,
 }
 
 /// Error details for the payment
 #[cfg(feature = "v2")]
-#[derive(Debug, serde::Serialize, ToSchema)]
+#[derive(Debug, serde::Serialize, Clone, ToSchema)]
 pub struct ErrorDetails {
     /// The error code
     pub code: String,
@@ -4588,7 +4609,7 @@ pub struct PaymentsConfirmIntentResponse {
 // TODO: have a separate response for detailed, summarized
 /// Response for Payment Intent Confirm
 #[cfg(feature = "v2")]
-#[derive(Debug, serde::Serialize, ToSchema)]
+#[derive(Debug, serde::Serialize, Clone, ToSchema)]
 pub struct PaymentsRetrieveResponse {
     /// Unique identifier for the payment. This ensures idempotency for multiple payments
     /// that have been done by a single merchant.
@@ -5147,6 +5168,7 @@ pub struct PgRedirectResponse {
     pub amount: Option<MinorUnit>,
 }
 
+#[cfg(feature = "v1")]
 #[derive(Debug, serde::Serialize, PartialEq, Eq, serde::Deserialize)]
 pub struct RedirectionResponse {
     pub return_url: String,
@@ -5156,6 +5178,12 @@ pub struct RedirectionResponse {
     pub headers: Vec<(String, String)>,
 }
 
+#[cfg(feature = "v2")]
+#[derive(Debug, serde::Serialize, PartialEq, Eq, serde::Deserialize)]
+pub struct RedirectionResponse {
+    pub return_url_with_query_params: String,
+}
+
 #[derive(Debug, serde::Deserialize)]
 pub struct PaymentsResponseForm {
     pub transaction_id: String,
@@ -6234,6 +6262,85 @@ pub struct FrmMessage {
     pub frm_error: Option<String>,
 }
 
+#[cfg(feature = "v2")]
+mod payment_id_type {
+    use std::{borrow::Cow, fmt};
+
+    use serde::{
+        de::{self, Visitor},
+        Deserializer,
+    };
+
+    use super::PaymentIdType;
+
+    struct PaymentIdVisitor;
+    struct OptionalPaymentIdVisitor;
+
+    impl<'de> Visitor<'de> for PaymentIdVisitor {
+        type Value = PaymentIdType;
+
+        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+            formatter.write_str("payment id")
+        }
+
+        fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+        where
+            E: de::Error,
+        {
+            common_utils::id_type::GlobalPaymentId::try_from(Cow::Owned(value.to_string()))
+                .map_err(de::Error::custom)
+                .map(PaymentIdType::PaymentIntentId)
+        }
+    }
+
+    impl<'de> Visitor<'de> for OptionalPaymentIdVisitor {
+        type Value = Option<PaymentIdType>;
+
+        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+            formatter.write_str("payment id")
+        }
+
+        fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
+        where
+            D: Deserializer<'de>,
+        {
+            deserializer.deserialize_any(PaymentIdVisitor).map(Some)
+        }
+
+        fn visit_none<E>(self) -> Result<Self::Value, E>
+        where
+            E: de::Error,
+        {
+            Ok(None)
+        }
+
+        fn visit_unit<E>(self) -> Result<Self::Value, E>
+        where
+            E: de::Error,
+        {
+            Ok(None)
+        }
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn deserialize<'a, D>(deserializer: D) -> Result<PaymentIdType, D::Error>
+    where
+        D: Deserializer<'a>,
+    {
+        deserializer.deserialize_any(PaymentIdVisitor)
+    }
+
+    pub(crate) fn deserialize_option<'a, D>(
+        deserializer: D,
+    ) -> Result<Option<PaymentIdType>, D::Error>
+    where
+        D: Deserializer<'a>,
+    {
+        deserializer.deserialize_option(OptionalPaymentIdVisitor)
+    }
+}
+
+#[cfg(feature = "v1")]
 mod payment_id_type {
     use std::{borrow::Cow, fmt};
 

crates/api_models/src/webhooks.rs

@@ -76,25 +76,45 @@ pub enum WebhookFlow {
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
 /// This enum tells about the affect a webhook had on an object
 pub enum WebhookResponseTracker {
+    #[cfg(feature = "v1")]
     Payment {
         payment_id: common_utils::id_type::PaymentId,
         status: common_enums::IntentStatus,
     },
+    #[cfg(feature = "v2")]
+    Payment {
+        payment_id: common_utils::id_type::GlobalPaymentId,
+        status: common_enums::IntentStatus,
+    },
     #[cfg(feature = "payouts")]
     Payout {
         payout_id: String,
         status: common_enums::PayoutStatus,
     },
+    #[cfg(feature = "v1")]
     Refund {
         payment_id: common_utils::id_type::PaymentId,
         refund_id: String,
         status: common_enums::RefundStatus,
     },
+    #[cfg(feature = "v2")]
+    Refund {
+        payment_id: common_utils::id_type::GlobalPaymentId,
+        refund_id: String,
+        status: common_enums::RefundStatus,
+    },
+    #[cfg(feature = "v1")]
     Dispute {
         dispute_id: String,
         payment_id: common_utils::id_type::PaymentId,
         status: common_enums::DisputeStatus,
     },
+    #[cfg(feature = "v2")]
+    Dispute {
+        dispute_id: String,
+        payment_id: common_utils::id_type::GlobalPaymentId,
+        status: common_enums::DisputeStatus,
+    },
     Mandate {
         mandate_id: String,
         status: common_enums::MandateStatus,
@@ -103,6 +123,7 @@ pub enum WebhookResponseTracker {
 }
 
 impl WebhookResponseTracker {
+    #[cfg(feature = "v1")]
     pub fn get_payment_id(&self) -> Option<common_utils::id_type::PaymentId> {
         match self {
             Self::Payment { payment_id, .. }
@@ -113,6 +134,18 @@ impl WebhookResponseTracker {
             Self::Payout { .. } => None,
         }
     }
+
+    #[cfg(feature = "v2")]
+    pub fn get_payment_id(&self) -> Option<common_utils::id_type::GlobalPaymentId> {
+        match self {
+            Self::Payment { payment_id, .. }
+            | Self::Refund { payment_id, .. }
+            | Self::Dispute { payment_id, .. } => Some(payment_id.to_owned()),
+            Self::NoEffect | Self::Mandate { .. } => None,
+            #[cfg(feature = "payouts")]
+            Self::Payout { .. } => None,
+        }
+    }
 }
 
 impl From<IncomingWebhookEvent> for WebhookFlow {
@@ -227,6 +260,7 @@ pub struct OutgoingWebhook {
 
 #[derive(Debug, Clone, Serialize, ToSchema)]
 #[serde(tag = "type", content = "object", rename_all = "snake_case")]
+#[cfg(feature = "v1")]
 pub enum OutgoingWebhookContent {
     #[schema(value_type = PaymentsResponse, title = "PaymentsResponse")]
     PaymentDetails(Box<payments::PaymentsResponse>),
@@ -241,6 +275,23 @@ pub enum OutgoingWebhookContent {
     PayoutDetails(Box<payouts::PayoutCreateResponse>),
 }
 
+#[derive(Debug, Clone, Serialize, ToSchema)]
+#[serde(tag = "type", content = "object", rename_all = "snake_case")]
+#[cfg(feature = "v2")]
+pub enum OutgoingWebhookContent {
+    #[schema(value_type = PaymentsResponse, title = "PaymentsResponse")]
+    PaymentDetails(Box<payments::PaymentsRetrieveResponse>),
+    #[schema(value_type = RefundResponse, title = "RefundResponse")]
+    RefundDetails(Box<refunds::RefundResponse>),
+    #[schema(value_type = DisputeResponse, title = "DisputeResponse")]
+    DisputeDetails(Box<disputes::DisputeResponse>),
+    #[schema(value_type = MandateResponse, title = "MandateResponse")]
+    MandateDetails(Box<mandates::MandateResponse>),
+    #[cfg(feature = "payouts")]
+    #[schema(value_type = PayoutCreateResponse, title = "PayoutCreateResponse")]
+    PayoutDetails(Box<payouts::PayoutCreateResponse>),
+}
+
 #[derive(Debug, Clone, Serialize)]
 pub struct ConnectorWebhookSecrets {
     pub secret: Vec<u8>,

crates/common_utils/src/consts.rs

@@ -159,6 +159,9 @@ pub const MAX_STATEMENT_DESCRIPTOR_LENGTH: u16 = 22;
 /// Payout flow identifier used for performing GSM operations
 pub const PAYOUT_FLOW_STR: &str = "payout_flow";
 
+/// length of the publishable key
+pub const PUBLISHABLE_KEY_LENGTH: u16 = 39;
+
 /// The number of bytes allocated for the hashed connector transaction ID.
 /// Total number of characters equals CONNECTOR_TRANSACTION_ID_HASH_BYTES times 2.
 pub const CONNECTOR_TRANSACTION_ID_HASH_BYTES: usize = 25;

crates/common_utils/src/events.rs

@@ -60,16 +60,27 @@ pub enum ApiEventsType {
     PaymentMethodList {
         payment_id: Option<String>,
     },
+    #[cfg(feature = "v1")]
     Webhooks {
         connector: String,
         payment_id: Option<id_type::PaymentId>,
     },
+    #[cfg(feature = "v2")]
+    Webhooks {
+        connector: id_type::MerchantConnectorAccountId,
+        payment_id: Option<id_type::GlobalPaymentId>,
+    },
     Routing,
     ResourceListAPI,
+    #[cfg(feature = "v1")]
     PaymentRedirectionResponse {
         connector: Option<String>,
         payment_id: Option<id_type::PaymentId>,
     },
+    #[cfg(feature = "v2")]
+    PaymentRedirectionResponse {
+        payment_id: id_type::GlobalPaymentId,
+    },
     Gsm,
     // TODO: This has to be removed once the corresponding apiEventTypes are created
     Miscellaneous,

crates/common_utils/src/id_type/global_id/payment.rs

@@ -66,3 +66,16 @@ impl GlobalAttemptId {
         self.0.get_string_repr()
     }
 }
+
+impl TryFrom<std::borrow::Cow<'static, str>> for GlobalAttemptId {
+    type Error = error_stack::Report<errors::ValidationError>;
+    fn try_from(value: std::borrow::Cow<'static, str>) -> Result<Self, Self::Error> {
+        use error_stack::ResultExt;
+        let global_attempt_id = super::GlobalId::from_string(value).change_context(
+            errors::ValidationError::IncorrectValueProvided {
+                field_name: "payment_id",
+            },
+        )?;
+        Ok(Self(global_attempt_id))
+    }
+}