Skip to main content
このページでは、公式の Dodo Payments React Native checkout SDK、@dodopayments/react-native-checkout を説明します。この SDK はネイティブブラウザビューで Dodo Payments のホスト型チェックアウトを開き、型付きの結果を返します。以前のパッケージである dodopayments-react-native-sdk(スコープなし)は API が異なります。このページではスコープ付きパッケージのみを説明します。

Checkout Sessions API

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

Mobile Integration Guide

この SDK がモバイル決済フロー全体のどこに位置するかを確認します。
React Native SDK は、ネイティブの iOS および Android checkout SDK をラップする Turbo Module です。iOS では SFSafariViewController を、Android では Custom Tab を開きます。API key を保持せず、独自のチェックアウトロジックもないため、Dodo Payments API を呼び出すことはありません。チェックアウトはブラウザビューで実行されます。SDK はそのビューを表示・閉じ、return URL から結果を読み取ります。
この SDK は New Architecture のみをサポートします。React Native 0.77 以降、iOS 16 以降、Android minSdk 24 が必要です。Android アプリは compileSdk 34 以降でビルドする必要があります。

インストール

1

Install the Package

パッケージは自動リンクされ、Maven Central から com.dodopayments.api:checkout-android を取得します。
ネイティブ依存関係は自動的に解決されるため、ほかに必要なインストール手順はありません。
Appearance customization にはバージョン 1.2.0 以降が必要です。
2

Register a Callback URL Scheme

オペレーティングシステムがチェックアウトの return URL をアプリに戻すように、URL scheme を登録します。
android/app/build.gradle で scheme を manifest placeholder として設定します。
android/app/build.gradle
"myapp" をアプリの scheme に置き換えます。
すべてのプラットフォームで、バックエンドが session を作成するときに、チェックアウト session の return_url と同じ URL を設定します。SDK は scheme、host、path に基づいて return URL を照合します。URL が実際のページを読み込む必要はありません。

使用方法

バックエンドから取得した checkout_url を使用して、DodoCheckout.start を呼び出します。
onEvent は、type が checkout.opened、checkout.return_received、または checkout.closed であるイベントを受け取ります。これらは logging のみに使用し、結果の判定には決して使用しないでください。

Return URL の転送

iOS では、SFSafariViewController が自身の return URL を捕捉できないため、return URL を処理する Linking listener が必要です。Android では、handleOpenURL は何もせず、false を解決します。Android SDK が redirect をネイティブに捕捉するためです。両方のプラットフォームで listener を登録できます。
iOS では、URL が進行中のチェックアウトに属する場合、handleOpenURL は true を解決し、それ以外の URL については false を解決します。

結果の意味

SDK は return URL の query parameters から結果を構築します。
result.status は UI hint であり、payment の証明ではありません。payment.succeeded または subscription.active webhook を使用して、すべての payment をバックエンドから確認してください。
CheckoutStatus
必須
5 つの値のいずれかです。
  • succeeded: return URL に status=succeeded(one-time payment)または status=active(subscription)が含まれています。
  • failed: payment が declined しました(status=failed)。
  • cancelled: return URL が届く前に customer がブラウザビューを閉じました。SDK は結果を把握できず、payment が成功している可能性もあるため、failure screen を表示しないでください。代わりに abandoned session を reconcile します。
  • pending: payment が後から settle します(status=processing または任意の requires_* value)。または status parameter がないか、認識されませんでした。cancelled と同様に reconcile します。
  • expired: checkout session の期限が切れました(status=expired)。
string
return URL に含まれている場合の payment_id query parameter。UI に表示できますが、access の付与には使用しないでください。Verify the Payment を参照してください。
string
subscription_id query parameter。subscription checkouts に設定されます。
string[]
license_key query parameter。checkout に license key products が含まれる場合に設定されます。
string
email query parameter。checkout で email address が取得された場合に設定されます。
Record<string, string>
return URL に含まれるすべての query parameter を、そのまま返します。

