Mobile SDKs
Integrate Pine Labs Mobile SDKs for Android and iOS to deliver secure, app-native checkout flows with backend verification and webhook-backed reliability.
Pine Labs Mobile SDKs enable native in-app payment experiences on Android and iOS. The SDK manages checkout UI and payment method interactions natively while your backend handles order creation, credential security, and payment verification through webhooks.
When To Use Mobile SDKs
Use Mobile SDKs when your payment flow runs inside:
- Native Android applications with in-app checkout
- Native iOS applications with in-app payment flows
- Flutter apps targeting native Android and iOS payment surfaces
- App-first commerce journeys requiring UPI intent or native payment method selection
- In-app subscription or repeat purchase flows
Choose Your Platform
React Native
Integrate checkout into React mobile apps using react-native-mobileview with callback-based payment handling.
Android
Embed Pine Labs checkout in Android apps through the EDGE SDK .aar library with native Mobile View support.
iOS
Add payment flows to iOS apps using the PineLabsMobileSDK.xcframework with WKWebView rendering.
Flutter
Build cross-platform checkout in Flutter apps with the pine_payment_sdk package for Android and iOS.
Mobile Integration Architecture
Every Mobile SDK integration follows a three-layer model that keeps sensitive operations on the server and delivers native payment UX on the device.
| Layer | Responsibility |
|---|---|
| Mobile SDK (Android/iOS/Flutter) | Render native checkout UI, detect available UPI apps, handle payment interaction callbacks |
| Merchant Backend | Generate auth tokens, create checkout links, validate payment responses, manage order state |
| Webhooks | Deliver reliable, retry-safe payment lifecycle events for final status confirmation |
Store client_id and client_secret exclusively on your backend. Mobile app binaries can be decompiled. Any credential embedded in client code is compromised by definition.
Prerequisites
Before integrating any Mobile SDK, confirm the following:
- Active Pine Labs merchant account with API access enabled.
client_idandclient_secretstored securely in your backend infrastructure.- Backend endpoints for the Generate Token API and Generate Checkout Link API.
- Webhook endpoint configured to receive and verify payment lifecycle events.
- Platform-specific app setup complete:
- Android: minSdk 26+, internet permission, UPI app detection configured.
- iOS: iOS 13.0+, UPI URL schemes declared in Info.plist.
- Flutter: Flutter 3.24+, platform-specific configurations applied.
- UAT test matrix covering success, failure, cancellation, background/foreground transitions, network loss, and app-kill scenarios.
How Mobile SDK Checkout Works
Your mobile app calls your backend API to initiate a payment. The backend generates an auth token using the Generate Token API, then creates a checkout link using the Generate Checkout Link API.
Your backend responds with the redirect_url (or payment URL and success/failure URLs) that the mobile SDK needs to launch checkout.
The app initializes the SDK with the checkout URL. The SDK renders the payment page natively, detects available UPI apps (on Android/iOS), and presents payment method options.
The customer selects a payment method, authenticates (PIN, biometric, OTP), and completes the transaction. For UPI payments, the SDK handles intent-based redirection to the UPI app and return.
The SDK returns a result through platform-specific callbacks (onTransactionResponse, onCancelTxn, onErrorOccured) indicating the session outcome.
Your backend receives the webhook event or calls Get Order by Order ID to confirm the authoritative payment state. The app then reflects the verified result to the customer.
Platform Requirements at a Glance
| Platform | Minimum Version | Key Dependency | UPI Support |
|---|---|---|---|
| Android | API 26+ (Android 8.0) | pine_payment_sdk or .aar library | Built-in app detection |
| iOS | iOS 13.0+ | PinePaymentSDK pod/framework | URL scheme declaration required |
| Flutter | Flutter 3.24+, Dart 3.9.2+ | pine_payment_sdk package | Automatic via native layer |
UPI App Detection and Intent Handling
Mobile SDKs include built-in support for UPI payments through native app intents:
| Platform | How UPI works |
|---|---|
| Android | SDK automatically detects installed UPI apps (Google Pay, PhonePe, Paytm, CRED) and presents them as payment options. Payment launches via Android Intent. |
| iOS | Requires UPI URL schemes declared in Info.plist (upi, phonepe, gpay, paytm, tez, credpay). SDK handles scheme-based app launch and return. |
| Flutter | Native layer handles UPI detection and intent. No additional Dart configuration needed. |
SDK Callback Methods
All Mobile SDK platforms share a consistent callback interface:
| Callback | When it fires |
|---|---|
onTransactionResponse | Payment completed (success or failure returned from checkout) |
onCancelTxn | Customer cancelled the payment flow |
onErrorOccured | Payment page failed to load or SDK encountered an error |
internetNotAvailable | Network connectivity lost during the payment flow |
onPressedBackButton | Customer pressed back during payment |
Mobile SDK callbacks reflect what happened in the app session. They can be missed if the app is killed, the network drops, or the OS reclaims memory. Always verify final payment state through your backend using webhooks or the Get Order by Order ID API.
Mobile-Specific Best Practices
| Area | Recommendation |
|---|---|
| App lifecycle | Handle background/foreground transitions gracefully — payment continues on Pine Labs infrastructure even if the app is suspended |
| Network resilience | Implement retry-safe status polling as a fallback if webhook delivery is delayed |
| Security | Never embed API secrets in app binaries; use certificate pinning for backend calls |
| UX states | Show clear pending, processing, success, and failed states with appropriate messaging |
| Observability | Log correlation IDs (order ID, transaction ID, webhook event ID) for end-to-end traceability |
| Testing | Test app-kill during payment, network toggle, UPI app not installed, and timeout scenarios |
| Deep linking | Configure proper return URLs so UPI apps can redirect back to your app after payment |
Integration Methods
Single Order Token (Recommended)
Pass a single token to the SDK. The SDK navigates to the Pine Labs Native SDK and handles success/failure routing automatically.
Next Steps
- Choose your platform guide above to start integration.
- Review Web SDKs if you also need browser-based checkout without native UI.
- Configure Webhooks for reliable, event-driven payment reconciliation.
- Use Error Codes to build robust error messages and retry logic.