---
title: Web SDKs FAQs
slug: sdks/web-sdks/faqs
excerpt: >-
  Pine Labs Web SDK questions for General and Flutter integrations, including
  setup, redirect URL handling, callback behavior, UPI intent flows, environment
  switching, and production-ready best practices.
hidden: false
sidebar_order: 6
sidebar_label: FAQs
metadata:
  title: 'Pine Labs Web SDK FAQs: General & Flutter Integration Guide'
  description: >-
    Comprehensive Pine Labs Web SDK FAQ for General and Flutter: integration
    prerequisites, redirect URL usage, callback handling, permissions, UPI
    app-switch behavior, UAT vs production setup, and secure backend
    verification best practices.
  keywords: >-
    Pine Labs Web SDK FAQ, Flutter payment SDK FAQ, redirect_url Pine Labs,
    onTransactionResponse, UPI intent flow Flutter, Pine Labs integration
    troubleshooting
---
<div className="pill-tabs">
<CodeTabs>
<Tab label="Android">
<br/>
<h2 class="pl-4">Android Web SDKs FAQs</h2>
<div className="p-4 faq-section">

<details>
<summary><b>1. What is the minimum merchant-side integration?</b></summary>
<br/>

Implement `EdgeResponseCallback`, create `EdgeManager`, and call:

```java
startPayment(activity, redirectUrl, callback);
```

</details>

---

<details>
<summary><b>2. What is redirectUrl in this SDK flow?</b></summary>
<br/>

It is the checkout/redirect URL generated by your backend/payment-init API.

</details>

---

<details>
<summary><b>3. Is onTransactionResponse() equal to "payment success"?</b></summary>
<br/>

Treat it as "payment flow finished / return reached," not final settlement.

Best practice is to call the Transaction Status API from backend using token/order details to confirm final transaction state.

</details>

---

<details>
<summary><b>4. How should we handle cancel/back from user?</b></summary>
<br/>

Both are explicitly surfaced via callbacks after confirmation dialogs.

</details>

---

<details>
<summary><b>5. Does SDK support app-switch flows (UPI/deep link/intents)?</b></summary>
<br/>

Yes. It handles `intent:` and external schemes from WebView, opens target apps, and resumes flow when return URL is hit.

</details>

---

<details>
<summary><b>6. What Android permissions are required?</b></summary>
<br/>

Network access is required:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

</details>

---

<details>
<summary><b>7. Can we run multiple payment sessions in parallel?</b></summary>
<br/>

Not recommended. SDK uses a singleton callback/context holder, so overlapping sessions can conflict.

</details>

---

<details>
<summary><b>8. What should we do on no internet before/after launch?</b></summary>
<br/>

`startPayment` already checks connectivity and returns `onInternetNotAvailable(...)`.

Merchants should show a retry CTA and avoid creating duplicate orders unnecessarily.

</details>

---

<details>
<summary><b>9. What is a good merchant-side success/failure pattern?</b></summary>
<br/>

1. Start payment via SDK.
2. Receive callback (transaction/cancel/error/back).
3. Call Transaction Status API from backend.
4. Show final status from inquiry (success/pending/failure), not just SDK callback.

</details>

</div>

  </Tab>


<Tab label="iOS">

<br/>
<h2 class="pl-4">iOS Web SDK FAQs</h2>

