feat(router): add /relay endpoint (#6870)

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

api-reference/api-reference/relay/relay--retrieve.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec get /relay/{relay_id}
+---

api-reference/api-reference/relay/relay.mdx

@@ -0,0 +1,3 @@
+---
+openapi: openapi_spec post /relay
+---

api-reference/mint.json

@@ -234,6 +234,13 @@
         "api-reference/routing/routing--activate-config"
       ]
     },
+    {
+      "group": "Relay",
+      "pages": [
+        "api-reference/relay/relay",
+        "api-reference/relay/relay--retrieve"
+      ]
+    },
     {
       "group": "Schemas",
       "pages": ["api-reference/schemas/outgoing--webhook"]

api-reference/openapi_spec.json

@@ -950,6 +950,123 @@
         ]
       }
     },
+    "/relay": {
+      "post": {
+        "tags": [
+          "Relay"
+        ],
+        "summary": "Relay - Create",
+        "description": "Creates a relay request.",
+        "operationId": "Relay Request",
+        "parameters": [
+          {
+            "name": "X-Profile-Id",
+            "in": "header",
+            "description": "Profile ID for authentication",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "X-Idempotency-Key",
+            "in": "header",
+            "description": "Idempotency Key for relay request",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RelayRequest"
+              },
+              "examples": {
+                "Create a relay request": {
+                  "value": {
+                    "connector_id": "mca_5apGeP94tMts6rg3U3kR",
+                    "connector_resource_id": "7256228702616471803954",
+                    "data": {
+                      "amount": 6540,
+                      "currency": "USD"
+                    },
+                    "type": "refund"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Relay request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RelayResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid data"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/relay/{relay_id}": {
+      "get": {
+        "tags": [
+          "Relay"
+        ],
+        "summary": "Relay - Retrieve",
+        "description": "Retrieves a relay details.",
+        "operationId": "Retrieve a Relay details",
+        "parameters": [
+          {
+            "name": "X-Profile-Id",
+            "in": "header",
+            "description": "Profile ID for authentication",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Relay Retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RelayResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Relay details was not found"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          },
+          {
+            "ephemeral_key": []
+          }
+        ]
+      }
+    },
     "/refunds": {
       "post": {
         "tags": [
@@ -23093,6 +23210,161 @@
         },
         "additionalProperties": false
       },
+      "RelayData": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/RelayRefundRequest"
+          }
+        ]
+      },
+      "RelayError": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "The error code"
+          },
+          "message": {
+            "type": "string",
+            "description": "The error message"
+          }
+        }
+      },
+      "RelayRefundRequest": {
+        "type": "object",
+        "required": [
+          "amount",
+          "currency"
+        ],
+        "properties": {
+          "amount": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The amount that is being refunded",
+            "example": 6540
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          },
+          "reason": {
+            "type": "string",
+            "description": "The reason for the refund",
+            "example": "Customer returned the product",
+            "nullable": true,
+            "maxLength": 255
+          }
+        }
+      },
+      "RelayRequest": {
+        "type": "object",
+        "required": [
+          "connector_resource_id",
+          "connector_id",
+          "type"
+        ],
+        "properties": {
+          "connector_resource_id": {
+            "type": "string",
+            "description": "The identifier that is associated to a resource at the connector to which the relay request is being made",
+            "example": "7256228702616471803954"
+          },
+          "connector_id": {
+            "type": "string",
+            "description": "Identifier of the connector ( merchant connector account ) to which relay request is being made",
+            "example": "mca_5apGeP94tMts6rg3U3kR"
+          },
+          "type": {
+            "$ref": "#/components/schemas/RelayType"
+          },
+          "data": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RelayData"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
+      "RelayResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "status",
+          "connector_resource_id",
+          "connector_id",
+          "profile_id",
+          "type"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The unique identifier for the Relay",
+            "example": "relay_mbabizu24mvu3mela5njyhpit4"
+          },
+          "status": {
+            "$ref": "#/components/schemas/RelayStatus"
+          },
+          "connector_reference_id": {
+            "type": "string",
+            "description": "The reference identifier provided by the connector for the relay request",
+            "example": "pi_3MKEivSFNglxLpam0ZaL98q9",
+            "nullable": true
+          },
+          "error": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RelayError"
+              }
+            ],
+            "nullable": true
+          },
+          "connector_resource_id": {
+            "type": "string",
+            "description": "The identifier that is associated to a resource at the connector to which the relay request is being made",
+            "example": "7256228702616471803954"
+          },
+          "connector_id": {
+            "type": "string",
+            "description": "Identifier of the connector ( merchant connector account ) to which relay request is being made",
+            "example": "mca_5apGeP94tMts6rg3U3kR"
+          },
+          "profile_id": {
+            "type": "string",
+            "description": "The business profile that is associated with this relay request",
+            "example": "pro_abcdefghijklmnopqrstuvwxyz"
+          },
+          "type": {
+            "$ref": "#/components/schemas/RelayType"
+          },
+          "data": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RelayData"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
+      "RelayStatus": {
+        "type": "string",
+        "enum": [
+          "success",
+          "processing",
+          "failure"
+        ]
+      },
+      "RelayType": {
+        "type": "string",
+        "enum": [
+          "refund"
+        ]
+      },
       "RequestPaymentMethodTypes": {
         "type": "object",
         "required": [

crates/api_models/src/lib.rs

@@ -31,6 +31,7 @@ pub mod poll;
 #[cfg(feature = "recon")]
 pub mod recon;
 pub mod refunds;
+pub mod relay;
 pub mod routing;
 pub mod surcharge_decision_configs;
 pub mod user;

crates/api_models/src/relay.rs

@@ -0,0 +1,103 @@
+pub use common_utils::types::MinorUnit;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+
+use crate::enums;
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+pub struct RelayRequest {
+    /// The identifier that is associated to a resource at the connector to which the relay request is being made
+    #[schema(example = "7256228702616471803954")]
+    pub connector_resource_id: String,
+    /// Identifier of the connector ( merchant connector account ) to which relay request is being made
+    #[schema(example = "mca_5apGeP94tMts6rg3U3kR", value_type = String)]
+    pub connector_id: common_utils::id_type::MerchantConnectorAccountId,
+    /// The type of relay request
+    #[serde(rename = "type")]
+    pub relay_type: RelayType,
+    /// The data that is associated with the relay request
+    pub data: Option<RelayData>,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RelayType {
+    /// The relay request is for a refund
+    Refund,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case", untagged)]
+pub enum RelayData {
+    /// The data that is associated with a refund relay request
+    Refund(RelayRefundRequest),
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+pub struct RelayRefundRequest {
+    /// The amount that is being refunded
+    #[schema(value_type = i64 , example = 6540)]
+    pub amount: MinorUnit,
+    /// The currency in which the amount is being refunded
+    #[schema(value_type = Currency)]
+    pub currency: enums::Currency,
+    /// The reason for the refund
+    #[schema(max_length = 255, example = "Customer returned the product")]
+    pub reason: Option<String>,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+pub struct RelayResponse {
+    /// The unique identifier for the Relay
+    #[schema(example = "relay_mbabizu24mvu3mela5njyhpit4", value_type = String)]
+    pub id: common_utils::id_type::RelayId,
+    /// The status of the relay request
+    pub status: RelayStatus,
+    /// The reference identifier provided by the connector for the relay request
+    #[schema(example = "pi_3MKEivSFNglxLpam0ZaL98q9")]
+    pub connector_reference_id: Option<String>,
+    /// The error details if the relay request failed
+    pub error: Option<RelayError>,
+    /// The identifier that is associated to a resource at the connector to which the relay request is being made
+    #[schema(example = "7256228702616471803954")]
+    pub connector_resource_id: String,
+    /// Identifier of the connector ( merchant connector account ) to which relay request is being made
+    #[schema(example = "mca_5apGeP94tMts6rg3U3kR", value_type = String)]
+    pub connector_id: common_utils::id_type::MerchantConnectorAccountId,
+    /// The business profile that is associated with this relay request
+    #[schema(example = "pro_abcdefghijklmnopqrstuvwxyz", value_type = String)]
+    pub profile_id: common_utils::id_type::ProfileId,
+    /// The type of relay request
+    #[serde(rename = "type")]
+    pub relay_type: RelayType,
+    /// The data that is associated with the relay request
+    pub data: Option<RelayData>,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RelayStatus {
+    /// The relay request is successful
+    Success,
+    /// The relay request is being processed
+    Processing,
+    /// The relay request has failed
+    Failure,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+pub struct RelayError {
+    /// The error code
+    pub code: String,
+    /// The error message
+    pub message: String,
+}
+
+#[derive(Debug, ToSchema, Clone, Deserialize, Serialize)]
+pub struct RelayRetrieveRequest {
+    /// The unique identifier for the Relay
+    #[serde(default)]
+    pub force_sync: bool,
+    /// The unique identifier for the Relay
+    pub id: String,
+}

crates/common_utils/src/id_type.rs

@@ -11,6 +11,7 @@ mod organization;
 mod payment;
 mod profile;
 mod refunds;
+mod relay;
 mod routing;
 mod tenant;
 
@@ -43,6 +44,7 @@ pub use self::{
     payment::{PaymentId, PaymentReferenceId},
     profile::ProfileId,
     refunds::RefundReferenceId,
+    relay::RelayId,
     routing::RoutingId,
     tenant::TenantId,
 };

crates/common_utils/src/id_type/relay.rs

@@ -0,0 +1,7 @@
+crate::id_type!(
+    RelayId,
+    "A type for relay_id that can be used for relay ids"
+);
+crate::impl_id_type_methods!(RelayId, "relay_id");
+
+crate::impl_debug_id_type!(RelayId);

crates/openapi/src/openapi.rs

@@ -84,6 +84,10 @@ Never share your secret api keys. Keep them guarded and secure.
         routes::payments::payments_complete_authorize,
         routes::payments::payments_post_session_tokens,
 
+        // Routes for relay
+        routes::relay,
+        routes::relay_retrieve,
+
         // Routes for refunds
         routes::refunds::refunds_create,
         routes::refunds::refunds_retrieve,
@@ -520,6 +524,13 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::payment_methods::PaymentMethodCollectLinkResponse,
         api_models::refunds::RefundListRequest,
         api_models::refunds::RefundListResponse,
+        api_models::relay::RelayRequest,
+        api_models::relay::RelayType,
+        api_models::relay::RelayData,
+        api_models::relay::RelayRefundRequest,
+        api_models::relay::RelayResponse,
+        api_models::relay::RelayStatus,
+        api_models::relay::RelayError,
         api_models::payments::AmountFilter,
         api_models::mandates::MandateRevokedResponse,
         api_models::mandates::MandateResponse,

crates/openapi/src/routes.rs

@@ -16,10 +16,11 @@ pub mod payouts;
 pub mod poll;
 pub mod profile;
 pub mod refunds;
+pub mod relay;
 pub mod routing;
 pub mod webhook_events;
 
 pub use self::{
     customers::*, mandates::*, merchant_account::*, merchant_connector_account::*, organization::*,
-    payment_method::*, payments::*, poll::*, refunds::*, routing::*, webhook_events::*,
+    payment_method::*, payments::*, poll::*, refunds::*, relay::*, routing::*, webhook_events::*,
 };

crates/openapi/src/routes/relay.rs

@@ -0,0 +1,57 @@
+/// Relay - Create
+///
+/// Creates a relay request.
+#[utoipa::path(
+    post,
+    path = "/relay",
+    request_body(
+        content = RelayRequest,
+        examples((
+            "Create a relay request" = (
+                value = json!({
+                    "connector_resource_id": "7256228702616471803954",
+                    "connector_id": "mca_5apGeP94tMts6rg3U3kR",
+                    "type": "refund",
+                    "data": {
+                        "amount": 6540,
+                        "currency": "USD"
+                    }
+                })
+            )
+        ))
+    ),
+    responses(
+        (status = 200, description = "Relay request", body = RelayResponse),
+        (status = 400, description = "Invalid data")
+    ),
+    params(
+        ("X-Profile-Id" = String, Header, description = "Profile ID for authentication"),
+        ("X-Idempotency-Key" = String, Header, description = "Idempotency Key for relay request")
+    ),
+    tag = "Relay",
+    operation_id = "Relay Request",
+    security(("api_key" = []))
+)]
+
+pub async fn relay() {}
+
+/// Relay - Retrieve
+///
+/// Retrieves a relay details.
+#[utoipa::path(
+    get,
+    path = "/relay/{relay_id}",
+    params (("id" = String, Path, description = "The unique identifier for the Relay")),
+    responses(
+        (status = 200, description = "Relay Retrieved", body = RelayResponse),
+        (status = 404, description = "Relay details was not found")
+    ),
+    params(
+        ("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
+    ),
+    tag = "Relay",
+    operation_id = "Retrieve a Relay details",
+    security(("api_key" = []), ("ephemeral_key" = []))
+)]
+
+pub async fn relay_retrieve() {}