React Native

This page covers the official Dodo Payments React Native checkout SDK, @dodopayments/react-native-checkout. It opens Dodo Payments hosted checkout in a native browser view and returns a typed result. An older package, dodopayments-react-native-sdk (unscoped), has a different API. This page documents only the scoped package.

Checkout Sessions API

Create the checkout_url that this SDK opens, from your backend.

Mobile Integration Guide

See how this SDK fits into the full mobile payment flow.

The React Native SDK is a Turbo Module that wraps the native iOS and Android checkout SDKs. It opens SFSafariViewController on iOS and a Custom Tab on Android. It holds no API key and has no checkout logic of its own, so it never calls the Dodo Payments API. Checkout runs in the browser view. The SDK presents and dismisses that view and reads the result from the return URL.

This SDK supports the New Architecture only. It requires React Native 0.77 or later, iOS 16 or later, and Android minSdk 24. Your Android app must build with compileSdk 34 or later.

Installation

Install the Package

Android
iOS
Expo

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

npm i @dodopayments/react-native-checkout

The native dependency resolves automatically, so no other install step is needed.

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

The package bundles the Swift core, and CocoaPods installs it.

The SDK works in development builds only, not in Expo Go.

npm i @dodopayments/react-native-checkout

Then configure the plugin in app.json, as shown in the next step.

Appearance customization requires version 1.2.0 or later.

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

Set the scheme as a manifest placeholder in android/app/build.gradle:

android/app/build.gradle

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

Replace "myapp" with your app’s scheme.

Add a URL type to 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 the URL type in Xcode under Info → URL Types.

The package’s config plugin registers the scheme for both platforms during prebuild. Pass the scheme as the plugin’s scheme option in app.json:

app.json

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

The plugin’s scheme must match the scheme of the returnUrl you pass, for example myappcheckout://return. Use a scheme that differs from expo.scheme. Expo already registers expo.scheme on MainActivity, so reusing it can send the checkout return to the wrong activity on Android, and the plugin warns you. The plugin rejects http, https, and other system schemes.Rebuild the native project after you edit app.json:

npx expo prebuild --clean

The plugin works with development builds only, not Expo Go. On iOS, you still need the Linking listener in Forwarding the Return URL.If android/app/build.gradle has no defaultConfig { } block, the plugin stops prebuild with an error. In that case, add the placeholder yourself, as shown in the Android tab.

On every platform, set the same URL as the checkout session’s return_url when your backend creates the session. The SDK matches the return URL on scheme, host, and path. The URL doesn’t need to load a real page.

Usage

Call DodoCheckout.start with the checkout_url from your backend:

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));

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
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': await reconcileAbandonedSession(); break; // outcome unknown, not a failure
  case 'pending':   await reconcileAbandonedSession(); break;
  case 'expired':   showExpired(); break;
}

onEvent receives events with a type of checkout.opened, checkout.return_received, or checkout.closed. Use them for logging only, never to decide the outcome.

Forwarding the Return URL

iOS needs the Linking listener to handle the return URL, because SFSafariViewController can’t catch its own return URL. On Android, handleOpenURL does nothing and resolves false, because the Android SDK catches its redirect natively. You can register the listener on both platforms.

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

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

On iOS, handleOpenURL resolves true when the URL belongs to the checkout in progress, and false for any other URL.

What the Result Means

The SDK builds the result from the query parameters on the return URL.

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

CheckoutStatus

required

One of five values:

succeeded: the return URL has status=succeeded (one-time payment) or status=active (subscription).
failed: the payment was declined (status=failed).
cancelled: the customer closed the browser view before the return URL arrived. The SDK doesn’t know the outcome, and the payment may have succeeded, so don’t show a failure screen. Reconcile the abandoned session instead.
pending: the payment settles later (status=processing or any requires_* value), or the status parameter was missing or unrecognized. Reconcile it like cancelled.
expired: the checkout session expired (status=expired).

string

The payment_id query parameter, when the return URL includes one. Show it in your UI, but don’t use it to grant access. See Verify the Payment.

string

The subscription_id query parameter. Set for subscription checkouts.

string[]

The license_key query parameter. Set when the checkout includes license key products.

string

The email query parameter. Set when checkout captures an email address.

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.

Grant access only after one of these confirms the payment. Don’t rely on result.status alone.

Appearance Customization

To change the checkout browser’s toolbar, buttons, and color scheme, pass customization to start(...). Android Custom Tabs and iOS SFSafariViewController expose different native controls, so the options are grouped into an android object and an ios object. Each platform reads only its own object. Every field is optional. When you omit a field, the platform applies its own default.

Android — Custom Tab

Toolbar background color, as a hex string: "#RRGGBB" or "#AARRGGBB".

Navigation bar color, as a hex string.

Color of the divider above the navigation bar, as a hex string.

'default' | 'back'

default shows the system “X” icon. back shows a back arrow that the SDK draws.

'start' | 'end'

The side of the toolbar where the close button appears.

Shows the toolbar’s share icon. false hides it.

boolean

Shows the page title under the URL in the toolbar.

boolean

Hides the toolbar automatically as the page scrolls.

boolean

Shows “Bookmark this page” in the overflow menu.

boolean

Shows “Download page” in the overflow menu.

'system' | 'light' | 'dark'

light or dark forces that appearance regardless of the device’s system setting. system follows the system setting.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Style of the dismiss button. iOS decides whether it renders as a label or an icon.

'pageSheet' | 'fullScreen'

pageSheet (the default) presents a card that the customer can swipe down to dismiss. fullScreen covers the whole screen.

boolean

Lets the toolbar collapse as the page scrolls. It has a visible effect only when presentationStyle is fullScreen. With pageSheet, the bars stay pinned regardless of this setting.

'system' | 'light' | 'dark'

light or dark forces that appearance regardless of the device’s system setting. system follows the system setting.

iOS has no toolbar color option, because the underlying SFSafariViewController tint properties are deprecated as of iOS 26.

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. Read the reason from error.code. A customer who cancels, or a declined payment, is always a result, never a rejection.

INVALID_CHECKOUT_URL: checkoutUrl isn’t an https checkout session URL (path starting with /session/) on checkout.dodopayments.com or test.checkout.dodopayments.com.
INVALID_RETURN_URL: returnUrl isn’t an absolute URL with a scheme and a host.
ALREADY_IN_PROGRESS: another checkout is running. Only one checkout can run at a time.
PLATFORM_ERROR: an unexpected platform failure. The SDK also reports any unrecognized native error with this code.

Abandoned Sessions

The native SDK records the checkout session when checkout starts, and clears the record only when checkout ends with succeeded, failed, or expired. The record stays when the app or the JavaScript bundle is killed during checkout, which loses the start promise, and after a cancelled or pending result. Check for it on the next mount and after every cancelled or pending result:

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

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // Ask your backend for the outcome of abandoned.sessionId, and show it.
  // Clear the record only after the outcome is final:
  await DodoCheckout.clearAbandonedSession();
}

abandoned.sessionId is the checkout session ID, which starts with cks_. abandoned.createdAt is the Date checkout started. Your backend can look up the session with Get Checkout Session, which returns its payment_id and payment_status. Until the payment reaches a final status, treat it as pending, not failed.

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