Web SDKs
Integrate Pine Labs Web SDKs across React, Android, iOS, and Flutter with secure backend token generation, callback handling, and webhook-based payment verification.
Pine Labs Web SDKs help you embed secure payment checkout directly into browser-based applications. The SDK handles checkout UI rendering in the client while your backend manages order creation, signature validation, and payment verification through webhooks.
When To Use Web SDKs
Use Web SDKs when your customer pays through:
- Web applications built with React or JavaScript frameworks
- Android apps using WebView-based checkout
- iOS apps using WKWebView-based checkout
- Flutter apps targeting browser checkout surfaces
- Desktop and mobile browser sessions on merchant storefronts
Choose Your Platform
React
Integrate checkout into React web apps using react-native-webview with callback-based payment handling.
Android
Embed Pine Labs checkout in Android apps through the EDGE SDK .aar library with native WebView support.
iOS
Add payment flows to iOS apps using the PineLabsWebSDK.xcframework with WKWebView rendering.
Flutter
Build cross-platform checkout in Flutter apps with the pine_payment_sdk package for Android and iOS.
Core Integration Architecture
Every Web SDK integration follows a three-layer model that keeps sensitive operations server-side.
| Layer | Responsibility |
|---|---|
| Frontend (Web SDK) | Render checkout UI, capture payment interaction, and return callbacks |
| Backend APIs | Create orders, generate auth tokens, produce checkout links, and validate signatures |
| Webhooks | Deliver payment lifecycle events for reliable, tamper-proof status confirmation |
Never call Pine Labs APIs directly from the frontend. Store client_id and client_secret exclusively on your backend. Frontend API calls expose credentials and carry legal implications.
Prerequisites
Before integrating any Web SDK, confirm the following:
- Active Pine Labs merchant account with API access enabled.
client_idandclient_secretstored securely in your backend.- Backend endpoint to call the Generate Token API and Generate Checkout Link API.
- Webhook endpoint configured to receive payment lifecycle events.
- UAT test plan covering success, failure, cancellation, timeout, and network interruption scenarios.
How Web SDK Checkout Works
Your server calls the Generate Token API with client_id and client_secret to receive a time-limited access token.
Using the access token, your backend calls the Generate Checkout Link API with order details (amount, currency, merchant reference). The API returns a redirect_url.
Your frontend initializes the platform-specific Web SDK with the redirect_url. The SDK opens the Pine Labs hosted checkout page.
The customer interacts with the checkout page, selects a payment method, and completes authentication.
The SDK fires callback methods (onTransactionResponse, onCancelTxn, onErrorOccured) to inform your app of the outcome.
Your backend calls the Get Order by Order ID API or processes the webhook event to confirm the final payment state before fulfilling the order.
Platform Requirements at a Glance
| Platform | Minimum Version | Key Dependency |
|---|---|---|
| React | React 16.8+, Node.js 14+ | react-native-webview |
| Android | SDK 21+ (Lollipop) | EDGE-SDK.aar library |
| iOS | iOS 12.0+, Swift 5.0 | PineLabsWebSDK.xcframework |
| Flutter | Flutter 3.24+, Dart 3.9.2+ | pine_payment_sdk package |
SDK Callback Methods
All Web SDK platforms share a consistent callback interface:
| Callback | When it fires |
|---|---|
onTransactionResponse | Payment completed (success or failure) |
onCancelTxn | Customer cancelled the payment |
onErrorOccured | Checkout page failed to load |
internetNotAvailable | Network connectivity lost during checkout |
onPressedBackButton | Customer pressed back during payment flow |
SDK callbacks indicate what happened in the browser session but are not tamper-proof. Always confirm the final payment state through your backend using the Get Order by Order ID API or webhook events.
Best Practices
| Focus area | Recommendation |
|---|---|
| Performance | Load SDK only on checkout intent to avoid blocking initial page render |
| Reliability | Treat webhook status as the authoritative source of truth for payment state |
| Security | Keep all API credentials, token generation, and signature validation on backend only |
| Conversion | Minimize checkout steps and provide clear progress indicators |
| Error handling | Map all callback states to user-friendly messages with retry options where applicable |
| Testing | Cover success, failure, timeout, back-press, and app-kill scenarios in UAT |
Integration Methods
Single Redirect URL (Recommended)
Pass a single redirect_url to the SDK. The SDK navigates to the Pine Labs hosted checkout page and handles success/failure routing automatically.
Separate Success and Failure URLs
Provide distinct successUrl and failureUrl endpoints. The SDK redirects to the appropriate URL based on checkout outcome. Useful when your app needs different post-payment landing flows.
Next Steps
- Choose your platform guide above to start integration.
- Review Mobile SDKs if you also need native app checkout without WebView.
- Use Webhooks for reliable, event-driven payment state handling.
- Refer to Error Codes to build robust error messaging.