feat: superposition sdk/config consumption by Pradeep-kumar1202 · Pull Request #524 · juspay/hyperswitch-client-core

Pradeep-kumar1202 · 2026-06-01T16:08:40Z

Type of Change

Summary

The PML no longer decides which payment methods to show or which fields to collect. SDK now fetches a config for the payment and uses that as the source for both — what's eligible, and what to render.

New Contract

When the SDK loads, it fetches configuration once:

GET {baseUrl}/v1/sdk/configs/web/sdk_config.json

Headers: api-key + client-secret

For each payment method and connector, the configuration defines:

Which payment methods and connectors are eligible
The exact fields to collect
Field metadata, including:
- Render type
- Display order
- Labels and placeholders
- Validation rules
- Where values should be mapped in the confirm payload

What we do with it

Available everywhere — fetched once at startup and exposed through a context,so any screen reads the same config.

Eligibility

The configuration determines which payment method tiles are displayed.

If a payment method or connector is not present in the configuration, it is not rendered.
No fallback behavior exists.
No configuration → nothing renders.

Fields

For the selected payment method:

Resolve eligible connectors from the configuration.
Resolve the required fields.
Render fields dynamically.

Field handling includes:

Grouping related fields together (card details, name, phone, etc.)
Rendering inputs according to their declared render type:
- Card Number
- Expiry
- CVC
- Card Network
- Email
- First Name / Last Name
- Phone (+ Country Code)
- Date / Date of Birth
- Country
- State
- Dropdowns
- Crypto Currency / Network
Applying labels, placeholders, and validation rules directly from the configuration

Rendering Implementation

Each renderer (Card, Name, Phone, Crypto, Date, Generic) selects fields based on render type and handles layout accordingly.
Name fields are received as a first-name/last-name pair but rendered as a single "Full Name / Card Holder Name" input and split back into first and last names during submission.
Standalone phone fields without a country code render independently.
The legacy standalone address element has been removed. Address fields are now handled through grouped or generic renderers.

Screenshots / Recordings

Affected Area & Impact

Client Core
Shared Codebase
Android
iOS

Android PR / status (if any):
iOS PR / status (if any):
**Shared Codebase PR / status (if any):**juspay/hyperswitch-sdk-utils#68

Testing

JS bundle built
Tested in Android app
Tested in iOS app

Notes:

Checklist

Tested in consuming Android app
Tested in consuming iOS app

Pradeep-kumar1202 · 2026-06-04T10:07:50Z

@@ -0,0 +1,35 @@
+
+// will be checked where this logic should live
+let useGetSuperpositionRawConfigs = () => {


Move to shared-code

Pradeep-kumar1202 · 2026-06-04T10:09:39Z

 }

