feat(core): Add support for Void after Capture (#8839)

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

Author: swangi-kumari

api-reference/docs.json

@@ -42,6 +42,7 @@
                       "v1/payments/payments--confirm",
                       "v1/payments/payments--retrieve",
                       "v1/payments/payments--cancel",
+                      "v1/payments/payments--cancel-post-capture",
                       "v1/payments/payments--capture",
                       "v1/payments/payments--incremental-authorization",
                       "v1/payments/payments--session-token",

api-reference/v1/openapi_spec_v1.json

@@ -1083,6 +1083,67 @@
         ]
       }
     },
+    "/payments/{payment_id}/cancel_post_capture": {
+      "post": {
+        "tags": [
+          "Payments"
+        ],
+        "summary": "Payments - Cancel Post Capture",
+        "description": "A Payment could can be cancelled when it is in one of these statuses: `succeeded`, `partially_captured`, `partially_captured_and_capturable`.",
+        "operationId": "Cancel a Payment Post Capture",
+        "parameters": [
+          {
+            "name": "payment_id",
+            "in": "path",
+            "description": "The identifier for payment",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PaymentsCancelPostCaptureRequest"
+              },
+              "examples": {
+                "Cancel the payment post capture with cancellation reason": {
+                  "value": {
+                    "cancellation_reason": "requested_by_customer"
+                  }
+                },
+                "Cancel the payment post capture with minimal fields": {
+                  "value": {}
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Payment canceled post capture"
+          },
+          "400": {
+            "description": "Missing mandatory fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GenericErrorResponseOpenApi"
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
     "/payments/list": {
       "get": {
         "tags": [
@@ -7894,6 +7955,7 @@
           "authorizing",
           "cod_initiated",
           "voided",
+          "voided_post_charge",
           "void_initiated",
           "capture_initiated",
           "capture_failed",
@@ -14734,6 +14796,7 @@
           "payment_failed",
           "payment_processing",
           "payment_cancelled",
+          "payment_cancelled_post_capture",
           "payment_authorized",
           "payment_captured",
           "payment_expired",
@@ -16581,6 +16644,7 @@
           "succeeded",
           "failed",
           "cancelled",
+          "cancelled_post_capture",
           "processing",
           "requires_customer_action",
           "requires_merchant_action",
@@ -22069,6 +22133,17 @@
           "recurring_mandate"
         ]
       },
+      "PaymentsCancelPostCaptureRequest": {
+        "type": "object",
+        "description": "Request to cancel a payment when the payment is already captured",
+        "properties": {
+          "cancellation_reason": {
+            "type": "string",
+            "description": "The reason for the payment cancel",
+            "nullable": true
+          }
+        }
+      },
       "PaymentsCancelRequest": {
         "type": "object",
         "properties": {
@@ -31718,6 +31793,7 @@
           "AUTHORIZING",
           "C_O_D_INITIATED",
           "VOIDED",
+          "VOIDED_POST_CHARGE",
           "VOID_INITIATED",
           "NOP",
           "CAPTURE_INITIATED",

api-reference/v1/payments/payments--cancel-post-capture.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /payments/{payment_id}/cancel_post_capture
+---

api-reference/v2/openapi_spec_v2.json

@@ -4902,6 +4902,7 @@
           "authorizing",
           "cod_initiated",
           "voided",
+          "voided_post_charge",
           "void_initiated",
           "capture_initiated",
           "capture_failed",
@@ -10781,6 +10782,7 @@
           "payment_failed",
           "payment_processing",
           "payment_cancelled",
+          "payment_cancelled_post_capture",
           "payment_authorized",
           "payment_captured",
           "payment_expired",
@@ -12740,6 +12742,7 @@
           "succeeded",
           "failed",
           "cancelled",
+          "cancelled_post_capture",
           "processing",
           "requires_customer_action",
           "requires_merchant_action",

crates/api_models/src/events/payment.rs

@@ -27,8 +27,8 @@ use crate::{
     payment_methods::{PaymentMethodListRequest, PaymentMethodListResponse},
     payments::{
         ExtendedCardInfoResponse, PaymentIdType, PaymentListFilterConstraints,
-        PaymentListResponseV2, PaymentsApproveRequest, PaymentsCancelRequest,
-        PaymentsCaptureRequest, PaymentsCompleteAuthorizeRequest,
+        PaymentListResponseV2, PaymentsApproveRequest, PaymentsCancelPostCaptureRequest,
+        PaymentsCancelRequest, PaymentsCaptureRequest, PaymentsCompleteAuthorizeRequest,
         PaymentsDynamicTaxCalculationRequest, PaymentsDynamicTaxCalculationResponse,
         PaymentsExternalAuthenticationRequest, PaymentsExternalAuthenticationResponse,
         PaymentsIncrementalAuthorizationRequest, PaymentsManualUpdateRequest,
@@ -134,6 +134,15 @@ impl ApiEventMetric for PaymentsCancelRequest {
     }
 }
 
+#[cfg(feature = "v1")]
+impl ApiEventMetric for PaymentsCancelPostCaptureRequest {
+    fn get_api_event_type(&self) -> Option<ApiEventsType> {
+        Some(ApiEventsType::Payment {
+            payment_id: self.payment_id.clone(),
+        })
+    }
+}
+
 #[cfg(feature = "v1")]
 impl ApiEventMetric for PaymentsApproveRequest {
     fn get_api_event_type(&self) -> Option<ApiEventsType> {

crates/api_models/src/open_router.rs

@@ -221,6 +221,7 @@ pub enum TxnStatus {
     Authorizing,
     CODInitiated,
     Voided,
+    VoidedPostCharge,
     VoidInitiated,
     Nop,
     CaptureInitiated,

crates/api_models/src/payments.rs

@@ -7689,6 +7689,16 @@ pub struct PaymentsCancelRequest {
     pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
 }
 
+/// Request to cancel a payment when the payment is already captured
+#[derive(Default, Debug, serde::Deserialize, serde::Serialize, Clone, ToSchema)]
+pub struct PaymentsCancelPostCaptureRequest {
+    /// The identifier for the payment
+    #[serde(skip)]
+    pub payment_id: id_type::PaymentId,
+    /// The reason for the payment cancel
+    pub cancellation_reason: Option<String>,
+}
+
 #[derive(Default, Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
 pub struct PaymentsIncrementalAuthorizationRequest {
     /// The identifier for the payment

crates/common_enums/src/enums.rs

@@ -141,6 +141,7 @@ pub enum AttemptStatus {
     Authorizing,
     CodInitiated,
     Voided,
+    VoidedPostCharge,
     VoidInitiated,
     CaptureInitiated,
     CaptureFailed,
@@ -166,6 +167,7 @@ impl AttemptStatus {
             | Self::Charged
             | Self::AutoRefunded
             | Self::Voided
+            | Self::VoidedPostCharge
             | Self::VoidFailed
             | Self::CaptureFailed
             | Self::Failure
@@ -1501,6 +1503,7 @@ impl EventClass {
                 EventType::PaymentFailed,
                 EventType::PaymentProcessing,
                 EventType::PaymentCancelled,
+                EventType::PaymentCancelledPostCapture,
                 EventType::PaymentAuthorized,
                 EventType::PaymentCaptured,
                 EventType::PaymentExpired,
@@ -1555,6 +1558,7 @@ pub enum EventType {
     PaymentFailed,
     PaymentProcessing,
     PaymentCancelled,
+    PaymentCancelledPostCapture,
     PaymentAuthorized,
     PaymentCaptured,
     PaymentExpired,
@@ -1659,6 +1663,8 @@ pub enum IntentStatus {
     Failed,
     /// This payment has been cancelled.
     Cancelled,
+    /// This payment has been cancelled post capture.
+    CancelledPostCapture,
     /// This payment is still being processed by the payment processor.
     /// The status update might happen through webhooks or polling with the connector.
     Processing,
@@ -1690,6 +1696,7 @@ impl IntentStatus {
             Self::Succeeded
             | Self::Failed
             | Self::Cancelled
+            | Self::CancelledPostCapture
             | Self::PartiallyCaptured
             | Self::Expired => true,
             Self::Processing
@@ -1713,6 +1720,7 @@ impl IntentStatus {
             | Self::Succeeded
             | Self::Failed
             | Self::Cancelled
+            | Self::CancelledPostCapture
             |  Self::PartiallyCaptured
             |  Self::RequiresCapture | Self::Conflicted | Self::Expired=> false,
             Self::Processing
@@ -1826,6 +1834,7 @@ impl From<AttemptStatus> for PaymentMethodStatus {
         match attempt_status {
             AttemptStatus::Failure
             | AttemptStatus::Voided
+            | AttemptStatus::VoidedPostCharge
             | AttemptStatus::Started
             | AttemptStatus::Pending
             | AttemptStatus::Unresolved

crates/common_enums/src/transformers.rs

@@ -2123,6 +2123,7 @@ impl From<AttemptStatus> for IntentStatus {
             | AttemptStatus::CaptureFailed
             | AttemptStatus::Failure => Self::Failed,
             AttemptStatus::Voided => Self::Cancelled,
+            AttemptStatus::VoidedPostCharge => Self::CancelledPostCapture,
             AttemptStatus::Expired => Self::Expired,
         }
     }
@@ -2138,6 +2139,7 @@ impl From<IntentStatus> for Option<EventType> {
             | IntentStatus::RequiresCustomerAction
             | IntentStatus::Conflicted => Some(EventType::ActionRequired),
             IntentStatus::Cancelled => Some(EventType::PaymentCancelled),
+            IntentStatus::CancelledPostCapture => Some(EventType::PaymentCancelledPostCapture),
             IntentStatus::Expired => Some(EventType::PaymentExpired),
             IntentStatus::PartiallyCaptured | IntentStatus::PartiallyCapturedAndCapturable => {
                 Some(EventType::PaymentCaptured)

crates/hyperswitch_connectors/src/connectors/chargebee/transformers.rs

@@ -698,6 +698,7 @@ impl TryFrom<enums::AttemptStatus> for ChargebeeRecordStatus {
             | enums::AttemptStatus::Authorizing
             | enums::AttemptStatus::CodInitiated
             | enums::AttemptStatus::Voided
+            | enums::AttemptStatus::VoidedPostCharge
             | enums::AttemptStatus::VoidInitiated
             | enums::AttemptStatus::CaptureInitiated
             | enums::AttemptStatus::VoidFailed