feat(payments): add error details for PaymentsResponse

api-reference/v1/openapi_spec_v1.json

@@ -9065,6 +9065,51 @@
           }
         }
       },
+      "ApiConnectorErrorDetails": {
+        "type": "object",
+        "description": "Error details from the payment connector",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Connector-specific error code",
+            "nullable": true
+          },
+          "message": {
+            "type": "string",
+            "description": "Connector-specific error message",
+            "nullable": true
+          },
+          "reason": {
+            "type": "string",
+            "description": "Additional error reason/details",
+            "nullable": true
+          }
+        }
+      },
+      "ApiIssuerErrorDetails": {
+        "type": "object",
+        "description": "Error details from the card issuer",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Error code from the issuer",
+            "nullable": true
+          },
+          "message": {
+            "type": "string",
+            "description": "Error message from the issuer",
+            "nullable": true
+          },
+          "network_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ApiNetworkErrorDetails"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
       "ApiKeyExpiration": {
         "oneOf": [
           {
@@ -9079,6 +9124,75 @@
           }
         ]
       },
+      "ApiNetworkErrorDetails": {
+        "type": "object",
+        "description": "Network-specific error details (e.g., Visa, Mastercard)",
+        "properties": {
+          "name": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CardNetwork"
+              }
+            ],
+            "nullable": true
+          },
+          "advice_code": {
+            "type": "string",
+            "description": "Network advice code",
+            "nullable": true
+          },
+          "advice_message": {
+            "type": "string",
+            "description": "Network advice message",
+            "nullable": true
+          }
+        }
+      },
+      "ApiUnifiedErrorDetails": {
+        "type": "object",
+        "description": "Unified error details standardized across all payment connectors",
+        "properties": {
+          "category": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UnifiedCode"
+              }
+            ],
+            "nullable": true
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message",
+            "nullable": true
+          },
+          "standardised_code": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/StandardisedCode"
+              }
+            ],
+            "nullable": true
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed description of the error",
+            "nullable": true
+          },
+          "user_guidance_message": {
+            "type": "string",
+            "description": "User-friendly guidance message",
+            "nullable": true
+          },
+          "recommended_action": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RecommendedAction"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
       "ApplePayAddressParameters": {
         "type": "string",
         "enum": [
@@ -24715,6 +24829,36 @@
           }
         }
       },
+      "PaymentErrorDetails": {
+        "type": "object",
+        "description": "Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.",
+        "properties": {
+          "unified_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ApiUnifiedErrorDetails"
+              }
+            ],
+            "nullable": true
+          },
+          "issuer_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ApiIssuerErrorDetails"
+              }
+            ],
+            "nullable": true
+          },
+          "connector_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ApiConnectorErrorDetails"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
       "PaymentExperience": {
         "type": "string",
         "description": "To indicate the type of payment experience that the customer would go through",
@@ -28263,6 +28407,14 @@
             "example": "Failed while verifying the card",
             "nullable": true
           },
+          "error_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentErrorDetails"
+              }
+            ],
+            "nullable": true
+          },
           "payment_experience": {
             "allOf": [
               {
@@ -29853,6 +30005,14 @@
             "description": "error message unified across the connectors is received here if there was an error while calling connector",
             "nullable": true
           },
+          "error_details": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/PaymentErrorDetails"
+              }
+            ],
+            "nullable": true
+          },
           "payment_experience": {
             "allOf": [
               {
@@ -33952,6 +34112,23 @@
           }
         }
       },
+      "RecommendedAction": {
+        "type": "string",
+        "enum": [
+          "do_not_retry",
+          "retry_after10_days",
+          "retry_after1_hour",
+          "retry_after24_hours",
+          "retry_after2_days",
+          "retry_after4_days",
+          "retry_after6_days",
+          "retry_after8_days",
+          "retry_after_instrument_update",
+          "retry_later",
+          "retry_with_different_payment_method_data",
+          "stop_recurring"
+        ]
+      },
       "ReconStatus": {
         "type": "string",
         "enum": [
@@ -37625,6 +37802,16 @@
           "delete"
         ]
       },
+      "UnifiedCode": {
+        "type": "string",
+        "enum": [
+          "UE_1000",
+          "UE_2000",
+          "UE_3000",
+          "UE_4000",
+          "UE_9000"
+        ]
+      },
       "UnpaidInvoicesHandling": {
         "type": "string",
         "enum": [

api-reference/v2/openapi_spec_v2.json

@@ -27608,6 +27608,16 @@
           "journey"
         ]
       },
