React Native

これは公式のDodo Payments React NativeチェックアウトSDKで、@dodopayments/react-native-checkoutです。Dodoのホスト型チェックアウトをネイティブブラウザビューで開き、型付きの結果を返します。注: dodopayments-react-native-sdk（スコープなし）という、APIがまったく異なる古い無関係なパッケージが存在します。このページでは、現在の公式スコープ付きパッケージのみを説明します。

Checkout Sessions API

バックエンドから、このSDKが開くcheckout_urlを作成します。

Mobile Integration Guide

モバイル決済フロー全体の中での位置付けを確認します。

React Native SDKは、同じネイティブSwiftおよびKotlinコア上に構築された薄いTurbo Moduleラッパーです。iOSではSFSafariViewControllerを、AndroidではChrome Custom Tabを開き、API keyを保持せず、Dodo APIを直接呼び出すこともありません。すべてのチェックアウトロジックはブラウザー内で実行され、SDKはビューのライフサイクルを管理し、戻りURLを取得するだけです。

このSDKにはNew Architectureのみ、React Native 0.76以降、iOS 16以降、およびAndroid minSdk 24が必要です。

インストール

Install the Package

Android
iOS
Expo

パッケージは自動リンクされ、Mavenからcom.dodopayments.api:checkout-androidを取得します。

npm i @dodopayments/react-native-checkout

追加の設定は不要です。ネイティブ依存関係は自動的に解決されます。

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

Swiftコアはパッケージに含まれており、CocoaPodsを介してインストールされます。

開発ビルドのみ（Expo Goは対象外）。

npm i @dodopayments/react-native-checkout

次にapp.jsonを設定します（下記の「コールバックURLスキームの登録」を参照してください）。

アプリでチェックアウトからの戻りURLを受け取るには、URLスキームを登録する必要があります。

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

android/app/build.gradleで:

android/app/build.gradle

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

"myapp"をアプリのスキームに置き換えます。

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>

Xcode の Info → URL Types UI から追加することもできます。

パッケージ独自の config plugin は、両方のプラットフォームでスキームを prebuild に登録します。app.json に scheme オプションを渡します。

app.json

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

scheme は、returnUrl に渡す値（例: myappcheckout://return）と一致し、expo.scheme とは異なる必要があります。Expo はすでに MainActivity にそれを登録しているため、再利用すると checkout の戻り先が誤った画面になる可能性があります。app.json を編集した後、ネイティブプロジェクトを再ビルドします。

npx expo prebuild --clean

これは development builds でのみ動作し、Expo Go では動作しません。android/app/build.gradle を手動で管理していて、plugin が見つけられる標準の defaultConfig { } ブロックがない場合は、代わりにプレースホルダーを自分で追加してください。上記の Android タブを参照してください。

使い方

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

Return URL の転送

Linking リスナーは、iOS の return URL 処理に必要です。Android では、handleOpenURL は何もせずに false を解決します。これは Android core がリダイレクトをネイティブに処理するためです。両方のプラットフォームでリスナーを無条件に登録しても問題ありません。

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

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

結果の意味

result.status は UI のヒントであり、支払いの証明ではありません。payment.succeeded / subscription.active webhook を介して、すべての支払いを backend から確認してください。

CheckoutStatus

必須

succeeded、failed、cancelled、pending、expired のいずれか。

string

return URL にいずれかが含まれていた場合に設定されます。UI に表示するために使用し、アクセスの付与には使用しないでください。詳しくは、下記の「支払いの確認」を参照してください。

string

subscription checkout の場合に設定されます。

string[]

checkout に license key product が含まれている場合に設定されます。

string

checkout でメールアドレスを取得した場合に設定されます。

Record<string, string>

return URL に含まれるすべての query parameter を、そのまま保持します。

支払いの確認

Webhooks

支払いが成功したとき、または subscription が有効になったとき、Dodo Payments は backend を呼び出します。

Get Payment Detail

secret key を使用して paymentId を検索し、そのステータスを直接確認します。

これらのいずれかによって支払いが確認された後にアクセスを付与してください。result.status だけを根拠にしてはいけません。

外観のカスタマイズ

customization を使用して、start(...) 上でチェックアウトブラウザのツールバー、ボタン、カラースキームをカスタマイズできます。Android の Custom Tab と iOS の SFSafariViewController では利用できるネイティブコントロールが異なるため、オプションはプラットフォームごとにグループ化されています。すべてのフィールドはオプションです。customization を省略すると、各プラットフォームのデフォルトの外観が使用されます。

Android — Custom Tab

ツールバーの背景色。

ナビゲーションバーの色。

ナビゲーションバーの上に表示される区切り線の色。

'default' | 'back'

default ではシステムの「X」アイコンが表示され、back では代わりに戻る矢印が描画されます。

'start' | 'end'

ツールバーの閉じるボタンを表示する側。

ツールバーの共有アイコンを表示します。

boolean

ツールバーで URL の下にページタイトルを表示します。

boolean

ページのスクロールに合わせてツールバーを自動的に非表示にします。

boolean

オーバーフローメニューに「このページをブックマーク」を表示します。

boolean

オーバーフローメニューに「ページをダウンロード」を表示します。

'system' | 'light' | 'dark'

デバイスのシステム設定に関係なく、ライトまたはダークの外観を強制します。

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

閉じるボタンのラベルまたはアイコン。

'pageSheet' | 'fullScreen'

pageSheet はスワイプして閉じるカードとして表示され、fullScreen は画面全体を覆います。

boolean

スクロール時にツールバーを折りたたみます。presentationStyle が fullScreen の場合にのみ表示されます。pageSheet では、この設定に関係なくバーが固定されたままになります。

'system' | 'light' | 'dark'

デバイスのシステム設定に関係なく、ライトまたはダークの外観を強制します。

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

エラー

start は、誤用またはプラットフォームの障害が発生した場合にのみ、CheckoutError で reject します。キャンセルまたは拒否された支払いは常に結果として返され、例外にはなりません。

INVALID_CHECKOUT_URL: checkout.dodopayments.com セッション URL ではありません。
INVALID_RETURN_URL: 有効な絶対 URL ではありません。
ALREADY_IN_PROGRESS: チェックアウトはすでに実行中です。
PLATFORM_ERROR: 予期しないプラットフォーム障害です。

放棄されたセッション

チェックアウトの途中でアプリまたは JS bundle が強制終了されると、promise は失われますが、native layer はセッションを保持します。次回の mount でセッションを復元し、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

Android、iOS、Flutter に共通する同じ契約です。

Expo Boilerplate

チェックアウト統合を含む完全な Expo の例です。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

インストール

使い方

Return URL の転送

結果の意味

支払いの確認

Webhooks

Get Payment Detail

外観のカスタマイズ

エラー

放棄されたセッション

関連情報

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​インストール

​使い方

​Return URL の転送

​結果の意味

​支払いの確認

Webhooks

Get Payment Detail

​外観のカスタマイズ

​エラー

​放棄されたセッション

​関連情報

Mobile Integration Guide

Expo Boilerplate

インストール

使い方

Return URL の転送

結果の意味

支払いの確認

外観のカスタマイズ

エラー

放棄されたセッション

関連情報