Payment の確認

Webhooks

payment が成功したとき、または subscription が activate されたとき、Dodo Payments はバックエンドを呼び出します。

Get Payment Detail

secret key で paymentId を lookup し、status を確認します。
これらのいずれかによって payment が確認された後にのみ access を付与してください。result.status だけに依存しないでください。

Appearance Customization

checkout browser の toolbar、buttons、color scheme を変更するには、customization を start(...) に渡します。Android Custom Tabs と iOS SFSafariViewController は異なる native controls を公開するため、options は android object と ios object に分けられています。各プラットフォームは自身の object のみを読み取ります。すべての field は optional です。field を省略すると、プラットフォーム独自の default が適用されます。
string
toolbar の background color。hex string として指定します: "#RRGGBB" または "#AARRGGBB"。
string
navigation bar の color。hex string として指定します。
string
navigation bar の上にある divider の color。hex string として指定します。
'default' | 'back'
default は system の「X」icon を表示します。back は SDK が描画する back arrow を表示します。
'start' | 'end'
close button が表示される toolbar の側。
boolean
toolbar の share icon を表示します。false はこれを非表示にします。
boolean
toolbar の URL の下に page title を表示します。
boolean
ページのスクロールに合わせて toolbar を自動的に非表示にします。
boolean
overflow menu に「Bookmark this page」を表示します。
boolean
overflow menu に「Download page」を表示します。
'system' | 'light' | 'dark'
light または dark は、device の system setting に関係なく、その appearance を強制します。system は system setting に従います。
'done' | 'close' | 'cancel'
dismiss button の style。iOS は label と icon のどちらとして render するかを決定します。
'pageSheet' | 'fullScreen'
pageSheet(default)は、customer が下に swipe して dismiss できる card を表示します。fullScreen は画面全体を覆います。
boolean
ページのスクロールに合わせて toolbar を collapse できるようにします。効果があるのは presentationStyle が fullScreen の場合のみです。pageSheet では、この設定に関係なく bars は固定されたままです。
'system' | 'light' | 'dark'
light または dark は、device の system setting に関係なく、その appearance を強制します。system は system setting に従います。
iOS には toolbar color の option がありません。基盤となる SFSafariViewController の tint properties は iOS 26 以降で deprecated になっているためです。

Errors

start は、誤用または platform failure の場合にのみ CheckoutError で reject します。理由は error.code から読み取ります。customer による cancel や declined payment は常に result であり、rejection ではありません。
  • INVALID_CHECKOUT_URL: checkoutUrl は、checkout.dodopayments.com または test.checkout.dodopayments.com 上の /session/ で始まる path を持つ https checkout session URL ではありません。
  • INVALID_RETURN_URL: returnUrl は scheme と host を持つ absolute URL ではありません。
  • ALREADY_IN_PROGRESS: 別の checkout が実行中です。一度に実行できる checkout は 1 つだけです。
  • PLATFORM_ERROR: 予期しない platform failure です。SDK は認識されない native error もこの code で報告します。

Abandoned Sessions

native SDK は checkout 開始時に checkout session を記録し、checkout が succeeded、failed、または expired で終了した場合にのみ記録を消去します。checkout 中に app または JavaScript bundle が kill されて start promise が失われた場合、および cancelled または pending result の後も、記録は残ります。次回の mount 時、および cancelled または pending result のたびに確認します。
abandoned.sessionId は checkout session ID で、cks_ で始まります。abandoned.createdAt は checkout が開始された Date です。バックエンドでは Get Checkout Session を使用して session を lookup できます。この API は payment_id と payment_status を返します。payment が final status に達するまでは、failed ではなく pending として扱います。

Mobile Integration Guide

Android、iOS、Flutter 共通の同じ contract。

Expo Boilerplate

checkout integration を含む完全な Expo example。
最終更新日 2026年9月26日