Skip to main content
skill CX Codex

mobile-checkout — Claude Code skill: what it does, how to install

mobile-checkout guides integration of Dodo Payments hosted checkout into React Native, Flutter, iOS, and Android using system browsers.

MIT 192 installs ★ 14 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dodopayments/skills --skill mobile-checkout -a claude-code
Open on GitHub

What mobile-checkout does

This skill details how to run Dodo Payments checkout in mobile applications using SFSafariViewController on iOS and Chrome Custom Tabs on Android. It covers URL scheme redirects, deep linking, and recovery flows for abandoned sessions.

The core principle requires the backend to initialize checkout sessions via checkoutSessions.create while the mobile client simply presents the resulting URL. Storing your API key in the mobile binary is prohibited; granting user access relies strictly on server-side verification using payment.succeeded webhooks or direct API calls.

Selling digital goods on iOS is restricted to storefronts permitting external purchases, such as the US, EU, and Japan. South Korea is not supported.

What it helps with

  • Integrate Dodo Payments into React Native or Flutter apps
  • Launch checkout inside Chrome Custom Tabs or SFSafariViewController
  • Configure deep link and custom URL scheme returns
  • Verify payment.succeeded webhook signatures on the backend

Example prompts for the agent

  • Show how to implement Dodo Payments checkout in React Native with Turbo Modules
  • Create an Express backend endpoint to generate checkout_url with dodoCustomerId
  • How should I verify the payment.succeeded webhook before granting user access?

How to install mobile-checkout

1Skills CLI (Vercel)

npx skills add dodopayments/skills --skill mobile-checkout -a claude-code

2Manually: put the files in place

~/.claude/skills/mobile-checkout/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mobile-checkout/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mobile-checkout

How do I install mobile-checkout in Claude Code?

Run npx skills add dodopayments/skills --skill mobile-checkout -a claude-code in your terminal.

What does the mobile-checkout skill do?

It provides guidance on integrating Dodo Payments into mobile applications using system browser tabs and verifying payments on the backend.

Can I use this checkout for digital purchases on iOS?

Only in regions where Apple allows external purchase links, such as the US, EU, and Japan. South Korea is not supported, and other App Store storefronts require StoreKit.

Source text

SKILL.md · MIT
---
name: mobile-checkout
description: Dodo Payments in-app checkout for React Native, Flutter, native iOS, and Android using SFSafariViewController or Chrome Custom Tabs. Use when a mobile app must open a backend-created checkout session, handle deep link or custom URL scheme returns, recover abandoned checkouts, and verify payment server-side before unlocking access.
---

# Mobile In-App Checkout

This skill covers integrating Dodo Payments hosted checkout into native and cross-platform mobile apps using secure system browser contexts.

## When to use this skill

- Building a React Native app with Turbo Module checkout integration
- Adding checkout to a Flutter app via native bridge
- Implementing native iOS or Android checkout with secure browser contexts
- Registering custom URL schemes and deep links for payment return
- Handling abandoned checkout sessions and recovery flows
- Confirming payment authority server-side before granting access

## Core principle: Backend creates, mobile opens

Your backend creates the checkout session and returns a URL. The mobile app opens that URL in a secure browser context. Your API key must never be embedded in the app binary. The mobile SDK result is informational only; always verify the payment server-side via webhook or API before unlocking features or granting access.

## Architecture overview

1. **Backend:** Create a checkout session via `client.checkoutSessions.create(...)` and return the `checkout_url` to your mobile app.
2. **Mobile app:** Call the platform-specific SDK with the checkout URL and a registered return URL scheme.
3. **Browser context:** The SDK opens the URL in a secure system browser: SFSafariViewController on iOS and Chrome Custom Tabs on Android.
4. **Return:** After payment, the browser navigates to your return URL. The SDK captures the result and passes it to your app.
5. **Verification:** Query the checkout session or listen for a webhook to confirm the payment before granting access.

## React Native (Turbo Module)

Full guide: [references/react-native.md](references/react-native.md).

Covers:

- Installation
- Setup
- Starting checkout
- Abandoned session recovery
- Android minSdk requirement

## Flutter

Full guide: [references/flutter.md](references/flutter.md).

