このページでは、公式の 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 がモバイル決済フロー全体のどこに位置するかを確認します。
SFSafariViewController を、Android では Custom Tab を開きます。API key を保持せず、独自のチェックアウトロジックもないため、Dodo Payments API を呼び出すことはありません。チェックアウトはブラウザビューで実行されます。SDK はそのビューを表示・閉じ、return URL から結果を読み取ります。
インストール
1
Install the Package
- Android
- iOS
- Expo
パッケージは自動リンクされ、Maven Central から ネイティブ依存関係は自動的に解決されるため、ほかに必要なインストール手順はありません。
com.dodopayments.api:checkout-android を取得します。2
Register a Callback URL Scheme
オペレーティングシステムがチェックアウトの return URL をアプリに戻すように、URL scheme を登録します。すべてのプラットフォームで、バックエンドが session を作成するときに、チェックアウト session の
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
android/app/build.gradle で scheme を manifest placeholder として設定します。android/app/build.gradle
"myapp" をアプリの scheme に置き換えます。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 を登録できます。
handleOpenURL は true を解決し、それ以外の URL については false を解決します。
結果の意味
SDK は return URL の query parameters から結果を構築します。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)。またはstatusparameter がないか、認識されませんでした。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 を確認します。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 が適用されます。
Android — Custom Tab
Android — Custom Tab
string
toolbar の background color。hex string として指定します:
"#RRGGBB" または "#AARRGGBB"。navigation bar の color。hex string として指定します。
navigation bar の上にある divider の color。hex string として指定します。
'default' | 'back'
default は system の「X」icon を表示します。back は SDK が描画する back arrow を表示します。'start' | 'end'
close button が表示される toolbar の側。
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 に従います。iOS — SFSafariViewController
iOS — SFSafariViewController
'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 に従います。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 を持つhttpscheckout 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 として扱います。
Related
Mobile Integration Guide
Android、iOS、Flutter 共通の同じ contract。
Expo Boilerplate
checkout integration を含む完全な Expo example。