+let lookupLocaleString = (localeObject, key) =>
+  switch localeObject->Obj.magic->Dict.get(key) {


try removing the .magic and if not possible wrap it in try{} catch{}

Pradeep-kumar1202 · 2026-06-04T11:11:16Z

            let handleInputChange = (value: string) => {
-              let formattedValue = value //formatValue(value, phoneNumberConfig.fieldType)
-              phoneNumberInput.onChange(formattedValue)
+              phoneNumberInput.onChange(value)


for Phone-code and postal code for formatting there is a file

Noted as a TODO, Pick this up later

Pradeep-kumar1202 · 2026-06-16T06:16:15Z

-      | _ => ()
+      let isCountryDropdown =
+        (field.fieldRenderType === Dropdown || field.fieldRenderType === Country) &&
+          field.confirmRequestWritePath->String.endsWith(".country")


These many checks are not required

Pradeep-kumar1202 · 2026-06-16T06:20:23Z

+
+let isStateDropdown = (field: SuperpositionTypes.fieldConfig) =>
+  field.fieldRenderType === State ||
+    (field.fieldRenderType === Dropdown && field.confirmRequestWritePath->String.endsWith(".state"))


These many checks might not be required

sh-iv-am · 2026-06-16T19:56:50Z

-        ~config={validate: createFieldValidator(CardNetwork(enabledCardSchemes))},
+        cardNetworkPath,
+        ~config={
+          validate: ?(hasNetwork && enabledCardSchemes->Array.length > 0


Why not have a unified logic for check and render?

Done — extracted a useOptionalCardField(config, ~sentinel, ~validate) → (present, input, meta) hook that unifies the presence-check + real/sentinel path + conditional validator in one place.

The optional cvc and network fields now each resolve in a single call.

The render guard uses the returned present flag.

sh-iv-am · 2026-06-16T19:57:16Z

+  let cardExpiryMonthConfig = findField(SuperpositionTypes.CardExpiryMonth)
+  let cardExpiryYearConfig = findField(SuperpositionTypes.CardExpiryYear)
+  let cardCvcConfig = findField(SuperpositionTypes.Cvc)
+  let cardNetworkConfig = findField(SuperpositionTypes.CardNetwork)


Shouldn't fields controlled by priority?

Previously, the CardElement logic relied on the order and priority of fields in the array (for example, assuming fields[0] was card number, fields[1] was expiry month, etc.). This approach was fragile because any change in field priority ordering it fell through to | _ => React.null

To make the rendering logic more robust and independent of field ordering, we have extended fieldRenderType with dedicated values such as CardExpiryMonth, CardExpiryYear, and CardNetwork. CardElement and other Special UX components now identify and consume fields based on fieldRenderType rather than array position or priority. Since fieldRenderType is a stable, explicit, and non-changing identifier, this ensures the components receive the correct fields regardless of ordering changes.

sh-iv-am · 2026-06-16T20:00:14Z

Remove all logic based on confirmRequestWritePath

Pradeep-kumar1202 · 2026-06-17T06:15:47Z

Remove all logic based on confirmRequestWritePath

GenericTabElement.res

Deleted the isCountryDropdown, isStateDropdown, and isPhoneCodeDropdown helpers.
Switch guards are now plain | Country / | State.
Removed the phone-code arm entirely — PhoneCountryCode is routed to PhoneElement by FieldGrouper.classify, so that arm was dead.
language_preference now renders as a normal dropdown from its own dropdownOptions (dropped the includes("language_preference") label special-casing).

DynamicFieldsContext.res

Country-default seeding is now fieldRenderType === Country instead of ... && endsWith(".country").

manideepk90 · 2026-06-17T10:48:07Z

                  maxLength=Some(7)
                  borderTopWidth=?{splitCardFields ? None : Some(borderWidth /. 2.)}
-                  borderRightWidth=?{splitCardFields ? None : Some(borderWidth /. 2.)}
+                  borderRightWidth=?{splitCardFields


Why are we changing this borderWidth

Because CVC is now optional (driven by the resolved config). When CVC is present, the expiry field sits to its left in the same row and shares a half-width border (borderWidth /. 2.). When CVC is hidden (hasCvc = false), expiry becomes the right-most element, so it needs the full borderWidth on its right edge; otherwise, the row's outer border renders thin. Hence Some(hasCvc ? borderWidth /. 2. : borderWidth).

manideepk90 · 2026-06-17T10:48:48Z

                  }}
                </UIUtils.RenderIf>
              </View>
+               <UIUtils.RenderIf condition={hasCvc}>


What exactly are we doing here?
Are we rendering CVC based on the superposition

Yes — CVC is config-driven now. hasCvc = findField(Cvc)->Option.isSome, so it's true only when the resolved dynamic-fields (superposition) config includes the CVC field.

The card block used to assume all five sub-fields always exist; now the CVC and network fields are optional. The useField for CVC is still called unconditionally via a sentinel path (Rules of Hooks), and hasCvc only gates the visual render and its validator.

manideepk90 · 2026-06-17T10:53:01Z

+  React.useEffect1(() => {
+    let cancelled = ref(false)
+
+    setResult(_ => defaultSdkConfigValue)


Why are you setting back to the defaultSdkConfigValue?
on refetchKey changes it will be triggered, you are already using the initial state with the defaultSdkConfigValue

let (result, setResult) = React.useState(() => defaultSdkConfigValue)

this may leads to broken UI

Good catch — agreed. setResult(_ => defaultSdkConfigValue) at the top of the effect would blank the config on every refetch and cause a UI flash.

In the latest revision, i've removed this bespoke loader entirely. The config is now fetched the same way as PML (via NavigationRouter) and stored in AllApiDataContextNew as an option. During refetches, the previous config is retained until the new response arrives, so there's no reset-to-default state and no empty flash.

This file is deleted

manideepk90 · 2026-06-17T10:54:22Z

+        }
+        Promise.resolve()
+      })
+      ->Promise.catch(_ => {


@sh-iv-am should we add a retry or lets skip this time

manideepk90 · 2026-06-17T10:55:24Z

+        ~appId=nativeProp.sdkParams.appId,
+        (),
+      )
+      if clientSecret->String.length > 0 {


Can we fetch sdkAuth without Client-Secret?
@sh-iv-am @Pradeep-kumar1202

So, can we send a mesage client-secret is needed if not handled in the sdkTypes

ChiragKV-Juspay · 2026-06-17T15:06:50Z

+          if isValidConfig(parsed) {
+            setSdkConfigData(_ => Some(parsed))
+          } else {
+            handleSuccessFailure(~apiResStatus=PaymentConfirmTypes.defaultConfirmError, ())


Why are we using defaultConfirmError here? Its a get call no?

Let's mark this as a TODO

if its a small change can we not do this now? Is there a big change needed for this?

ChiragKV-Juspay · 2026-06-17T15:08:06Z

+  let apiLogWrapper = LoggerHook.useApiLogWrapper()
+  let baseUrl = GlobalHooks.useGetBaseUrl()()
+  () => {
+    let uri = `${baseUrl}/v1/sdk/configs/web/sdk_config.json`


is /web in the uri intentional?

Good Catch - it is not intensional it should be platform now it's modified

manideepk90 · 2026-06-18T06:23:59Z

UpdateIntentHook
Api in the Parallel with the accountPML, customerPML with the delayedPM

Pradeep-kumar1202 added the in progress label Jun 1, 2026

Pradeep-kumar1202 commented Jun 4, 2026

View reviewed changes

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from 8066300 to 7aefc01 Compare June 15, 2026 11:06

Pradeep-kumar1202 commented Jun 16, 2026

View reviewed changes

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from 0e1ae60 to 2490027 Compare June 16, 2026 17:14

sh-iv-am force-pushed the main branch from 2217fd4 to 290f87b Compare June 16, 2026 19:02

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch 3 times, most recently from 01ad827 to 262dc50 Compare June 16, 2026 19:16

sh-iv-am reviewed Jun 16, 2026

View reviewed changes

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from 262dc50 to 65dd4e1 Compare June 17, 2026 06:15

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from 65dd4e1 to 972e31a Compare June 17, 2026 06:19

manideepk90 reviewed Jun 17, 2026

View reviewed changes

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch 2 times, most recently from c96dba3 to e3c58ca Compare June 17, 2026 14:09

ChiragKV-Juspay reviewed Jun 17, 2026

View reviewed changes

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch 2 times, most recently from 9d0af72 to ff6bb00 Compare June 18, 2026 05:51

manideepk90 previously approved these changes Jun 18, 2026

View reviewed changes

Pradeep-kumar1202 dismissed manideepk90’s stale review via 03549c3 June 18, 2026 06:38

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from ff6bb00 to 03549c3 Compare June 18, 2026 06:38

Pradeep-kumar1202 added 5 commits June 18, 2026 12:10

feat: consuming /sdk-configs for dynamic fields

c08c198

feat: superposition sdk/config consumption for dynamic_fields

967db41

feat: consuming /sdk-config api for superposition

047ff2c

feat: passing the billing data from flat dict to object

918ac82

feat: added a new type for the /sdk-config failure case

b783f85

Pradeep-kumar1202 force-pushed the superposition-sdk/config branch from 03549c3 to b783f85 Compare June 18, 2026 06:40

Pradeep-kumar1202 removed the in progress label Jun 18, 2026

ChiragKV-Juspay approved these changes Jun 18, 2026

View reviewed changes

manideepk90 approved these changes Jun 18, 2026

View reviewed changes

		@@ -0,0 +1,35 @@

		// will be checked where this logic should live
		let useGetSuperpositionRawConfigs = () => {

Conversation

Pradeep-kumar1202 commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Summary

New Contract

What we do with it

Eligibility

Fields

Rendering Implementation

Screenshots / Recordings

Affected Area & Impact

Testing

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sh-iv-am commented Jun 16, 2026

Uh oh!

Pradeep-kumar1202 commented Jun 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manideepk90 commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Pradeep-kumar1202 commented Jun 1, 2026 •

edited

Loading