React Native

This is the official Dodo Payments React Native checkout SDK, @dodopayments/react-native-checkout. It opens Dodo’s hosted checkout in a native browser view and returns a typed result. Note: an older, unrelated package named dodopayments-react-native-sdk (unscoped) exists with a completely different API. This page documents the current official scoped package only.

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.

The React Native SDK is a thin Turbo Module wrapper over the same native Swift and Kotlin cores. It opens SFSafariViewController on iOS and a Chrome Custom Tab on Android, holds no API key, and never calls the Dodo API directly. All checkout logic runs in the browser; the SDK simply manages the view lifecycle and captures the return URL.

This SDK requires New Architecture only, React Native 0.76+, iOS 16+, and Android minSdk 24.

Installation

Install the Package

Android
iOS
Expo

The package is autolinked and pulls com.dodopayments.api:checkout-android from Maven.

npm i @dodopayments/react-native-checkout

No additional setup needed; the native dependency is resolved automatically.

npm i @dodopayments/react-native-checkout
cd ios && pod install

The Swift core is bundled in the package and installed via CocoaPods.

Development builds only (not Expo Go).

npm i @dodopayments/react-native-checkout

Then configure your app.json (see Register a Callback URL Scheme below).

Your app must register a URL scheme to receive the return URL from the checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

In android/app/build.gradle:

android/app/build.gradle

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

Replace "myapp" with your app’s scheme.

In ios/YourApp/Info.plist:

Info.plist

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

You can also add this via Xcode’s Info → URL Types UI.

The package’s own config plugin registers the scheme for both platforms at prebuild. Pass it a scheme option in app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme must match what you pass as returnUrl (e.g. myappcheckout://return), and must differ from expo.scheme. Expo already registers that one on MainActivity, and reusing it can route the checkout return to the wrong screen.Rebuild the native project after editing app.json:

npx expo prebuild --clean

This works with development builds only, not Expo Go.If android/app/build.gradle is hand-maintained and has no standard defaultConfig { } block for the plugin to find, add the placeholder yourself instead. See the Android tab above.

Usage

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

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

Forwarding the Return URL

The Linking listener is required for iOS’s return-URL handling. On Android, handleOpenURL is a no-op that resolves false because the Android core handles its redirect natively. It’s safe to register the listener unconditionally on both platforms.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

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.

string[]

Set when the checkout includes license key products.

string

Set when the checkout captures an email.

Record<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 start(...). 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.

'default' | 'back'

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

'start' | 'end'

Which side of the toolbar the close button appears on.

Shows the toolbar’s share icon.

boolean

Shows the page title under the URL in the toolbar.

boolean

Lets the toolbar auto-hide as the page scrolls.

boolean

Shows “Bookmark this page” in the overflow menu.

boolean

Shows “Download page” in the overflow menu.

'system' | 'light' | 'dark'

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

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Label or icon for the dismiss button.

'pageSheet' | 'fullScreen'

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

boolean

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

'system' | 'light' | 'dark'

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

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Errors

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

INVALID_CHECKOUT_URL: not a checkout.dodopayments.com session URL.
INVALID_RETURN_URL: not a valid absolute URL.
ALREADY_IN_PROGRESS: a checkout is already running.
PLATFORM_ERROR: unexpected platform failure.

Abandoned Sessions

If the app or the JS bundle is killed mid-checkout, the promise is lost but the native layer keeps the session. Recover it on next mount and reconcile it with your backend.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

Mobile Integration Guide

The same contract for Android, iOS, and Flutter.

Expo Boilerplate

A complete Expo example with checkout integration.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Usage

Forwarding the Return URL

What the Result Means

Verify the Payment

Webhooks

Get Payment Detail

Appearance Customization

Errors

Abandoned Sessions

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Installation

​Usage

​Forwarding the Return URL

​What the Result Means

​Verify the Payment

Webhooks

Get Payment Detail

​Appearance Customization

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Expo Boilerplate

Installation

Usage

Forwarding the Return URL

What the Result Means

Verify the Payment

Appearance Customization

Errors

Abandoned Sessions

Related