Quick Start
Get your mobile payment integration running in 4 simple steps
Platform Examples
Complete code examples for Android, iOS, React Native, and Flutter
Dodo Payments ships an official checkout SDK for Android, iOS, React Native,
and Flutter. Each one wraps the pattern documented below (open the checkout
URL, capture the return, parse the result) behind a single typed
start(...)
call, with abandoned-session recovery built in. Reach for a manual WebView only
if none of them fits your stack.Prerequisites
Before integrating Dodo Payments into your mobile app, ensure you have:- Dodo Payments Account: Active merchant account with API access
- API Credentials: API key and webhook secret key from your dashboard
- Mobile App Project: Android, iOS, React Native, or Flutter application
- Backend Server: To securely handle checkout session creation
Integration Workflow
The mobile integration follows a secure 4-step process where your backend handles API calls and your mobile app manages the user experience.1
Backend: Create Checkout Session
Checkout Session API Docs
Learn how to create a checkout session in your backend using Node.js, Python, and more. See complete examples and parameter references in the dedicated Checkout Sessions API documentation.
Security: Checkout sessions must be created on your backend server, never in the mobile app. This protects your API keys and ensures proper validation.
2
Mobile: Get Checkout URL
Your mobile app calls your backend to get the checkout URL. Authenticate
this request with the signed-in user’s own session token.
- iOS (Swift)
- Android (Kotlin)
- React Native (JavaScript)
- Flutter (Dart)
Security: Mobile apps only communicate with your backend, never directly with Dodo Payments API.
3
Mobile: Open Checkout in Browser
Open the checkout URL in a secure in-app browser for payment processing.
Or skip the manual setup entirely with the official checkout SDK for your
platform.
Pick your mobile SDK
Install steps and setup instructions for Android, iOS, React Native, and Flutter.
4
Backend: Handle Payment Completion
Process payment completion via webhooks and redirect URLs to confirm payment status.
Choose Your SDK
Every mobile SDK exposes the same contract: onestart(...) call opens Dodo’s
hosted checkout in the platform’s native browser surface and returns a typed
CheckoutResult whose status is succeeded, failed, cancelled,
pending, or expired. None of them holds an API key or calls the Dodo
Payments API, and all four support abandoned-session recovery.
Android
com.dodopayments.api:checkout-android opens a Chrome Custom Tab. Requires minSdk 23.iOS
dodopayments-mobile-sdk-ios opens SFSafariViewController. Requires iOS 16+.React Native
@dodopayments/react-native-checkout, a Turbo Module over both native cores. Requires React Native 0.76+.Flutter
dodopayments_checkout, a Pigeon channel over both native cores. Requires Flutter 3.44+.Registering a Callback URL Scheme
All four SDKs hand control back to your app through a custom URL scheme that you choose, for examplemyapp://checkout/return. Register it once per
platform:
- Android
- iOS
- Expo
android/app/build.gradle
Prefer to build it yourself? Open the
checkout_url in a WebView and intercept
the navigation to your return_url, then read the status and payment_id
query parameters. The SDKs above do this for you in the platform’s real browser
surface, which is why Apple Pay and Google Pay keep working.Best Practices
- Security: Never ship an API key in your app. Create checkout sessions on your backend and pass only the resulting
checkout_urlto the client. - Authority: Treat
CheckoutResult.statusas a UI hint. Grant access only after your backend confirms the payment. - User Experience: Show a loading state while your backend creates the session, and handle
cancelledas a normal outcome rather than an error. - Testing: Use test mode and test cards, and verify the return-URL round trip on a real device as well as a simulator.
Troubleshooting
Common Issues
- Callback never arrives: The scheme in
returnUrlmust match the one you registered. On Android that is thedodoCallbackSchememanifest placeholder; on iOS and React Native it is theInfo.plistURL type. - Checkout returns to the browser instead of your app (iOS): You haven’t forwarded the incoming URL. Call
DodoCheckout.handleOpenURL(url)from.onOpenURL,scene(_:openURLContexts:), or a React NativeLinkinglistener. PLATFORM_ERRORon Android: Most often a scheme mismatch. It can also appear if yourMainActivitysetsandroid:taskAffinity=""(the stockflutter createdefault), which lets some OEM builds lose the in-flight checkout.ALREADY_IN_PROGRESS: A checkout is still open. Await or dismiss the previous one before starting another.- Build fails with an unresolved placeholder: You added the Android SDK but never set
manifestPlaceholders["dodoCallbackScheme"]. - Payment succeeded but access wasn’t granted: Expected if you’re keying off the mobile result. Grant access from the
payment.succeeded/subscription.activewebhook instead.
Additional Resources
For questions or support, contact support@dodopayments.com.