feat(connector): Introduce Connector Customer Flow and Optional Billing Address Support (#10499)

Author: awasthi21

crates/connector_configs/toml/development.toml

@@ -6998,6 +6998,8 @@ key1="Product Line Id"
   payment_method_type = "Mastercard"
 [[payload.debit]]
   payment_method_type = "Visa"
+[[payload.bank_debit]]
+payment_method_type = "ach"
 
 [payload.connector_auth.CurrencyAuthKey.auth_key_map.USD]
 processing_account_id = "processing_account_id"
@@ -7721,6 +7723,24 @@ options=["CRYPTOGRAM_3DS"]
 api_key="Username"
 api_secret="Password"
 key1="Account ID"
+[zift.metadata.acquirer_bin]
+name="acquirer_bin"
+label="Acquirer Bin"
+placeholder="Enter Acquirer Bin"
+required=false
+type="Text"
+[zift.metadata.acquirer_merchant_id]
+name="acquirer_merchant_id"
+label="Acquirer Merchant ID"
+placeholder="Enter Acquirer Merchant ID"
+required=false
+type="Text"
+[zift.metadata.acquirer_country_code]
+name="acquirer_country_code"
+label="Acquirer Country Code"
+placeholder="Enter Acquirer Country Code"
+required=false
+type="Text"
 
 [payjustnow]
 [payjustnow.connector_auth.BodyKey]

crates/connector_configs/toml/production.toml

@@ -5695,6 +5695,8 @@ payment_method_type = "Discover"
 payment_method_type = "Mastercard"
 [[payload.debit]]
 payment_method_type = "Visa"
+[[payload.bank_debit]]
+payment_method_type = "ach"
 
 [payload.connector_auth.CurrencyAuthKey.auth_key_map.USD]
 processing_account_id = "processing_account_id"
@@ -6456,6 +6458,24 @@ options=["CRYPTOGRAM_3DS"]
 api_key="Username"
 api_secret="Password"
 key1="Account ID"
+[zift.metadata.acquirer_bin]
+name="acquirer_bin"
+label="Acquirer Bin"
+placeholder="Enter Acquirer Bin"
+required=false
+type="Text"
+[zift.metadata.acquirer_merchant_id]
+name="acquirer_merchant_id"
+label="Acquirer Merchant ID"
+placeholder="Enter Acquirer Merchant ID"
+required=false
+type="Text"
+[zift.metadata.acquirer_country_code]
+name="acquirer_country_code"
+label="Acquirer Country Code"
+placeholder="Enter Acquirer Country Code"
+required=false
+type="Text"
 
 [payjustnow]
 [payjustnow.connector_auth.BodyKey]

crates/connector_configs/toml/sandbox.toml

@@ -6976,6 +6976,8 @@ payment_method_type = "Discover"
 payment_method_type = "Mastercard"
 [[payload.debit]]
 payment_method_type = "Visa"
+[[payload.bank_debit]]
+payment_method_type = "ach"
 
 [payload.connector_auth.CurrencyAuthKey.auth_key_map.USD]
 processing_account_id = "processing_account_id"
@@ -7694,6 +7696,24 @@ options=["CRYPTOGRAM_3DS"]
 api_key="Username"
 api_secret="Password"
 key1="Account ID"
+[zift.metadata.acquirer_bin]
+name="acquirer_bin"
+label="Acquirer Bin"
+placeholder="Enter Acquirer Bin"
+required=false
+type="Text"
+[zift.metadata.acquirer_merchant_id]
+name="acquirer_merchant_id"
+label="Acquirer Merchant ID"
+placeholder="Enter Acquirer Merchant ID"
+required=false
+type="Text"
+[zift.metadata.acquirer_country_code]
+name="acquirer_country_code"
+label="Acquirer Country Code"
+placeholder="Enter Acquirer Country Code"
+required=false
+type="Text"
 
 [payjustnow]
 [payjustnow.connector_auth.BodyKey]

crates/hyperswitch_connectors/src/connectors/payload.rs

@@ -20,21 +20,25 @@ use hyperswitch_domain_models::{
     router_data::{AccessToken, ConnectorAuthType, ErrorResponse, RouterData},
     router_flow_types::{
         access_token_auth::AccessTokenAuth,
-        payments::{Authorize, Capture, PSync, PaymentMethodToken, Session, SetupMandate, Void},
+        payments::{
+            Authorize, Capture, CreateConnectorCustomer, PSync, PaymentMethodToken, Session,
+            SetupMandate, Void,
+        },
         refunds::{Execute, RSync},
     },
     router_request_types::{
-        AccessTokenRequestData, PaymentMethodTokenizationData, PaymentsAuthorizeData,
-        PaymentsCancelData, PaymentsCaptureData, PaymentsSessionData, PaymentsSyncData,
-        RefundsData, SetupMandateRequestData,
+        AccessTokenRequestData, ConnectorCustomerData, PaymentMethodTokenizationData,
+        PaymentsAuthorizeData, PaymentsCancelData, PaymentsCaptureData, PaymentsSessionData,
+        PaymentsSyncData, RefundsData, SetupMandateRequestData,
     },
     router_response_types::{
         ConnectorInfo, PaymentMethodDetails, PaymentsResponseData, RefundsResponseData,
         SupportedPaymentMethods, SupportedPaymentMethodsExt,
     },
     types::{
-        PaymentsAuthorizeRouterData, PaymentsCancelRouterData, PaymentsCaptureRouterData,
-        PaymentsSyncRouterData, RefundSyncRouterData, RefundsRouterData, SetupMandateRouterData,
+        ConnectorCustomerRouterData, PaymentsAuthorizeRouterData, PaymentsCancelRouterData,
+        PaymentsCaptureRouterData, PaymentsSyncRouterData, RefundSyncRouterData, RefundsRouterData,
+        SetupMandateRouterData,
     },
 };
 use hyperswitch_interfaces::{
@@ -45,7 +49,7 @@ use hyperswitch_interfaces::{
     configs::Connectors,
     errors,
     events::connector_api_logs::ConnectorEvent,
-    types::{self, PaymentsVoidType, Response, SetupMandateType},
+    types::{self, ConnectorCustomerType, PaymentsVoidType, Response, SetupMandateType},
     webhooks,
 };
 use masking::{ExposeInterface, Mask};
@@ -78,6 +82,88 @@ impl api::Refund for Payload {}
 impl api::RefundExecute for Payload {}
 impl api::RefundSync for Payload {}
 impl api::PaymentToken for Payload {}
+impl api::ConnectorCustomer for Payload {}
+
+impl ConnectorIntegration<CreateConnectorCustomer, ConnectorCustomerData, PaymentsResponseData>
+    for Payload
+{
+    fn get_headers(
+        &self,
+        req: &ConnectorCustomerRouterData,
+        _connectors: &Connectors,
+    ) -> CustomResult<Vec<(String, masking::Maskable<String>)>, errors::ConnectorError> {
+        let mut header = vec![(
+            headers::CONTENT_TYPE.to_string(),
+            "application/json".to_string().into(),
+        )];
+        let mut api_key = self.get_auth_header(&req.connector_auth_type)?;
+        header.append(&mut api_key);
+        Ok(header)
+    }
+    fn get_url(
+        &self,
+        _req: &ConnectorCustomerRouterData,
+        connectors: &Connectors,
+    ) -> CustomResult<String, errors::ConnectorError> {
+        Ok(format!("{}/customers", self.base_url(connectors),))
+    }
+
+    fn get_request_body(
+        &self,
+        req: &ConnectorCustomerRouterData,
+        _connectors: &Connectors,
+    ) -> CustomResult<RequestContent, errors::ConnectorError> {
+        let connector_req = requests::CustomerRequest::try_from(req)?;
+        Ok(RequestContent::Json(Box::new(connector_req)))
+    }
+
+    fn build_request(
+        &self,
+        req: &ConnectorCustomerRouterData,
+        connectors: &Connectors,
+    ) -> CustomResult<Option<Request>, errors::ConnectorError> {
+        Ok(Some(
+            RequestBuilder::new()
+                .method(Method::Post)
+                .url(&ConnectorCustomerType::get_url(self, req, connectors)?)
+                .attach_default_headers()
+                .headers(ConnectorCustomerType::get_headers(self, req, connectors)?)
+                .set_body(ConnectorCustomerType::get_request_body(
+                    self, req, connectors,
+                )?)
+                .build(),
+        ))
+    }
+
+    fn handle_response(
+        &self,
+        data: &ConnectorCustomerRouterData,
+        event_builder: Option<&mut ConnectorEvent>,
+        res: Response,
+    ) -> CustomResult<ConnectorCustomerRouterData, errors::ConnectorError> {
+        let response: responses::CustomerResponse =
+            res.response
+                .parse_struct("CustomerResponse")
+                .change_context(errors::ConnectorError::ResponseDeserializationFailed)?;
+
+        event_builder.map(|i| i.set_response_body(&response));
+        router_env::logger::info!(connector_response=?response);
+
+        RouterData::try_from(ResponseRouterData {
+            response,
+            data: data.clone(),
+            http_code: res.status_code,
+        })
+    }
+
+    fn get_error_response(
+        &self,
+        res: Response,
+        event_builder: Option<&mut ConnectorEvent>,
+    ) -> CustomResult<ErrorResponse, errors::ConnectorError> {
+        self.build_error_response(res, event_builder)
+    }
+}
 
 impl ConnectorIntegration<PaymentMethodToken, PaymentMethodTokenizationData, PaymentsResponseData>
     for Payload
@@ -962,4 +1048,14 @@ impl ConnectorSpecifications for Payload {
     fn get_supported_webhook_flows(&self) -> Option<&'static [enums::EventClass]> {
         Some(&PAYLOAD_SUPPORTED_WEBHOOK_FLOWS)
     }
+    fn should_call_connector_customer(
+        &self,
+        payment_attempt: &hyperswitch_domain_models::payments::payment_attempt::PaymentAttempt,
+    ) -> bool {
+        #[cfg(feature = "v1")]
+        return payment_attempt.customer_acceptance.is_some()
+            && payment_attempt.setup_future_usage_applied == Some(enums::FutureUsage::OffSession);
+        #[cfg(feature = "v2")]
+        return false;
+    }
 }

crates/hyperswitch_connectors/src/connectors/payload/requests.rs

@@ -1,4 +1,4 @@
-use common_utils::types::StringMajorUnit;
+use common_utils::{pii::Email, types::StringMajorUnit};
 use masking::Secret;
 use serde::{Deserialize, Serialize};
 
@@ -26,15 +26,15 @@ pub enum TransactionTypes {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct BillingAddress {
     #[serde(rename = "payment_method[billing_address][city]")]
-    pub city: String,
+    pub city: Option<String>,
     #[serde(rename = "payment_method[billing_address][country_code]")]
-    pub country: common_enums::CountryAlpha2,
+    pub country: Option<common_enums::CountryAlpha2>,
     #[serde(rename = "payment_method[billing_address][postal_code]")]
     pub postal_code: Secret<String>,
     #[serde(rename = "payment_method[billing_address][state_province]")]
-    pub state_province: Secret<String>,
+    pub state_province: Option<Secret<String>>,
     #[serde(rename = "payment_method[billing_address][street_address]")]
-    pub street_address: Secret<String>,
+    pub street_address: Option<Secret<String>>,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -55,6 +55,15 @@ pub struct PayloadPaymentRequestData {
     /// This is true by default
     #[serde(rename = "payment_method[keep_active]")]
     pub keep_active: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub customer_id: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CustomerRequest {
+    pub keep_active: bool,
+    pub email: Email,
+    pub name: Secret<String>,
 }
 
 #[derive(Debug, Clone, Serialize, PartialEq)]

crates/hyperswitch_connectors/src/connectors/payload/responses.rs

@@ -48,7 +48,10 @@ pub struct PayloadCardsResponseData {
     #[serde(rename = "type")]
     pub response_type: Option<String>,
 }
-
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CustomerResponse {
+    pub id: String,
+}
 // Type definition for Refund Response
 // Added based on assumptions since this is not provided in the documentation
 #[derive(Debug, Copy, Serialize, Default, Deserialize, Clone)]