Skip to content

Commit df148e0

Browse files
ayush22667hyperswitch-bot[bot]
authored and
Sayak Basak
committed
feat(payments): add error details for PaymentsResponse (#10799)
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
1 parent 882ebe6 commit df148e0

File tree

18 files changed

+408
-4
lines changed

18 files changed

+408
-4
lines changed

‎api-reference/v1/openapi_spec_v1.json‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9065,6 +9065,51 @@
90659065
}
90669066
}
90679067
},
9068+
"ApiConnectorErrorDetails": {
9069+
"type": "object",
9070+
"description": "Error details from the payment connector",
9071+
"properties": {
9072+
"code": {
9073+
"type": "string",
9074+
"description": "Connector-specific error code",
9075+
"nullable": true
9076+
},
9077+
"message": {
9078+
"type": "string",
9079+
"description": "Connector-specific error message",
9080+
"nullable": true
9081+
},
9082+
"reason": {
9083+
"type": "string",
9084+
"description": "Additional error reason/details",
9085+
"nullable": true
9086+
}
9087+
}
9088+
},
9089+
"ApiIssuerErrorDetails": {
9090+
"type": "object",
9091+
"description": "Error details from the card issuer",
9092+
"properties": {
9093+
"code": {
9094+
"type": "string",
9095+
"description": "Error code from the issuer",
9096+
"nullable": true
9097+
},
9098+
"message": {
9099+
"type": "string",
9100+
"description": "Error message from the issuer",
9101+
"nullable": true
9102+
},
9103+
"network_details": {
9104+
"allOf": [
9105+
{
9106+
"$ref": "#/components/schemas/ApiNetworkErrorDetails"
9107+
}
9108+
],
9109+
"nullable": true
9110+
}
9111+
}
9112+
},
90689113
"ApiKeyExpiration": {
90699114
"oneOf": [
90709115
{
@@ -9079,6 +9124,75 @@
90799124
}
90809125
]
90819126
},
9127+
"ApiNetworkErrorDetails": {
9128+
"type": "object",
9129+
"description": "Network-specific error details (e.g., Visa, Mastercard)",
9130+
"properties": {
9131+
"name": {
9132+
"allOf": [
9133+
{
9134+
"$ref": "#/components/schemas/CardNetwork"
9135+
}
9136+
],
9137+
"nullable": true
9138+
},
9139+
"advice_code": {
9140+
"type": "string",
9141+
"description": "Network advice code",
9142+
"nullable": true
9143+
},
9144+
"advice_message": {
9145+
"type": "string",
9146+
"description": "Network advice message",
9147+
"nullable": true
9148+
}
9149+
}
9150+
},
9151+
"ApiUnifiedErrorDetails": {
9152+
"type": "object",
9153+
"description": "Unified error details standardized across all payment connectors",
9154+
"properties": {
9155+
"category": {
9156+
"allOf": [
9157+
{
9158+
"$ref": "#/components/schemas/UnifiedCode"
9159+
}
9160+
],
9161+
"nullable": true
9162+
},
9163+
"message": {
9164+
"type": "string",
9165+
"description": "Human-readable error message",
9166+
"nullable": true
9167+
},
9168+
"standardised_code": {
9169+
"allOf": [
9170+
{
9171+
"$ref": "#/components/schemas/StandardisedCode"
9172+
}
9173+
],
9174+
"nullable": true
9175+
},
9176+
"description": {
9177+
"type": "string",
9178+
"description": "Detailed description of the error",
9179+
"nullable": true
9180+
},
9181+
"user_guidance_message": {
9182+
"type": "string",
9183+
"description": "User-friendly guidance message",
9184+
"nullable": true
9185+
},
9186+
"recommended_action": {
9187+
"allOf": [
9188+
{
9189+
"$ref": "#/components/schemas/RecommendedAction"
9190+
}
9191+
],
9192+
"nullable": true
9193+
}
9194+
}
9195+
},
90829196
"ApplePayAddressParameters": {
90839197
"type": "string",
90849198
"enum": [
@@ -24724,6 +24838,36 @@
2472424838
}
2472524839
}
2472624840
},
24841+
"PaymentErrorDetails": {
24842+
"type": "object",
24843+
"description": "Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.",
24844+
"properties": {
24845+
"unified_details": {
24846+
"allOf": [
24847+
{
24848+
"$ref": "#/components/schemas/ApiUnifiedErrorDetails"
24849+
}
24850+
],
24851+
"nullable": true
24852+
},
24853+
"issuer_details": {
24854+
"allOf": [
24855+
{
24856+
"$ref": "#/components/schemas/ApiIssuerErrorDetails"
24857+
}
24858+
],
24859+
"nullable": true
24860+
},
24861+
"connector_details": {
24862+
"allOf": [
24863+
{
24864+
"$ref": "#/components/schemas/ApiConnectorErrorDetails"
24865+
}
24866+
],
24867+
"nullable": true
24868+
}
24869+
}
24870+
},
2472724871
"PaymentExperience": {
2472824872
"type": "string",
2472924873
"description": "To indicate the type of payment experience that the customer would go through",
@@ -28287,6 +28431,14 @@
2828728431
"example": "Failed while verifying the card",
2828828432
"nullable": true
2828928433
},
28434+
"error_details": {
28435+
"allOf": [
28436+
{
28437+
"$ref": "#/components/schemas/PaymentErrorDetails"
28438+
}
28439+
],
28440+
"nullable": true
28441+
},
2829028442
"payment_experience": {
2829128443
"allOf": [
2829228444
{
@@ -29892,6 +30044,14 @@
2989230044
"description": "error message unified across the connectors is received here if there was an error while calling connector",
2989330045
"nullable": true
2989430046
},
30047+
"error_details": {
30048+
"allOf": [
30049+
{
30050+
"$ref": "#/components/schemas/PaymentErrorDetails"
30051+
}
30052+
],
30053+
"nullable": true
30054+
},
2989530055
"payment_experience": {
2989630056
"allOf": [
2989730057
{
@@ -33991,6 +34151,23 @@
3399134151
}
3399234152
}
3399334153
},
34154+
"RecommendedAction": {
34155+
"type": "string",
34156+
"enum": [
34157+
"do_not_retry",
34158+
"retry_after10_days",
34159+
"retry_after1_hour",
34160+
"retry_after24_hours",
34161+
"retry_after2_days",
34162+
"retry_after4_days",
34163+
"retry_after6_days",
34164+
"retry_after8_days",
34165+
"retry_after_instrument_update",
34166+
"retry_later",
34167+
"retry_with_different_payment_method_data",
34168+
"stop_recurring"
34169+
]
34170+
},
3399434171
"ReconStatus": {
3399534172
"type": "string",
3399634173
"enum": [
@@ -37665,6 +37842,16 @@
3766537842
"delete"
3766637843
]
3766737844
},
37845+
"UnifiedCode": {
37846+
"type": "string",
37847+
"enum": [
37848+
"UE_1000",
37849+
"UE_2000",
37850+
"UE_3000",
37851+
"UE_4000",
37852+
"UE_9000"
37853+
]
37854+
},
3766837855
"UnpaidInvoicesHandling": {
3766937856
"type": "string",
3767037857
"enum": [

‎api-reference/v2/openapi_spec_v2.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27813,6 +27813,16 @@
2781327813
"journey"
2781427814
]
2781527815
},
27816+
"UnifiedCode": {
27817+
"type": "string",
27818+
"enum": [
27819+
"UE_1000",
27820+
"UE_2000",
27821+
"UE_3000",
27822+
"UE_4000",
27823+
"UE_9000"
27824+
]
27825+
},
2781627826
"UpdateActiveAttempt": {
2781727827
"oneOf": [
2781827828
{

‎crates/api_models/src/payments.rs‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7293,6 +7293,11 @@ pub struct PaymentsResponse {
72937293
#[smithy(value_type = "Option<String>")]
72947294
pub unified_message: Option<String>,
72957295

7296+
/// Complete error details containing unified, issuer, and connector-level error information.
7297+
#[schema(value_type = Option<PaymentErrorDetails>)]
7298+
#[smithy(value_type = "Option<PaymentErrorDetails>")]
7299+
pub error_details: Option<PaymentErrorDetails>,
7300+
72967301
/// Describes the type of payment flow experienced by the customer (e.g., 'redirect_to_url', 'invoke_sdk', 'display_qr_code').
72977302
#[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
72987303
#[smithy(value_type = "Option<PaymentExperience>")]
@@ -8207,6 +8212,76 @@ pub struct PaymentsStatusRequest {
82078212
pub return_raw_connector_response: Option<bool>,
82088213
}
82098214

8215+
/// Complete error details for V1 PaymentsResponse containing unified, issuer, and connector-level error information.
8216+
#[cfg(feature = "v1")]
8217+
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
8218+
pub struct PaymentErrorDetails {
8219+
/// Unified error details (standardized across connectors)
8220+
pub unified_details: Option<ApiUnifiedErrorDetails>,
8221+
/// Error details from the card issuer
8222+
pub issuer_details: Option<ApiIssuerErrorDetails>,
8223+
/// Error details from the payment connector
8224+
pub connector_details: Option<ApiConnectorErrorDetails>,
8225+
}
8226+
8227+
/// Unified error details standardized across all payment connectors
8228+
#[cfg(feature = "v1")]
8229+
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
8230+
pub struct ApiUnifiedErrorDetails {
8231+
/// Error category
8232+
#[schema(value_type = Option<UnifiedCode>)]
8233+
pub category: Option<String>,
8234+
/// Human-readable error message
8235+
pub message: Option<String>,
8236+
/// Standardised error code
8237+
#[schema(value_type = Option<StandardisedCode>)]
8238+
pub standardised_code: Option<api_enums::StandardisedCode>,
8239+
/// Detailed description of the error
8240+
pub description: Option<String>,
8241+
/// User-friendly guidance message
8242+
pub user_guidance_message: Option<String>,
8243+
/// Recommended action (e.g., "do_not_retry", "retry_later")
8244+
#[schema(value_type = Option<RecommendedAction>)]
8245+
pub recommended_action: Option<api_enums::RecommendedAction>,
8246+
}
8247+
8248+
/// Error details from the card issuer
8249+
#[cfg(feature = "v1")]
8250+
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
8251+
pub struct ApiIssuerErrorDetails {
8252+
/// Error code from the issuer
8253+
pub code: Option<String>,
8254+
/// Error message from the issuer
8255+
pub message: Option<String>,
8256+
/// Network-specific error details
8257+
pub network_details: Option<ApiNetworkErrorDetails>,
8258+
}
8259+
8260+
/// Network-specific error details (e.g., Visa, Mastercard)
8261+
#[cfg(feature = "v1")]
8262+
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
8263+
pub struct ApiNetworkErrorDetails {
8264+
/// Card network (e.g., Visa, Mastercard)
8265+
#[schema(value_type = Option<CardNetwork>)]
8266+
pub name: Option<api_enums::CardNetwork>,
8267+
/// Network advice code
8268+
pub advice_code: Option<String>,
8269+
/// Network advice message
8270+
pub advice_message: Option<String>,
8271+
}
8272+
8273+
/// Error details from the payment connector
8274+
#[cfg(feature = "v1")]
8275+
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, ToSchema)]
8276+
pub struct ApiConnectorErrorDetails {
8277+
/// Connector-specific error code
8278+
pub code: Option<String>,
8279+
/// Connector-specific error message
8280+
pub message: Option<String>,
8281+
/// Additional error reason/details
8282+
pub reason: Option<String>,
8283+
}
8284+
82108285
/// Error details for the payment
82118286
#[cfg(feature = "v2")]
82128287
#[derive(Debug, serde::Serialize, serde::Deserialize, Clone, PartialEq, ToSchema)]

‎crates/common_enums/src/enums.rs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9740,6 +9740,36 @@ impl ErrorCategory {
97409740
}
97419741
}
97429742

9743+
#[derive(
9744+
Clone,
9745+
Copy,
9746+
Debug,
9747+
Eq,
9748+
Hash,
9749+
PartialEq,
9750+
serde::Serialize,
9751+
serde::Deserialize,
9752+
strum::Display,
9753+
strum::EnumString,
9754+
ToSchema,
9755+
PartialOrd,
9756+
Ord,
9757+
)]
9758+
#[router_derive::diesel_enum(storage_type = "text")]
9759+
#[allow(non_camel_case_types)]
9760+
pub enum UnifiedCode {
9761+
/// Customer Error - Issue with payment method details
9762+
UE_1000,
9763+
/// Connector Declines - Issue with Configurations
9764+
UE_2000,
9765+
/// Connector Error - Technical issue with PSP
9766+
UE_3000,
9767+
/// Integration Error - Issue in the integration
9768+
UE_4000,
9769+
/// Others - Something went wrong
9770+
UE_9000,
9771+
}
9772+
97439773
#[derive(
97449774
Clone,
97459775
Debug,

0 commit comments

Comments
 (0)