<div className="p-4 faq-section">
  <details>
    <summary><b>1. What iOS versions and Swift versions are supported?</b></summary>

    <br/>

    The SDK requires:

    - **iOS 16+**
    - **Xcode 15+**
    - **Swift 5**

    Apps written in Swift 4 or later and Objective-C are supported.

    </details>

    ---

  

    <details>
    <summary><b>2. After adding the SDK, the import Pine Labs Online is not coming up automatically.</b></summary>

    <br/>

    To resolve this issue:

    - Make sure that you see the framework under your app target **Frameworks, Libraries and Embedded Content**
    - Make sure that it is in **Embed and Sign**
    - If issue still persists, clean the build and build again

    </details>

    ---

    <details>
    <summary><b>3. My project fails to build after adding the SDK. What could be wrong?</b></summary>

    <br/>

    Common causes include:

    - Unsupported Swift version (must be Swift 5+)
    - Incompatible iOS deployment target
    - Outdated dependency manager setup (SPM)

    Verify that your project meets all SDK prerequisites.

    </details>

    ---

    <details>
    <summary><b>4. Does the SDK work with both UIKit and SwiftUI apps?</b></summary>

    <br/>

    Yes. The SDK can be integrated into UIKit-based apps and SwiftUI apps, provided the app meets the required iOS and Swift versions.

    </details>


    ---

    <details>
    <summary><b>6. Can I test the SDK entirely on the simulator?</b></summary>

    <br/>

    Basic testing for most of the pay modes is possible except the UPI Intent flow, but end-to-end payment testing should be done on a real device to avoid simulator-specific network and security issues.

    </details>

    ---

    <details>
    <summary><b>7. Can API keys be stored directly in the iOS app?</b></summary>

    <br/>

    **No.** API keys must be generated and passed securely from your backend. Hardcoding keys in the app is not recommended.

    </details>

    ---

    <details>
    <summary><b>8. My app is written in `Swift 4`. Can I integrate the SDK?</b></summary>

    <br/>

    **Yes.** Apps written in Swift 4 or later can integrate the SDK as long as they are built using a Swift 5–compatible Xcode version (Xcode 15+) and target iOS 16 or above.

    The SDK is distributed as a compiled XCFramework built with Swift 5, which is ABI-stable and backward compatible with Swift 4 source code.

    </details>

    ---

    <details>
    <summary><b>9. My app is written in `Swift 3`. Can I integrate the SDK?</b></summary>

    <br/>

    **No.** Apps written in Swift 3 or earlier are not supported.

    Reasons:

    - Swift 3 does not support Swift 5 ABI stability
    - Older Xcode versions cannot build iOS 16 apps
    - Apple no longer supports these toolchains

    **FIX:** Migration to Swift 5 and a modern Xcode version is required.

    </details>

    ---

    <details>
    <summary><b>10. Why does the SDK require `iOS 16` or above?</b></summary>

    <br/>

    Because the SDK depends on:

    - Modern WebKit and networking APIs
    - Updated security & TLS requirements
    - Apple-mandated platform security standards

    Apps targeting older iOS versions are increasingly restricted by Apple and App Store policies.

    </details>
</div>
</Tab>

  <Tab label="Flutter">

<br/>
<h2 class="pl-4">Flutter Web SDKs FAQs</h2>
<div className="p-4 faq-section">
<details>
<summary><b>1. What Flutter and Dart versions are required?</b></summary>

<br/>

The SDK requires Flutter 3.24.0+ and Dart 3.9.2+. Run `flutter --version` to check your current version. If you need to upgrade, run `flutter upgrade`.

</details>

---

<details>
<summary><b>2. The payment WebView shows a blank white screen. What should I check?</b></summary>

<br/>

The URL you are passing is a valid https:// URL.

The order token has not expired (tokens are usually valid for a limited time).

The device has an active internet connection.

You created the order in the correct environment (UAT order token will not work in Production and vice versa).

</details>

---

<details>
<summary><b>3. UPI apps are not opening from the payment screen. Why?</b></summary>

<br/>

On iOS: Make sure you have added all required LSApplicationQueriesSchemes entries in your Info.plist (see Section 2.3). Without these entries, iOS will block the SDK from launching UPI apps.

On Android: The SDK already includes the required `<queries>` entries for common UPI schemes. If a specific app is not launching, ensure the app is installed on the device. UPI intent flows do not work on emulators/simulators.

</details>

---

<details>
<summary><b>4. I get a PaymentStatus.invalidRequest result without the WebView opening. Why?</b></summary>

<br/>

This means the URL you passed failed validation. The SDK checks that:

- `paymentUrl` must be a valid http or https URL with a host.
- `successUrl` and `failureUrl` must be valid absolute URLs.
- None of the URL fields can be empty or blank.

Double-check the URLs you are passing. The `result.message` field will describe what was wrong.

</details>

---

<details>
<summary><b>5. The SDK returns cancelled status even though I did not cancel the payment. Why?</b></summary>

<br/>

The SDK returns cancelled when:

- The user presses the system back button (Android) or swipes back (iOS).
- The WebView is dismissed without reaching a success or failure callback URL.

If this happens unexpectedly, check whether the payment gateway is redirecting to the correct callback URL after payment completion.

</details>

---

<details>
<summary><b>6. Can I test UPI payments on a simulator or emulator?</b></summary>

<br/>

No. UPI intent flows require real payment apps installed on a physical device. The simulator/emulator does not have these apps. For UPI testing, always use a physical device.

Card payments, netbanking, and wallet flows work fine on simulators since they operate entirely within the WebView.

</details>

---

<details>
<summary><b>7. My Android minSdk is lower than 26. Can I still use the SDK?</b></summary>

<br/>

No. The SDK requires minSdk 26 (Android 8.0). If your app currently supports a lower version, you will need to raise it to 26 in your `android/app/build.gradle.kts`:

