feat: hs external vault flow and return user support (#1643)

Author: sakksham7

.env

@@ -7,4 +7,5 @@ SDK_TAG_VERSION=""
 SENTRY_DSN=""
 VISA_API_KEY_ID=""
 VISA_API_CERTIFICATE_PEM=""
-PORT= 9050
+IS_PCI_COMPLIANT=""
+PORT= 9050

src/CardCVCElement.res

@@ -1,15 +1,30 @@
 open RecoilAtoms
 open Utils
 
+// `isVaultCvcFlow` reuses this CVC element for the Hyperswitch-vault saved-card
+// (return user) flow. The single submit handler below has two mutually-exclusive
+// paths:
+//   • default (Elements CVC widget): listens for `requestCVCConfirm` and confirms
+//     the payment-session intent itself with the entered CVC.
+//   • vault saved-card flow: listens for the forwarded doSubmit, tokenises the CVC
+//     through the payment-method-session update call, and posts `savedCardCvcTokenEvent`
+//     back to SavedMethods, which owns the confirm (mirrors the VGS saved-card flow).
 @react.component
-let make = (~cvcProps: CardUtils.cvcProps, ~paymentType: CardThemeType.mode) => {
+let make = (
+  ~cvcProps: CardUtils.cvcProps,
+  ~paymentType: CardThemeType.mode,
+  ~isVaultCvcFlow=false,
+) => {
   let {config, localeString} = Recoil.useRecoilValueFromAtom(configAtom)
   let emitter = SubscriptionEventHooks.useSubscriptionEventEmitter()
   let {innerLayout} = config.appearance
   let keys = Recoil.useRecoilValueFromAtom(keys)
   let customPodUri = Recoil.useRecoilValueFromAtom(customPodUri)
   let loggerState = Recoil.useRecoilValueFromAtom(loggerAtom)
   let redirectionFlags = Recoil.useRecoilValueFromAtom(RecoilAtoms.redirectionFlagsAtom)
+  // Vault credentials (pmSessionId / sdkAuthorization) for the saved-card tokenise
+  // call; populated by PaymentMethodsSDK in the inner iframe. Only used in vault mode.
+  let vaultCredentials = Recoil.useRecoilValueFromAtom(RecoilAtoms.vaultCredentials)
 
   let {
     isCVCValid,
@@ -26,9 +41,67 @@ let make = (~cvcProps: CardUtils.cvcProps, ~paymentType: CardThemeType.mode) =>
   let compressedLayoutStyleForCvcError =
     innerLayout === Compressed && cvcError->String.length > 0 ? "!border-l-0" : ""
 
-  React.useEffect(() => {
+  // Single submit handler for both modes (mutually exclusive on `isVaultCvcFlow`):
+  //   • vault saved-card flow: SavedMethods forwards the validated doSubmit (carrying
+  //     the selected card's payment_token); we tokenise the CVC via the
+  //     payment-method-session update call and post the token back as
+  //     `savedCardCvcTokenEvent`. SavedMethods builds the vault_card_token_data confirm
+  //     body and calls intent. Validation / tokenisation failures post a failed-submit
+  //     response, which SavedMethods forwards to Hyper.res to reject confirmPayment().
+  //   • Elements CVC widget: confirms the payment-session intent itself on the
+  //     `requestCVCConfirm` message, posting the response back to the parent window.
+  let submitCallback = React.useCallback((ev: Window.event) => {
     open Promise
-    let handleRequestCVCConfirm = (ev: Window.event) => {
+    if isVaultCvcFlow {
+      let confirmDict = ev.data->safeParse->getDictFromJson
+      let confirm = confirmDict->ConfirmType.itemToObjMapper
+      let isOuterValid = confirmDict->getBool("isOuterValid", true)
+
+      if confirm.doSubmit {
+        let paymentMethodToken = confirmDict->getString("paymentToken", "")
+        let (pmSessionId, sdkAuthorization) = switch vaultCredentials {
+        | HyperswitchVault(creds) => (creds.pmSessionId, creds.sdkAuthorization)
+        | _ => ("", "")
+        }
+        let isCvcComplete = cvcNumber->String.length >= 3
+
+        if isCvcComplete && isOuterValid {
+          setCvcError(_ => "")
+          PaymentHelpersV2.updatePaymentMethod(
+            ~bodyArr=PaymentManagementBody.vaultUpdateCVVBody(~cvcNumber),
+            ~pmSessionId,
+            ~logger=loggerState,
+            ~customPodUri,
+            ~sdkAuthorization,
+          )
+          ->then(res => {
+            let vaultTokenData = VaultHelpers.decodeVaultTokenData(res)
+            if vaultTokenData.token !== "" {
+              messageParentWindow([
+                ("savedCardCvcTokenEvent", true->JSON.Encode.bool),
+                ("cvcToken", vaultTokenData.token->JSON.Encode.string),
+              ])
+            } else {
+              postFailedSubmitResponse(~errortype="server_error", ~message="Something went wrong")
+            }
+            resolve()
+          })
+          ->catch(_ => {
+            postFailedSubmitResponse(~errortype="server_error", ~message="Something went wrong")
+            resolve()
+          })
+          ->ignore
+        } else if isOuterValid {
+          // Only the CVC is invalid/empty (outer fields are validated upstream).
+          let errorMsg =
+            cvcNumber->String.length == 0
+              ? localeString.cvcNumberEmptyText
+              : localeString.inCompleteCVCErrorText
+          setCvcError(_ => errorMsg)
+          postFailedSubmitResponse(~errortype="validation_error", ~message=errorMsg)
+        }
+      }
+    } else {
       let json = ev.data->safeParse
       try {
         let dict = json->getDictFromJson
@@ -127,13 +200,18 @@ let make = (~cvcProps: CardUtils.cvcProps, ~paymentType: CardThemeType.mode) =>
         ])
       }
     }
-    Window.addEventListener("message", handleRequestCVCConfirm)
-    Some(
-      () => {
-        Window.removeEventListener("message", handleRequestCVCConfirm)
-      },
-    )
-  }, (cvcNumber, keys, paymentType, loggerState, customPodUri, redirectionFlags, localeString))
+  }, (
+    isVaultCvcFlow,
+    cvcNumber,
+    keys,
+    paymentType,
+    loggerState,
+    customPodUri,
+    redirectionFlags,
+    localeString,
+    vaultCredentials,
+  ))
+  useSubmitPaymentData(submitCallback)
 
   React.useEffect(() => {
     SubscriptionEventHooks.emitReady(
@@ -144,18 +222,19 @@ let make = (~cvcProps: CardUtils.cvcProps, ~paymentType: CardThemeType.mode) =>
   }, (keys.iframeId, paymentType))
 
   React.useEffect(() => {
-    let cvcInfoDict = [("isCvcEmpty", isCvcEmpty->JSON.Encode.bool)]->Dict.fromArray
-    Utils.messageParentWindow([("cvcInfo", cvcInfoDict->JSON.Encode.object)])
+    if !isVaultCvcFlow {
+      let cvcInfoDict = [("isCvcEmpty", isCvcEmpty->JSON.Encode.bool)]->Dict.fromArray
+      Utils.messageParentWindow([("cvcInfo", cvcInfoDict->JSON.Encode.object)])
+    }
     None
   }, [isCvcEmpty])
-
   React.useEffect(() => {
     emitter.emitCvcStatus(~iframeId=keys.iframeId, ~isCvcEmpty, ~isCvcComplete)
     None
   }, (isCvcEmpty, isCvcComplete, keys.iframeId))
 
   <PaymentInputField
-    fieldName=localeString.cvcTextLabel
+    fieldName={isVaultCvcFlow ? "" : localeString.cvcTextLabel}
     isValid=isCVCValid
     setIsValid=setIsCVCValid
     value=cvcNumber
@@ -167,6 +246,7 @@ let make = (~cvcProps: CardUtils.cvcProps, ~paymentType: CardThemeType.mode) =>
     maxLength=4
     inputRef=cvcRef
     placeholder="123"
+    height={isVaultCvcFlow ? "1.8rem" : ""}
     name=TestUtils.cardCVVInputTestId
     autocomplete="cc-csc"
   />

src/Components/SavedCardItem.res

@@ -62,11 +62,12 @@ let make = (
   ~installmentsError,
   ~setInstallmentsError,
   ~eligibilitySurchargeDetails: option<EligibilityHelpers.eligibilitySurchargeDetails>,
-  // VGS saved-card (return user) flow: when true, this card's CVC is collected
-  // inside the nested iframe (ParentCardComponent saved-card mode) instead of the
-  // plain input. `setCvcIframeRef` lifts the iframe ref to SavedMethods, which
-  // owns submit. Defaults keep other call sites (e.g. ClickToPayAuthenticate) intact.
-  ~isVgsCvcFlow=false,
+  // Vault saved-card (return user) flow (VGS or Hyperswitch): when true, this card's
+  // CVC is collected inside the nested iframe (ParentCardComponent saved-card mode)
+  // instead of the plain input. `setCvcIframeRef` lifts the iframe ref to
+  // SavedMethods, which owns submit. Defaults keep other call sites
+  // (e.g. ClickToPayAuthenticate) intact.
+  ~isVaultCvcFlow=false,
   ~setCvcIframeRef=_ => (),
 ) => {
   let {themeObj, config, localeString} = Recoil.useRecoilValueFromAtom(RecoilAtoms.configAtom)
@@ -147,14 +148,14 @@ let make = (
   }, (isActive, paymentItem, country, state, pinCode, isCvcEmpty))
 
   React.useEffect(() => {
+    open CardUtils
     if isActive {
       // * Focus CVC
       focusCVC()
-
       // * Sending card expiry to handle cases where the card expires before the use date.
       `${expiryMonth}${String.substring(~start=2, ~end=4, expiryYear)}`
       ->CardValidations.formatCardExpiryNumber
-      ->CardUtils.emitExpiryDate
+      ->emitExpiryDate
     }
     None
   }, (isActive, paymentItem, country, state, pinCode))
@@ -219,7 +220,7 @@ let make = (
   // VGS saved-card flow renders the secure CVC iframe in place of the plain input;
   // ParentCardComponent (saved-card mode) hosts it and lifts its ref to SavedMethods.
   let makeCvcField = (~fieldName="", ~height="1.8rem", ~inputFieldClassName="flex justify-start") =>
-    isVgsCvcFlow
+    isVaultCvcFlow
       ? <ParentCardComponent
           isSavedCardFlow=true containerId=cvcIframeContainerId setExternalIframeRef=setCvcIframeRef
         />

src/Components/SavedMethods.res

@@ -111,12 +111,22 @@ let make = (
     () => VaultHelpers.getVaultCredentialsFromSessions(sessionToken),
     [sessionToken],
   )
-  let isVgsCvcFlow =
+  // Either vault (VGS or Hyperswitch) collects + tokenises the saved-card CVC inside
+  // the nested iframe (ParentCardComponent saved-card mode); SavedMethods stays the
+  // submit owner. The vault provider only changes what renders inside that iframe —
+  // SavedMethods' forward-doSubmit / await-token / confirm logic is identical — so a
+  // single flag covers both.
+  let isVaultCvcFlow =
     isTokenize &&
     switch vaultCredentials {
-    | VGS(_) => true
-    | _ => false
+    | VGS(_) | HyperswitchVault(_) => true
+    | NoVault => false
     }
+
+  let isHyperswitchVault = switch vaultCredentials {
+  | HyperswitchVault(_) => true
+  | _ => false
+  }
   let cvcIframeRef = React.useRef(Nullable.null)
   let setCvcIframeRef = React.useCallback(ref => {
     cvcIframeRef.current = ref
@@ -152,7 +162,7 @@ let make = (
           eligibilitySurchargeDetails={paymentTokenVal == obj.paymentToken
             ? eligibilitySurchargeDetails
             : None}
-          isVgsCvcFlow
+          isVaultCvcFlow
           setCvcIframeRef
         />
       )
@@ -189,7 +199,7 @@ let make = (
   }
   // VGS collects + validates the CVC inside the iframe, so the outer plain-CVC
   // "empty" signal is not meaningful — treat it as filled.
-  let empty = isVgsCvcFlow ? false : cvcNumber == ""
+  let empty = isVaultCvcFlow ? false : cvcNumber == ""
   let customerMethod = React.useMemo(_ =>
     savedMethods
     ->Array.concat(customerMethods)
@@ -203,7 +213,9 @@ let make = (
   // submit), so outer validity does not depend on the plain CVC field — mirroring
   // how the new-card flow lets the inner iframe gate the card fields.
   let isCardPaymentMethodValid =
-    isVgsCvcFlow && isCardPaymentMethod ? true : !customerMethod.requiresCvv || (complete && !empty)
+    isVaultCvcFlow && isCardPaymentMethod
+      ? true
+      : !customerMethod.requiresCvv || (complete && !empty)
   let isInstallmentValid = !showInstallments || selectedInstallmentPlan->Option.isSome
 
   let shouldDoEligibility = paymentMethodListValue.sdk_next_action === Some("eligibility_check")
@@ -467,25 +479,38 @@ let make = (
             )
           }
         | _ =>
-          if isVgsCvcFlow && customerMethod.paymentMethod === "card" && customerMethod.requiresCvv {
-            // VGS saved-card flow: forward the validated doSubmit to the CVC iframe.
-            // It tokenises the CVC and posts `vgsSavedCardCvcTokenEvent` back; we
-            // then confirm with the vault_card_token_data body (otherwise identical
-            // to the plain saved-card confirm — same business-logic merge).
+          if (
+            isVaultCvcFlow && customerMethod.paymentMethod === "card" && customerMethod.requiresCvv
+          ) {
+            // Vault saved-card flow (VGS or Hyperswitch): forward the validated
+            // doSubmit to the CVC iframe. It tokenises the CVC and posts
+            // `savedCardCvcTokenEvent` back; we then confirm with the
+            // vault_card_token_data body (otherwise identical to the plain saved-card
+            // confirm — same business-logic merge). The Hyperswitch tokeniser needs
+            // the selected card's payment_token, so forward it in the message.
             let innerMsg = json->getDictFromJson
             innerMsg->Dict.set("isOuterValid", true->JSON.Encode.bool)
+            innerMsg->Dict.set("paymentToken", paymentTokenVal->JSON.Encode.string)
             cvcIframeRef.current->Window.iframePostMessage(innerMsg)
             let handle = (ev: Types.event) => {
               let dict = ev.data->Identity.anyTypeToJson->getDictFromJson
-              if dict->Dict.get("vgsSavedCardCvcTokenEvent")->Option.isSome {
+              if dict->Dict.get("savedCardCvcTokenEvent")->Option.isSome {
                 let cvcToken = dict->getString("cvcToken", "")
-                let vaultBody =
-                  PaymentBody.savedCardVaultCvcBody(
-                    ~paymentToken=paymentTokenVal,
-                    ~customerId,
-                    ~cvcToken,
-                    ~isCustomerAcceptanceRequired,
-                  )->Array.concat(installmentBody)
+                let cvcConfirmBody =
+                  isHyperswitchVault && GlobalVars.isPciCompliant
+                    ? PaymentBody.savedCardVaultCvcBody(
+                        ~paymentToken=paymentTokenVal,
+                        ~customerId,
+                        ~cvcToken,
+                        ~isCustomerAcceptanceRequired,
+                      )
+                    : PaymentBody.externalSavedCardVaultCvcBody(
+                        ~paymentToken=paymentTokenVal,
+                        ~customerId,
+                        ~cvcToken,
+                        ~isCustomerAcceptanceRequired,
+                      )
+                let vaultBody = cvcConfirmBody->Array.concat(installmentBody)
                 intent(
                   ~bodyArr=vaultBody->mergeAndFlattenToTuples(requiredFieldsBody),
                   ~confirmParam=confirm.confirmParams,
@@ -552,7 +577,8 @@ let make = (
     showInstallments,
     sdkAuthorization,
     isEligibilityPending,
-    isVgsCvcFlow,
+    isHyperswitchVault,
+    isVaultCvcFlow,
     paymentTokenVal,
     customerId,
   ))

src/GlobalVars.res

@@ -15,3 +15,4 @@ let targetOrigin: string = "*"
 @val external isSandbox: bool = "isSandboxEnv"
 @val external isProd: bool = "isProductionEnv"
 @val external isLocal: bool = "isLocal"
+@val external isPciCompliant: bool = "isPciCompliant"

src/LoaderController.res

@@ -456,6 +456,10 @@ let make = (~children, ~paymentMode, ~setIntegrateErrorError, ~logger, ~initTime
         // PaymentMethodsSDK reads this atom to render only the vault CVC field.
         if dict->Dict.get("isSavedCardCvcFlow")->Option.isSome {
           setIsSavedCardCvcFlow(_ => dict->Utils.getBool("isSavedCardCvcFlow", false))
+          switch dict->getString("endpoint", "") {
+          | "" => ()
+          | endpoint => ApiEndpoint.setApiEndPoint(endpoint)
+          }
         }
         if dict->getDictIsSome("sessions") {
           setSessions(_ => Loaded(dict->getJsonObjectFromDict("sessions")))

src/Payments/CardsSDK.res

@@ -21,11 +21,12 @@ let make = (~cvcOnly=false) => {
 
   switch vaultCredentials {
   | HyperswitchVault(_) =>
-    // TODO: render a Hyperswitch-vault CVC-only component for the saved-card flow.
-    // Until then, don't fall back to a full card form in the CVC-only slot.
-    <RenderIf condition={!cvcOnly}>
-      <CardPayment cardProps expiryProps cvcProps isInsideCardSDK=true />
-    </RenderIf>
+    // Saved-card (return user) flow renders the CVC-only widget, which tokenises the
+    // CVC via the payment-method-session update call; the new-card flow renders the
+    // full card form. CardCVCElement is reused here in its vault-tokenise mode.
+    cvcOnly
+      ? <CardCVCElement cvcProps paymentType=CardThemeType.CardCVCElement isVaultCvcFlow=true />
+      : <CardPayment cardProps expiryProps cvcProps isInsideCardSDK=true />
   | VGS(_) => <VGSVault cvcOnly />
   | NoVault =>
     // Vault details not yet loaded. For the new-card flow render the form so the