Skip to main content

Payment Configuration

The Hubble SDK supports UPI and card payments. Most payment flows work automatically, but native mobile apps require some configuration for UPI payments to work correctly.

Web-Only Integrations

If you are integrating the SDK as a web iframe only (not a native mobile app), you can skip this section. Payment configuration is only required for native iOS and Android apps.

iOS UPI Configuration​

The iOS Limitation​

iOS restricts apps from checking which other apps are installed on the device. This is a privacy feature. However, for UPI payments to work, the SDK needs to know which UPI apps (PhonePe, GPay, Paytm, etc.) are available so it can show the correct payment options.

Passing Installed UPI Apps​

To enable UPI payments in your iOS app, you need to declare the UPI app URL schemes in your Info.plist. This allows your app to query which UPI apps are installed.

Add the following to your Info.plist:

Info.plist
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>phonepe</string>
  <string>tez</string>
  <string>paytmmp</string>
  <string>cred</string>
  <string>bhim</string>
</array>

Why This Matters​

Without these URL schemes declared, iOS will not allow your app to check for installed UPI apps. The SDK will fall back to showing a generic "Pay via UPI" option, which may open the wrong app or fail entirely. With the schemes declared, the SDK can show specific buttons for each installed UPI app, providing a smoother payment experience.

iOS WebView Background Behavior​

When a user taps a UPI app to complete payment, your app goes to the background and the UPI app opens. iOS may suspend your app's WebView while it is in the background, which can pause JavaScript execution.

When the user returns to your app after completing the payment, the WebView may have been suspended. JavaScript timers, network requests, and state updates may not have executed as expected.

Handling iOS Background Resumption

Listen for the applicationDidBecomeActive notification in your app. When your app becomes active again after a UPI payment, you may need to refresh the WebView or call evaluateJavaScript to trigger a status check. The SDK handles most of this automatically, but if you see stale payment states, this is the likely cause.

Android Configuration​

For Android apps, add the following queries to your AndroidManifest.xml to detect UPI apps:

AndroidManifest.xml
<queries>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="upi" />
  </intent>
</queries>
Android WebView and UPI Intent

Android handles UPI payments through intents. For the WebView to open UPI apps, you need to ensure your WebView client properly handles intent:// URLs. The Android Integration Guide includes the necessary WebView configuration code.

Troubleshooting​

UPI Apps Not Appearing (iOS)​

  1. Verify the LSApplicationQueriesSchemes are added to your Info.plist
  2. Ensure you're using WKWebView (not SFSafariViewController)
  3. Rebuild your app after modifying Info.plist

UPI Apps Not Appearing (Android)​

  1. Verify the <queries> block is present in your AndroidManifest.xml
  2. Ensure your WebView is configured to handle external intents
  3. On Android 11+, the package visibility rules require the queries declaration

Payment Status Stuck (iOS)​

If the payment status screen appears stuck after returning from a UPI app:

  1. Implement applicationDidBecomeActive handling
  2. Reload the WebView or trigger a JavaScript status check
  3. The SDK should auto-recover within a few seconds