```kotlin
defaultConfig {
    minSdk = 26
}
```

Apps targeting Android 7 and below will fail to compile with the SDK.

</details>

---

<details>
<summary><b>8. Do I need to handle the WebView lifecycle manually?</b></summary>

<br/>

No. The SDK manages the entire WebView lifecycle internally, including:

* Creating and destroying the WebView
* Handling app background/foreground transitions during UPI app switches
* Closing the WebView when the payment flow completes
* Clearing the WebView cache on disposal

</details>

---

<details>
<summary><b>9. How do I switch between UAT and Production environments?</b></summary>

<br/>

The environment is determined by the `redirect_url` returned from the Create Hosted Checkout API:

**UAT:** Create orders using `https://pluraluat.v2.pinepg.in/api/checkout/v1/orders`

**Production:** Create orders using `https://plural.v2.pinepg.in/api/checkout/v1/orders`

The SDK does not have a separate environment toggle. It simply loads the URL you give it.

**Important:** UAT order tokens will not work with Production URLs and vice versa. Always ensure the order environment matches the API endpoint used.

</details>

---

<details>
<summary><b>10. Should I store API keys (client_id, client_secret) in my Flutter app?</b></summary>

<br/>

No. API keys must be stored securely on your backend server. Your Flutter app should call your own backend to create orders and obtain the `redirect_url`. Never hardcode or bundle API credentials in client-side code.

</details>

---

<details>
<summary><b>11. The payment succeeded on the gateway but the SDK returned failure. What happened?</b></summary>

<br/>

This can happen if the gateway redirected to an unexpected URL that the SDK did not recognise as a success callback. To handle this:

* Always verify the final payment status on your backend using the Order Inquiry API with the order ID.
* Do not rely solely on the client-side SDK result for order fulfilment.

</details>

---

<details>
<summary><b>12. I see a TLS error in the WebView during 3DS authentication. Is this a problem?</b></summary>

<br/>

During card payment 3DS flows, the WebView may navigate to bank authentication pages that have different SSL certificates. The SDK does not bypass SSL validation for security reasons. If you see TLS errors:

* They are usually transient and caused by the bank's authentication server.
* The SDK will continue monitoring and handle the callback once the flow completes.
* If the error persists, the payment gateway will typically time out and redirect to the failure URL.

</details>
</div>
  </Tab>

<Tab label="React Native">

<br/>
<h2 class="pl-4">React Native Web SDKs FAQs</h2>

<div className="p-4 faq-section">
<details>
<summary><b>1. What platforms are supported?</b></summary>

<br/>

React Native apps on Android and iOS.

</details>

---

<details>
<summary><b>2. What dependencies are required?</b></summary>

<br/>

Install the SDK plus `react-native-webview`.

Keep `react-native-webview` within the supported range: `11.23.0` up to (but not including) `14`.

</details>

---

<details>
<summary><b>3. Is there any iOS post-installation step required?</b></summary>

<br/>

Yes. Run `pod install` after adding or updating native dependencies.

</details>

---

<details>
<summary><b>4. What is the recommended checkout flow?</b></summary>

<br/>

1. Create the order on the backend.
2. Generate the checkout redirect URL on the backend.
3. Open the checkout screen by passing the redirect URL.
4. Receive the callback.
5. Confirm the final transaction status using the backend enquiry API.

</details>

---

<details>
<summary><b>5. Can the redirect URL be generated within the app?</b></summary>

<br/>

No. Redirect URL generation should remain server-side for each transaction.

</details>

---

<details>
<summary><b>6. What is the difference between response and error callback statuses?</b></summary>

<br/>

**Response** means a redirect pattern was detected, including error redirect URLs.

**Error** means SDK or WebView-level issues, such as:

- Page load failure
- No installed app available for a custom scheme

</details>

---

<details>
<summary><b>7. How are UPI and app-switch links handled?</b></summary>

<br/>

Non-http(s) URLs are opened through OS linking.

If no compatible app is installed, you receive an error callback.

</details>

---

<details>
<summary><b>8. Why should I still call the backend enquiry API after receiving a callback?</b></summary>

<br/>

The callback only indicates redirect or error signals from the client flow.

The backend status is the source of truth for settlement and the final order state.

</details>

---

<details>
<summary><b>9. What are the most common installation issues?</b></summary>

<br/>

Common installation issues include:

- Dependency mismatches, especially the supported `react-native-webview` version range
- Missing `pod install` execution on iOS after adding or updating dependencies

</details>
</div>
</Tab>
  
</CodeTabs>
</div>