Covers:

- Installation
- Setup
- Starting checkout
- Return URL registration

## iOS (native)

Full guide: [references/ios.md](references/ios.md).

Covers:

- Installation
- Starting checkout
- Forwarding the return URL
- Abandoned sessions

## Android (native)

Full guide: [references/android.md](references/android.md).

Covers:

- Installation
- Starting checkout
- Abandoned sessions

## Backend: Creating checkout sessions

Always create checkout sessions on your backend. Never embed your API key in the mobile app.

```typescript
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const MOBILE_PRODUCTS = new Map([
  ['starter', 'pdt_starter123'],
  ['pro', 'pdt_pro456'],
]);

app.post('/api/mobile-checkout', requireAuth, async (req, res) => {
  const productId = MOBILE_PRODUCTS.get(req.body.plan);

  if (!productId) {
    return res.status(400).json({ error: 'Invalid plan' });
  }

  // requireAuth derives this mapping from the authenticated server-side session.
  const customerId = req.auth.dodoCustomerId;
  
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: { customer_id: customerId },
    return_url: 'myapp://checkout/return',
  });
  
  res.json({ checkout_url: session.checkout_url });
});
```

## Verifying payment server-side

Never grant access based on the mobile SDK result alone. Always verify via webhook or API.

### Via webhook

Listen for `payment.succeeded` webhooks. Webhook signature verification is covered in the `webhook-integration` skill.

```typescript
// Mount with express.raw({ type: 'application/json' }) so req.body is the raw Buffer.
app.post('/webhook', async (req, res) => {
  let event;
  try {
    event = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
  } catch {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  try {
    // Dodo retries and may redeliver: claim webhook-id with a UNIQUE insert
    // and grant in the same transaction so a duplicate is a no-op.
    await db.$transaction(async (tx) => {
      const claim = await tx.webhookLog.createMany({
        data: [{ webhookId: req.headers['webhook-id'] as string, eventType: event.type }],
        skipDuplicates: true,
      });
      if (claim.count === 0) return; // already processed

      if (event.type === 'payment.succeeded') {
        await grantAccess(event.data.customer.customer_id, tx);
      }
    });
  } catch (error) {
    // Non-2xx makes Dodo retry; the transaction rolled back the claim.
    return res.status(500).json({ error: 'Processing failed' });
  }

  res.json({ received: true });
});
```

### Via API

Query the checkout session to confirm payment:

```typescript
const session = await client.checkoutSessions.retrieve(sessionId);

if (session.payment_status === 'succeeded' && session.payment_id) {
  const payment = await client.payments.retrieve(session.payment_id);
  await grantAccess(payment.customer.customer_id);
}
```

## Selling digital goods on iOS

Dodo Payments hosted checkout can sell digital goods (subscriptions, courses, downloads, SaaS plans) in an iOS app **only on App Store storefronts where Apple allows external purchases**:

- **United States:** Guideline 3.1.1(a) allows buttons and links to other purchase methods without an entitlement (subject to the Epic v. Apple proceedings).
- **European Union:** requires Apple's EU external purchase entitlement (the StoreKit External Purchases or Offers Entitlement from October 1, 2026) and DMA compliance.
- **Japan:** allowed under the Mobile Software Competition Act, following Apple's Japan-specific entitlement requirements.
- **South Korea is not supported** (Apple requires a native, non-web-view flow through an approved Korean PSP).

On other storefronts, digital goods sold inside the iOS app must use Apple in-app purchase (StoreKit). Review Apple's region-specific entitlements before enabling Dodo checkout for a storefront; unsupported flows can get the app rejected.

## Common mistakes

### Embedding the API key in the app

Never include your API key in the app binary or client-side code. Always create checkout sessions on your backend.

```typescript
// WRONG
const client = new DodoPayments({
  bearerToken: 'dodo_live_abc123...',  // Never hardcode
});

// CORRECT
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,  // Backend only
});
```

### Trusting the mobile SDK result

The SDK result is informational. Always verify server-side before granting access.

```typescript
// WRONG
if (result.status === 'succeeded') {
  grantAccess();  // No verification
}

// CORRECT
if (result.status === 'succeeded') {
  const verified = await verifyPaymentOnBackend(result.paymentId);
  if (verified) {
    grantAccess();
  }
}
```