+      "UnifiedCode": {
+        "type": "string",
+        "enum": [
+          "UE_1000",
+          "UE_2000",
+          "UE_3000",
+          "UE_4000",
+          "UE_9000"
+        ]
+      },
       "UpdateActiveAttempt": {
         "oneOf": [
           {

crates/api_models/src/payments.rs

@@ -7269,6 +7269,11 @@ pub struct PaymentsResponse {
     #[smithy(value_type = "Option<String>")]
     pub unified_message: Option<String>,
 
+    /// Complete error details containing unified, issuer, and connector-level error information.
+    #[schema(value_type = Option<PaymentErrorDetails>)]
+    #[smithy(value_type = "Option<PaymentErrorDetails>")]
+    pub error_details: Option<PaymentErrorDetails>,
+
     /// Describes the type of payment flow experienced by the customer (e.g., 'redirect_to_url', 'invoke_sdk', 'display_qr_code').
     #[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
     #[smithy(value_type = "Option<PaymentExperience>")]
@@ -8183,6 +8188,76 @@ pub struct PaymentsStatusRequest {
     pub return_raw_connector_response: Option<bool>,
 }
 
+/// Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.
+#[cfg(feature = "v1")]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
+pub struct PaymentErrorDetails {
+    /// Unified error details (standardized across connectors)
+    pub unified_details: Option<ApiUnifiedErrorDetails>,
+    /// Error details from the card issuer
+    pub issuer_details: Option<ApiIssuerErrorDetails>,
+    /// Error details from the payment connector
+    pub connector_details: Option<ApiConnectorErrorDetails>,
+}
+
+/// Unified error details standardized across all payment connectors
+#[cfg(feature = "v1")]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
+pub struct ApiUnifiedErrorDetails {
+    /// Error category
+    #[schema(value_type = Option<UnifiedCode>)]
+    pub category: Option<api_enums::UnifiedCode>,
+    /// Human-readable error message
+    pub message: Option<String>,
+    /// Standardised error code
+    #[schema(value_type = Option<StandardisedCode>)]
+    pub standardised_code: Option<api_enums::StandardisedCode>,
+    /// Detailed description of the error
+    pub description: Option<String>,
+    /// User-friendly guidance message
+    pub user_guidance_message: Option<String>,
+    /// Recommended action (e.g., "do_not_retry", "retry_later")
+    #[schema(value_type = Option<RecommendedAction>)]
+    pub recommended_action: Option<api_enums::RecommendedAction>,
+}
+
+/// Error details from the card issuer
+#[cfg(feature = "v1")]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
+pub struct ApiIssuerErrorDetails {
+    /// Error code from the issuer
+    pub code: Option<String>,
+    /// Error message from the issuer
+    pub message: Option<String>,
+    /// Network-specific error details
+    pub network_details: Option<ApiNetworkErrorDetails>,
+}
+
+/// Network-specific error details (e.g., Visa, Mastercard)
+#[cfg(feature = "v1")]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
+pub struct ApiNetworkErrorDetails {
+    /// Card network (e.g., Visa, Mastercard)
+    #[schema(value_type = Option<CardNetwork>)]
+    pub name: Option<api_enums::CardNetwork>,
+    /// Network advice code
+    pub advice_code: Option<String>,
+    /// Network advice message
+    pub advice_message: Option<String>,
+}
+
+/// Error details from the payment connector
+#[cfg(feature = "v1")]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
+pub struct ApiConnectorErrorDetails {
+    /// Connector-specific error code
+    pub code: Option<String>,
+    /// Connector-specific error message
+    pub message: Option<String>,
+    /// Additional error reason/details
+    pub reason: Option<String>,
+}
+
 /// Error details for the payment
 #[cfg(feature = "v2")]
 #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, PartialEq, ToSchema)]

crates/common_enums/src/enums.rs

@@ -9693,6 +9693,36 @@ impl ErrorCategory {
     }
 }
 
+#[derive(
+    Clone,
+    Copy,
+    Debug,
+    Eq,
+    Hash,
+    PartialEq,
+    serde::Serialize,
+    serde::Deserialize,
+    strum::Display,
+    strum::EnumString,
+    ToSchema,
+    PartialOrd,
+    Ord,
+)]
+#[router_derive::diesel_enum(storage_type = "text")]
+#[allow(non_camel_case_types)]
+pub enum UnifiedCode {
+    /// Customer Error - Issue with payment method details
+    UE_1000,
+    /// Connector Declines - Issue with Configurations
+    UE_2000,
+    /// Connector Error - Technical issue with PSP
+    UE_3000,
+    /// Integration Error - Issue in the integration
+    UE_4000,
+    /// Others - Something went wrong
+    UE_9000,
+}
+
 #[derive(
     Clone,
     Debug,

crates/diesel_models/src/payment_attempt.rs

@@ -61,7 +61,7 @@ pub struct ErrorDetails {
 
 #[derive(Clone, Default, Debug, serde::Deserialize, Eq, PartialEq, serde::Serialize)]
 pub struct UnifiedErrorDetails {
-    pub category: Option<String>,
+    pub category: Option<storage_enums::UnifiedCode>,
     pub message: Option<String>,
     pub standardised_code: Option<storage_enums::StandardisedCode>,
     pub description: Option<String>,