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.

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

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

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Community Projects

Installation

Usage

What the Result Means

Verify the Payment

Errors

Abandoned Sessions

Related