> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# React Native
> Open Dodo Payments' hosted checkout from a React Native app in a system browser tab and get a typed result back in one call.
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.
Create the checkout\_url this SDK opens, from your backend.
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
The package is autolinked and pulls `com.dodopayments.api:checkout-android` from Maven.
```sh theme={null}
npm i @dodopayments/react-native-checkout
```
No additional setup needed; the native dependency is resolved automatically.
```sh theme={null}
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).
```sh theme={null}
npm i @dodopayments/react-native-checkout
npx expo install expo-build-properties
```
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.
In `android/app/build.gradle`:
```kotlin android/app/build.gradle theme={null}
android {
defaultConfig {
manifestPlaceholders["dodoCallbackScheme"] = "myapp"
}
}
```
Replace `"myapp"` with your app's scheme.
In `ios/YourApp/Info.plist`:
```xml Info.plist theme={null}
CFBundleURLTypes
CFBundleURLName
myapp
CFBundleURLSchemes
myapp
```
You can also add this via Xcode's **Info → URL Types** UI.
In `app.json`:
```json app.json theme={null}
{
"expo": {
"plugins": [
[
"expo-build-properties",
{
"android": {
"manifestPlaceholders": {
"dodoCallbackScheme": "myapp"
}
}
}
]
],
"ios": {
"infoPlist": {
"CFBundleURLTypes": [
{
"CFBundleURLSchemes": ["myapp"]
}
]
}
}
}
}
```
The package also ships an `@dodopayments/react-native-checkout` Expo config
plugin, but it currently writes no URL scheme and no manifest placeholder.
Adding it alone will **not** register your callback scheme — use the
`expo-build-properties` and `infoPlist` configuration above.
Rebuild the native project after editing `app.json`:
```sh theme={null}
npx expo prebuild --clean
```
This works with development builds only, not Expo Go.
## Usage
```typescript theme={null}
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.
```typescript theme={null}
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.
One of `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
Set when the return URL included one. Display it in the UI, don't use it to grant access. See Verify the Payment below.
Set for subscription checkouts.
Set when the checkout includes license key products.
Set when the checkout captures an email.
Every query parameter from the return URL, verbatim.
## Verify the Payment
Dodo Payments calls your backend when a payment succeeds or a subscription activates.
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` 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.
```typescript theme={null}
import { DodoCheckout } from '@dodopayments/react-native-checkout';
const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
// reconcile abandoned.sessionId with your backend, then:
await DodoCheckout.clearAbandonedSession();
}
```
## Related
The same contract for Android, iOS, and Flutter.
A complete Expo example with checkout integration.