Flutter

This is the official Dodo Payments Flutter package (dodopayments_checkout on pub.dev). A separate, community-built package also exists, see Community Projects.

Checkout Sessions API

Create the checkout_url this SDK opens, from your backend.

Mobile Integration Guide

See how this fits into the full mobile payment flow.

dodopayments_checkout opens Dodo’s hosted checkout in SFSafariViewController on iOS and a Chrome Custom Tab on Android — the same native cores used by the standalone iOS and Android SDKs. All checkout logic lives in those native cores; the Dart layer passes the call through a typed Pigeon channel. It holds no API key and never calls the Dodo Payments API. Requires Flutter 3.44+ / Dart 3.12+, iOS 16+, and Android minSdk 23.

Installation

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

Add a URL type for your scheme in ios/Runner/Info.plist:

ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Then forward incoming URLs (e.g. via app_links) into the SDK, because SFSafariViewController cannot catch its own return URL:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

It’s safe to forward every URL here. handleOpenURL only acts on URLs matching your registered returnUrl and resolves false for anything else.

Set your callback scheme as a Gradle manifest placeholder:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

If MainActivity sets android:taskAffinity="" (the stock flutter create default), remove it or give the SDK’s activities the same affinity. Otherwise some OEM Android builds can lose the in-flight checkout and return PLATFORM_ERROR.

Usage

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

What the Result Means

result.status is a UI hint, not proof of payment. Confirm every payment from your backend, via the payment.succeeded / subscription.active webhook.

CheckoutStatus

required

One of succeeded, failed, cancelled, pending, expired.

String?

Set when the return URL included one. Display it in the UI, don’t use it to grant access. See Verify the Payment below.

String?

Set for subscription checkouts.

List<String>?

Set when the checkout includes license key products.

String?

Set when the checkout captures an email.

Map<String, String>

Every query parameter from the return URL, verbatim.

Verify the Payment

Webhooks

Dodo Payments calls your backend when a payment succeeds or a subscription activates.

Get Payment Detail

Look up paymentId with your secret key to check its status directly.

Grant access after one of these confirms the payment, never from result.status alone.

Appearance Customization

Customize the checkout browser’s toolbar, buttons, and color scheme via customization on CheckoutParams. Options are grouped by platform because Android’s Custom Tab and iOS’s SFSafariViewController expose different native controls. All fields are optional; omitting customization uses each platform’s default appearance.

Android — Custom Tab

Toolbar background color.

Navigation bar color.

Divider color above the navigation bar.

CloseButtonStyle

standard shows the system “X” icon; back draws a back arrow instead.

CloseButtonPosition

Which side of the toolbar the close button appears on.

Shows the toolbar’s share icon.

bool

Shows the page title under the URL in the toolbar.

bool

Lets the toolbar auto-hide as the page scrolls.

bool

Shows “Bookmark this page” in the overflow menu.

bool

Shows “Download page” in the overflow menu.

BrowserColorScheme

Forces light or dark appearance regardless of the device’s system setting.

iOS — SFSafariViewController

DismissButtonStyle

Label or icon for the dismiss button.

PresentationStyle

pageSheet presents as a card with swipe-to-dismiss; fullScreen covers the whole screen.

bool

Lets the toolbar collapse on scroll. Only visible when presentationStyle is fullScreen — pageSheet keeps the bars pinned regardless of this setting.

BrowserColorScheme

Forces light or dark appearance regardless of the device’s system setting.

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

Errors

start throws CheckoutException only for misuse or a platform failure. A cancelled or declined payment is always a result, never an exception.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): not a checkout.dodopayments.com session URL.
invalidReturnUrl (INVALID_RETURN_URL): not a valid absolute URL.
alreadyInProgress (ALREADY_IN_PROGRESS): a checkout is already running.
platformError (PLATFORM_ERROR): unexpected platform failure.

Abandoned Sessions

If the app is killed mid-checkout, recover the session on next launch and reconcile it with your backend.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Mobile Integration Guide

The same contract for Android, iOS, and React Native.

Community Projects

A separate, community-built Flutter package also exists.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Usage

What the Result Means

Verify the Payment

Webhooks

Get Payment Detail

Appearance Customization

Errors

Abandoned Sessions

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​Installation

​Usage

​What the Result Means

​Verify the Payment

Webhooks

Get Payment Detail

​Appearance Customization

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Community Projects

Installation

Usage

What the Result Means

Verify the Payment

Appearance Customization

Errors

Abandoned Sessions

Related