pinelabs_web 1.0.0

Flutter plugin for fullscreen payment WebView flow with UPI intent handling and callback-based results.

pinelabs_web

pinelabs_web is a production-ready Flutter plugin that runs payment flows inside a fullscreen Flutter WebView, intercepts payment callback URLs, opens external UPI apps when required, and returns a typed PaymentResult.

Features

• Fullscreen payment WebView managed by the plugin
• URL interception and callback detection
• UPI intent/external scheme handling (upi://, intent://, phonepe://, gpay://, paytm://, and other custom schemes)
• Automatic success/failure result parsing
• Graceful user cancellation handling (back button)
• Android and iOS support with null-safe Dart API

Installation

Add this package to your app:

dependencies:
	pinelabs_web: ^1.0.0

Then run:

flutter pub get

Usage

final result = await PinePaymentSdk.startPayment(
	paymentUrl: "https://your-payment-page.com",
	successUrl: "https://merchant.com/success",
	failureUrl: "https://merchant.com/failure",
	appBarTitle: "Complete Payment",
);

if (result.success) {
	// payment success
} else {
	// payment failed or cancelled
}

If your gateway sends both outcomes to one redirect callback URL, use:

final result = await PinePaymentSdk.startPaymentWithRedirect(
	paymentUrl: "https://your-payment-page.com",
	redirectUrl: "https://merchant.com/redirect",
	appBarTitle: "Complete Payment",
);

PaymentResult:

class PaymentResult {
	final bool success;
	final String status;
	final String finalUrl;
	final String? transactionId;
	final String? message;
}

Callback Handling

The SDK watches WebView navigation and automatically completes the flow when the current URL matches successUrl or failureUrl.

• Query parameters are parsed to extract values like transactionId, status, and message
• If status is not provided, success/failure is inferred from the matched callback URL
• The WebView route pops automatically and returns PaymentResult

External UPI and Intent Handling

When WebView navigation points to external schemes (upi://, intent://, and other non-web schemes), the SDK:

1. Prevents in-WebView navigation
2. Launches the external app via url_launcher
3. Returns to the WebView and continues monitoring callback URLs
4. Uses browser fallback URL for intent:// when available

Android Setup

pinelabs_web targets Android 8+ (minSdk 26).

The plugin ships manifest queries for common UPI schemes. If your callback uses a custom scheme, add an intent-filter in your app AndroidManifest.xml:

<activity ...>
	<intent-filter>
		<action android:name="android.intent.action.VIEW" />
		<category android:name="android.intent.category.DEFAULT" />
		<category android:name="android.intent.category.BROWSABLE" />
		<data android:scheme="yourapp" android:host="payment" />
	</intent-filter>
</activity>

iOS Setup

The plugin targets iOS 13+.

Add required query schemes in Info.plist of the merchant app:

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>upi</string>
	<string>intent</string>
	<string>phonepe</string>
	<string>gpay</string>
	<string>paytm</string>
	<string>tez</string>
</array>

If you use a custom callback scheme, also configure CFBundleURLTypes.

Lifecycle and Safety Notes

• Uses Flutter WidgetsBindingObserver to handle app switch/resume after UPI app launch
• Keeps JavaScript enabled only in the payment WebView
• Does not bypass SSL validation at native level
• Guards against invalid URLs and returns safe failure/cancel states

Example

A complete working demo is available in example. It demonstrates:

• Starting payment flow
• Simulated success/failure callback URLs
• Rendering PaymentResult in the UI

License

See LICENSE.