### Forgetting URL scheme registration

If you don't register the custom URL scheme, the app won't receive the return callback and checkout will appear to hang.

- React Native: Use the Expo plugin or manually register in `Info.plist` and `AndroidManifest.xml`.
- Flutter: Register in both `Info.plist` and `AndroidManifest.xml`.
- iOS: Add `CFBundleURLTypes` to `Info.plist` and forward URLs to `DodoCheckout.handleOpenURL`.
- Android: Set `manifestPlaceholders["dodoCallbackScheme"]`; the SDK supplies the intent filter.

### Not handling all result statuses

Always handle all five statuses: `succeeded`, `failed`, `cancelled`, `pending`, and `expired`. Each requires different UX.

```typescript
// WRONG
if (result.status === 'succeeded') {
  showSuccess();
}

// CORRECT
switch (result.status) {
  case 'succeeded':
    showSuccess();
    break;
  case 'failed':
    showFailure();
    break;
  case 'cancelled':
  case 'pending':
    // Unknown outcome - reconcile, never show a failure
    reconcileAbandonedSession();
    break;
  case 'expired':
    showExpired();
    break;
}
```

### Ignoring abandoned sessions

If the app crashes or is backgrounded during checkout, the session is abandoned. Always check for and recover abandoned sessions on app startup.

```typescript
// WRONG
// No recovery logic

// CORRECT: reconcile on launch and after every cancelled/pending result,
// and clear the record only once the backend reports a final outcome.
await reconcileAbandonedSession(); // defined in references/react-native.md
```

## Package names

Use `@dodopayments/react-native-checkout` for React Native and `dodopayments_checkout` for Flutter. The similarly named `@dodopayments/react-native` and `dodo_payments_flutter` packages do not exist.

## Resources

- [Mobile Integration](https://docs.dodopayments.com/developer-resources/mobile-integration)
- [React Native SDK](https://docs.dodopayments.com/developer-resources/sdks/react-native)
- [iOS SDK](https://docs.dodopayments.com/developer-resources/sdks/ios)
- [Android SDK](https://docs.dodopayments.com/developer-resources/sdks/android)
- [Flutter SDK](https://pub.dev/packages/dodopayments_checkout)
- [Selling Digital Goods on iOS](https://docs.dodopayments.com/features/appstore-digital-goods)
- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks/intents) (for payment verification)

© dodopayments · MIT · dodopayments/skills

Similar skills

All skills for Mobile →

From the same set17

The whole set →
testing-and-go-live testing-and-go-live runs a Dodo Payments integration through test mode: cards, declines, renewals, webhooks. Then takes it to production with a launch checklist. CX Codex +1 219installs framework-adapters framework-adapters mounts official Dodo Payments adapters across Next.js, Express, Hono, Nuxt, and more. Sets up checkout, customer portal, and webhook handlers. CX Codex +1 209installs refunds-and-disputes refunds-and-disputes teaches coding agents how to issue refunds and handle dispute lifecycles with Dodo Payments. Helps wire webhooks, issue partial line-item refunds, and manage access. CX Codex +1 208installs product-catalog-management product-catalog-management manages Dodo Payments products, subscription pricing models, add-ons, and image uploads. Designed for TypeScript SDK integrations. CX Codex +1 208installs customer-management customer-management is a Claude Code skill for managing Dodo Payments customers: create records, set up portals and payment methods, manage wallets, and link app users to billing IDs. CX Codex +1 202installs discounts-and-promotions discounts-and-promotions is a Claude Code skill for configuring Dodo Payments promo codes, checking eligibility rules, and troubleshooting codes rejected at checkout. CX Codex +1 199installs localized-pricing localized-pricing guides multi-currency setups in Dodo Payments across fixed regional prices, live Adaptive Currency conversion, and purchasing power parity (PPP) tiers. CX Codex +1 198installs better-auth-integration The better-auth-integration skill connects Better Auth with Dodo Payments for customer sync, checkout, portal access, usage events, and signed webhooks. CX Codex +1 192installs

Project sponsors

Companies that keep this analytics open