Mobile Integration Guide - Dodo Payments Documentation

Quick Start

バックエンドからチェックアウトへ、そして戻るまでの4つのステップ。

Platform Examples

Android、iOS、React Native、Flutter向けのコード。

Checkout Customization

モバイルで特に重要な14個のcheckout sessionパラメータ。

Mobile Recipes

よくある5つのモバイルシナリオに対応する完全なリクエストボディ。

モバイルアプリは、プラットフォームのシステムブラウザー画面でDodo Paymentsのホスト型チェックアウトを開き、チェックアウト終了時に顧客をアプリへ戻します。バックエンドがcheckout sessionを作成し、webhookからアクセス権を付与します。

Dodo Paymentsは、Android、iOS、React Native、Flutter向けの公式checkout SDKを提供しています。各SDKはcheckout URLを開き、復帰を取得し、1回の型付きstart(...)呼び出しの背後で結果を解析します。また、それぞれに放棄されたsessionの復旧機能が含まれています。SDKがどれもスタックに適合しない場合にのみ、フローを手動で構築してください。

前提条件

始める前に、次のものが必要です。

Dodo Paymentsアカウント。
Developer → API Keysから取得したAPI keyと、Developer → Webhooksから取得したwebhook signing secret。
Android、iOS、React Native、またはFlutterアプリ。
checkout sessionを作成するバックエンドサーバー。API keyはこのサーバーに保存します。

統合ワークフロー

すべてのDodo Payments API呼び出しはバックエンドから行います。アプリはバックエンドにcheckout URLを要求し、それを開いて結果を表示するだけです。

ディープリンク内のstatusは、顧客に何を表示するかをアプリに伝えます。これは支払いの証明ではありません。アクセス権はモバイルの結果ではなく、バックエンドで受信したpayment.succeededまたはsubscription.active webhookから付与してください。

Backend: Create Checkout Session

バックエンドはAPI keyを使ってcheckout sessionを作成し、そのcheckout_urlをアプリに返します。sessionのreturn_urlには、アプリが登録するディープリンクを設定します。例：myapp://checkout/return。

Checkout Session API Docs

Node.js、Pythonなどの言語からcheckout sessionを作成する方法と、完全なパラメータリファレンスを確認できます。

Security：checkout sessionはモバイルアプリではなく、必ずバックエンドサーバーで作成してください。アプリのバイナリからAPI keyを抽出することは誰にでも可能です。

Mobile: Get Checkout URL

アプリはバックエンドを呼び出してcheckout URLを取得します。このリクエストは、サインイン中のユーザー自身のsession tokenで認証してください。各例では、userSessionTokenがそのtokenで、CheckoutResponseが独自のレスポンスタイプです。

iOS (Swift)
Android (Kotlin)
React Native (JavaScript)
Flutter (Dart)

func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
    let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
    
    let requestData: [String: Any] = [
        "productId": productId,
        "customerEmail": customerEmail,
        "customerName": customerName
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
    return response.checkout_url
}

suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
    val client = OkHttpClient()
    val requestBody = JSONObject().apply {
        put("productId", productId)
        put("customerEmail", customerEmail)
        put("customerName", customerName)
    }.toString().toRequestBody("application/json".toMediaType())
    
    val request = Request.Builder()
        .url("https://your-backend.com/api/create-checkout-session")
        .header("Authorization", "Bearer $userSessionToken")
        .post(requestBody)
        .build()
    
    val response = client.newCall(request).execute()
    val responseBody = response.body?.string()
    val jsonResponse = JSONObject(responseBody ?: "")
    return jsonResponse.getString("checkout_url")
}

const getCheckoutURL = async (productId, customerEmail, customerName) => {
  try {
    const response = await fetch('https://your-backend.com/api/create-checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userSessionToken}`,
      },
      body: JSON.stringify({
        productId,
        customerEmail,
        customerName
      })
    });
    
    const data = await response.json();
    return data.checkout_url;
  } catch (error) {
    console.error('Failed to get checkout URL:', error);
    throw error;
  }
};

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String> getCheckoutUrl({
  required String productId,
  required String customerEmail,
  required String customerName,
}) async {
  final response = await http.post(
    Uri.parse('https://your-backend.com/api/create-checkout-session'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $userSessionToken',
    },
    body: jsonEncode({
      'productId': productId,
      'customerEmail': customerEmail,
      'customerName': customerName,
    }),
  );

  if (response.statusCode != 200) {
    throw Exception('Failed to get checkout URL: ${response.statusCode}');
  }
  return jsonDecode(response.body)['checkout_url'] as String;
}

Security：アプリはDodo Payments APIを直接呼び出さず、必ずバックエンドとのみ通信します。

Mobile: Open Checkout in Browser

checkout URLをプラットフォームのシステムブラウザー画面で開きます。公式checkout SDKを使えば、この処理が自動的に行われ、型付きの結果が返されます。

Pick your mobile SDK

Android、iOS、React Native、Flutterのインストール手順とセットアップ方法。

Backend: Handle Payment Completion

バックエンドがpayment.succeededまたはsubscription.active webhookを受信したら、アクセス権を付与します。復帰URLの結果は、アプリの画面を更新する目的にのみ使用してください。

SDKを選択する

すべてのモバイルSDKは同じ契約に従います。1回のstart(...)呼び出しで、Dodo Paymentsのホスト型checkoutをプラットフォームのシステムブラウザー画面で開き、型付きCheckoutResultを返します。そのstatusはsucceeded、failed、cancelled、pending、またはexpiredになります。SDKがAPI keyを保持したりDodo Payments APIを呼び出したりすることはありません。4つすべてが放棄されたsessionの復旧に対応しています。

Android

com.dodopayments.api:checkout-androidはCustom Tabを開きます。minSdk 23が必要です。

iOS

dodopayments-mobile-sdk-iosはSFSafariViewControllerを開きます。iOS 16以降が必要です。

React Native

@dodopayments/react-native-checkoutは、両方のnative core上で動作するTurbo Moduleです。New Architectureを有効にしたReact Native 0.77以降が必要です。

Flutter

dodopayments_checkoutは、両方のnative core上で動作するPigeon channelです。Flutter 3.44以降が必要です。

返されるstatusはUI上のヒントであり、支払いの証明ではありません。すべての支払いは、payment.succeededまたはsubscription.active webhookからバックエンドで確認するか、API keyを使って取得してください。cancelledステータスは、復帰URLが到着する前に顧客がブラウザーを閉じたことを意味するため、支払いが成功している可能性があります。失敗として表示しないでください。

Callback URL Schemeの登録

4つのSDKはすべて、例としてmyapp://checkout/returnのように、選択したcustom URL schemeを通じてアプリへ制御を戻します。プラットフォームごとに1回登録してください。

Android
iOS
Expo

android/app/build.gradle

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

SDK独自のmanifestにはredirect activityがすでに宣言されているため、manifest XMLを追加する必要はありません。schemeはreturnUrlのschemeと一致させる必要があります。

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

iOSでは、受信URLをSDKへ転送する必要もあります。SFSafariViewControllerは自身の復帰URLを取得できないためです。正確なhandlerについては、iOSまたはReact Nativeのページを参照してください。

@dodopayments/react-native-checkoutには、prebuild中に両方のプラットフォームへschemeを登録するconfig pluginが含まれています。schemeオプションを渡してください。

app.json

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

schemeはreturnUrlのschemeと一致させ、expo.schemeとは異なる値にする必要があります。expo.schemeはExpoがMainActivityに登録します。詳細はReact Native SDKのページを参照してください。pluginはandroid/app/build.gradleのdefaultConfig { }ブロックを編集します。ファイルに標準のdefaultConfig { }ブロックがない場合は、Androidタブに示すようにplaceholderを手動で設定してください。pluginはdevelopment buildでのみ動作し、Expo Goでは動作しません。app.jsonを編集した後、npx expo prebuild --cleanを実行してください。

フローを自分で構築するには、checkout_urlをプラットフォームのシステムブラウザー画面（AndroidではCustom Tab、iOSではSFSafariViewController）で開き、return_urlへのナビゲーションをインターセプトして、クエリパラメータstatusとpayment_idを読み取ります。これらはSDKが自動的に行います。

埋め込み WebView 内で checkout を開かないでください（WKWebView または Android WebView）。 埋め込み WebView では 3-D Secure チャレンジや保存済みカードの自動入力が正常に動作せず、決済に失敗する顧客が増える可能性があります。SDK を使用するか、システムのブラウザー画面で checkout_url を開いてください。iOS では、Apple Pay を利用できるように、SFSafariViewController または ASWebAuthenticationSession、あるいはシステムブラウザーで開いてください。Android では、顧客のブラウザー上で動作する Custom Tab で開くことで、Google Pay を引き続き利用できます。

外観のカスタマイズ

すべてのSDKは、start(...)またはCheckoutParamsで任意のcustomizationパラメータを受け取ります。これはシステムブラウザー画面のtoolbar、button、ブラウザーの表示方法を制御します。checkoutページ独自のthemeは別に設定します。checkout session作成時に、サーバー上でcustomization.theme_configを使って設定します。オプションはプラットフォームごとに分類されています。AndroidのCustom TabとiOSのSFSafariViewControllerでは、利用できるnative controlが異なるためです。すべてのfieldは任意です。未設定のfieldには、プラットフォーム独自のデフォルト値が使用されます。

Android - Custom Tab

Toolbarの背景色。

Navigation barの色。

Navigation barの上に表示されるdividerの色。

'default' | 'back'

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

'start' | 'end'

Toolbarのどちら側にclose buttonを表示するか。

Toolbarのshare iconを表示します。

boolean

ToolbarでURLの下にpage titleを表示します。

boolean

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

boolean

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

boolean

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

'system' | 'light' | 'dark'

デバイスのシステム設定にかかわらず、lightまたはdark appearanceを強制します。

iOS - SFSafariViewController

'done' | 'close' | 'cancel'

dismiss buttonのlabelまたはicon。

'pageSheet' | 'fullScreen'

デフォルト:"pageSheet"

pageSheetは、顧客がスワイプして閉じられるcardとしてcheckoutを表示します。fullScreenは画面全体を覆います。

boolean

スクロール時にtoolbarを折りたたみます。効果があるのはpresentationStyleがfullScreenの場合のみです。pageSheetでは、barは固定されたままです。

'system' | 'light' | 'dark'

デバイスのシステム設定にかかわらず、lightまたはdark appearanceを強制します。

以下の例では、Androidでtoolbarの色とclose buttonを設定し、iOSでは全画面のdark表示を設定します。React NativeとFlutterでは、それぞれ別のandroidおよびios option groupを使用します。native SDKでは各プラットフォーム固有のoptionのみを使用します。

React Native
Flutter
Android (Kotlin)
iOS (Swift)

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

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

val result = DodoCheckout.start(
    activity,
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
        )
    )
) { event -> }

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

Checkoutページのカスタマイズ

checkoutページ自体（表示するfield、theme、表示する決済手段）は、checkout session作成時にサーバーで設定します。外観のカスタマイズで説明するのは、その周囲のブラウザー画面だけです。以下のパラメータは、モバイルでのコンバージョンに最も大きな効果があります。これらのパラメータは、checkout session のリクエスト内の3か所、つまりトップレベル、customization、または feature_flags に配置します。配置先列には、それぞれのパラメータを配置するオブジェクトが示されています。各パラメータは表示されたオブジェクトに配置してください。誤ったオブジェクトに配置しても効果はありません。

Parameter	配置先	モバイルでのメリット	Default	設定するタイミング
`show_order_details`	`customization`	`false`で注文概要を折りたたみ、画面上部に決済手段を表示	`true`	モバイルで`false`を設定し、決済手段をスクロールせずに表示
`minimal_address`	top-level	完全な住所項目の代わりにpostcodeのみ、または必要な国ではregionのみを収集	`false`	多くのモバイルcheckoutで設定。fieldが1つ増えるごとに顧客の入力負担が増えるため
`theme`	`customization`	checkoutページを`light`、`dark`、または`system`に設定	Business theme	`"system"`でデバイス設定に従う
`theme_config`	`customization`	brand palette、font、border radius、pay button labelを設定	None	checkoutをアプリの一部のように見せる場合
`force_language`	`customization`	ブラウザーの言語検出を上書き。例：`en`または`es`	Auto-detect	ブラウザーではなくアプリの言語から設定
`show_on_demand_tag`	`customization`	checkoutページのon-demand labelを表示または非表示	`true`	カード保存のためだけにon-demand billingを使う場合は`false`を設定
`show_saved_payment_methods`	top-level	returning customerの保存済み決済手段を表示	`false`	過去に支払ったことのあるサインイン済み顧客向け
`allow_discount_code`	`feature_flags`	discount code fieldを表示	`true`	フォームを短くするために`false`を設定
`allow_currency_selection`	`feature_flags`	顧客がbilling currencyを変更可能	`true`	`billing_currency`でcurrencyを固定する場合に`false`を設定
`redirect_immediately`	`feature_flags`	success pageを省略し、`return_url`へredirect	`false`	支払い直後に顧客をアプリへ戻す場合
`confirm`	top-level	作成時にsession detailsを確定。必須データがない場合、APIはerrorを返す	`false`	ワンクリックcheckoutで`payment_method_id`と併用
`short_link`	top-level	短縮されたcheckout URLを返す	`false`	URLをpush notificationまたはSMSに収める必要がある場合
`payment_method_id`	top-level	保存済み決済手段に課金。`confirm: true`と既存の`customer_id`が必要	None	ワンクリックcheckout向け
`allowed_payment_method_types`	top-level	checkoutを指定した決済手段に限定。対象のmethodでも利用可能な場合にのみ表示	All enabled	商品に適したmethodだけを表示する場合

**billing_currencyとbilling_address.countryは必ず一緒に渡してください。**どちらか一方を省略すると、Adaptive Currencyは顧客のIPアドレスからbilling currencyを選択できます。例えば、米国の顧客が欧州へ旅行中でbilling countryが設定されていない場合、EURで請求される可能性があります。

モバイルコンバージョンへの最大の効果：show_order_details: falseとminimal_address: trueを設定します。これらを組み合わせると、決済手段がスクロールせずに表示され、住所fieldの大部分が削除されます。

チェックアウトの比較：注文詳細を展開（fieldはスクロール後に表示）した場合と折りたたみ（上部に表示）した場合 — show_order_details: false moves the contact and payment fields above the fold, instead of behind the order summary.

完全なstreet、city、state fieldの代わりにpostcodeのみを収集するには、minimal_address: trueを設定します。

チェックアウトの比較：完全なbilling address formとpostcodeのみの場合 — minimal_address: true reduces the billing address to a single postcode field.

checkoutがデバイスのlightまたはdark mode設定に従うように、theme: "system"を設定します。

チェックアウトの比較：同じページをlight modeとdark modeで表示 — With theme: system, the checkout follows the device's light or dark appearance automatically.

**利用できる決済手段は商品タイプによって異なります。**Apple PayとCash App Payは、ゼロではない金額のrecurring subscriptionに対応しています。one-time paymentでは、ビジネスで有効にしたすべての決済手段を利用できます。Payment Methodsを参照してください。

Full checkout session parameter reference

Checkout Sessions guideに記載された、すべてのparameter、type、default value。

モバイル最適化レシピ

各レシピは、バックエンドから送信する完全なcheckout session requestです。シナリオに合うものを選び、product IDを自分のものに置き換えてください。Node.jsとPythonのclientは最初のレシピで設定し、その他のレシピで再利用します。

Minimal Mobile Checkout - fastest path to payment

最も短いフォームにする場合は、このレシピを使用します。決済手段を上部に表示し、住所はpostcodeのみ、discount fieldは表示せず、themeはデバイスに従います。

Node.js SDK
Python SDK

import DodoPayments from 'dodopayments';

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

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  return_url: 'myapp://checkout/success',
  cancel_url: 'myapp://checkout/cancelled',
  billing_currency: 'USD',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  feature_flags: {
    allow_discount_code: false,
    allow_currency_selection: false,
  },
});

console.log(session.checkout_url);

import os
import dodopayments

client = dodopayments.DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    return_url="myapp://checkout/success",
    cancel_url="myapp://checkout/cancelled",
    billing_currency="USD",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "system",
    },
    feature_flags={
        "allow_discount_code": False,
        "allow_currency_selection": False,
    },
)

print(session.checkout_url)

利用可能なすべてのparameterとdefaultについては、Checkout Sessionsを参照してください。

Branded Mobile Checkout - custom colors, fonts, and button label

checkoutページをアプリの一部のように見せる必要がある場合は、このレシピを使用します。brand color、border radius、custom pay button labelを設定します。

theme_configでcustom dark navy paletteを適用したブランド付きモバイルcheckout

Node.js SDK
Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'dark',
    theme_config: {
      dark: {
        button_primary: '#7C3AED',
        button_primary_hover: '#6D28D9',
        button_text_primary: '#FFFFFF',
        bg_primary: '#1A1A2E',
        bg_secondary: '#16213E',
        text_primary: '#E2E8F0',
      },
      pay_button_text: 'Complete Purchase',
      radius: '8px',
    },
  },
});

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "dark",
        "theme_config": {
            "dark": {
                "button_primary": "#7C3AED",
                "button_primary_hover": "#6D28D9",
                "button_text_primary": "#FFFFFF",
                "bg_primary": "#1A1A2E",
                "bg_secondary": "#16213E",
                "text_primary": "#E2E8F0",
            },
            "pay_button_text": "Complete Purchase",
            "radius": "8px",
        },
    },
)

theme_configは、darkとlightの別々のobjectを受け取るため、paletteはデバイスのappearanceに従います。すべてのcolor keyとfont optionについては、Checkout Sessionsを参照してください。

One-Click Returning Customer - saved card, instant confirmation

過去に支払ったことのあるサインイン済み顧客には、このレシピを使用します。顧客のcustomer_id、保存済みのpayment_method_id、confirm: trueを渡してcheckout formを省略します。payment_method_idを指定すると、sessionは保存済みのmethodに直接課金し、checkout_urlを返さないため、アプリで開くものはありません。結果はwebhookから取得します。

Node.js SDK
Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { customer_id: 'cus_returning_customer_id' },
  // confirm: true requires a complete billing address
  billing_address: {
    country: 'US',
    state: 'CA',
    city: 'San Francisco',
    street: '123 Main St',
    zipcode: '94102',
  },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  payment_method_id: 'pm_saved_payment_method_id',
  confirm: true,
  show_saved_payment_methods: true,           // top-level parameter
  feature_flags: { redirect_immediately: true },
});

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    # confirm=True requires a complete billing address
    billing_address={
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "street": "123 Main St",
        "zipcode": "94102",
    },
    billing_currency="USD",
    return_url="myapp://checkout/success",
    payment_method_id="pm_saved_payment_method_id",
    confirm=True,
    show_saved_payment_methods=True,           # top-level parameter
    feature_flags={"redirect_immediately": True},
)

バックエンドがpayment.succeeded webhookを受信したら、アクセス権を付与します。アプリが表示するstatusはUI上のヒントにすぎません。

Subscription with Free Trial - trial before first charge

初回請求前に無料trialを提供するsubscription productには、このレシピを使用します。trial_period_daysで、このsessionのtrial期間を設定します。

Node.js SDK
Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://subscription/activated',
  cancel_url: 'myapp://subscription/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  subscription_data: { trial_period_days: 14 },
});

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://subscription/activated",
    cancel_url="myapp://subscription/cancelled",
    minimal_address=True,
    customization={"show_order_details": False, "theme": "system"},
    subscription_data={"trial_period_days": 14},
)

モバイルSDKが返ったときではなく、バックエンドがsubscription.active webhookを受信したときにアクセス権を付与します。完全なwebhookフローについては、Subscription Integration Guideを参照してください。

On-Demand Mandate - save a card for future variable charges

wallet top-up、pay-as-you-go、BNPLなど、後で請求するために顧客の決済手段を保存する場合は、このレシピを使用します。subscription labelは表示しません。顧客は一度決済手段を承認し、後から変動する金額を請求します。

使用量に応じて課金するアプリは、このパターンに従います。例えば、占星術アプリは固定スケジュールではなく、各セッションのたびに事前承認済みカードへ請求します。

Node.js SDK
Python SDK

// Step 1: Authorize the mandate (no charge yet)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://mandate/authorized',
  cancel_url: 'myapp://mandate/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    show_on_demand_tag: false, // hides the "on-demand" / "subscription" label
    theme: 'system',
  },
  subscription_data: {
    on_demand: { mandate_only: true },
  },
});

// Step 2: Later, charge any amount using the subscription ID
// (received via the subscription.active webhook after mandate authorization)
// await client.subscriptions.charge(subscriptionId, {
//   product_price: 2000,         // $20.00 in cents
//   product_currency: 'USD',
//   product_description: 'Session credits',
// });

# Step 1: Authorize the mandate (no charge yet)
session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://mandate/authorized",
    cancel_url="myapp://mandate/cancelled",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "show_on_demand_tag": False,  # hides the "on-demand" / "subscription" label
        "theme": "system",
    },
    subscription_data={"on_demand": {"mandate_only": True}},
)

# Step 2: Later, charge any amount using the subscription ID
# client.subscriptions.charge(
#     subscription_id,
#     product_price=2000,  # $20.00 in cents
#     product_currency="USD",
#     product_description="Session credits",
# )

オンデマンド請求は、最小通貨単位で少なくとも100（USDでは$1.00）である必要があります。APIは、"product_price: value out of range"を伴う低いproduct_priceを拒否します。請求せずに承認するには、上記のようにmandate_only: trueを使用し、後で少なくともその最小額を請求してください。

完全な請求フロー、webhook event、retry policyについては、On-Demand Subscriptionsを参照してください。

モバイルからのサブスクリプションフロー

モバイルアプリは、one-time paymentと同じcheckout sessionフローでsubscriptionを開始します。SDKがホスト型checkoutを開き、顧客がsubscribeし、アプリがディープリンクからの復帰を処理します。subscription lifecycleの残りはバックエンドが管理します。

通常のRecurring Subscription

月次や年次など固定間隔で請求するには、subscription productとディープリンクreturn_urlを指定してcheckout sessionを作成します。subscription開始時に、バックエンドがsubscription.activeを受信します。

Apple PayとCash App Payは、ゼロではない金額のrecurring subscriptionに対応しています。

完全なバックエンドwebhookフローについては、Subscription Integration Guideを参照してください。

On-Demand Subscription

on-demand subscriptionは顧客の決済手段を一度承認し、後から変動する金額を請求できるようにします。wallet top-up、pay-as-you-go、事前に金額が分からない請求に使用します。完全なrequest bodyについては、On-Demand Mandateレシピを参照してください。モバイルでは、次の点に注意してください。

show_on_demand_tag: falseを設定し、checkoutページにsubscriptionまたはon-demandの文言を表示しないようにします。top-up用にカードを保存する顧客は、subscription termsを想定していません。
顧客がmandateを承認した後、バックエンドはsubscription.activeを受信します。後続の請求ではすべてsubscription_idを使用するため、保存してください。

オンデマンド請求は、最小通貨単位で少なくとも100である必要があります。APIは低い金額を"product_price: value out of range"とともに拒否します。少なくともその最小額を請求するか、mandate_only: trueを使って請求せずに承認し、後で最初の金額を回収してください。**請求を短時間に連続してretryしないでください。**同じsubscriptionで前の請求が処理中の場合、新しい請求は"Cannot create new charge as previous payment is not successful yet"で失敗します。これはインドの決済手段（UPI、インドのdebit cardとcredit card）で最もよく発生します。請求開始から48時間後に引き落としが行われるためです。retryする前に、前の請求が完了していることを確認してください。

請求endpoint、webhook event、retry policyについては、On-Demand Subscriptionsを参照してください。

Free Trial付きSubscription

初回請求前にtrialを提供するには、checkout sessionでsubscription_data.trial_period_daysを渡します。顧客はsignup時に決済手段を承認し、Dodo Paymentsはtrial終了時にその手段へ請求します。完全なrequest bodyについては、Subscription with Free Trialレシピを参照してください。

UpgradeとDowngrade

バックエンドは新しいcheckout sessionではなく、APIを通じてplanを変更します。Dodo Paymentsは、選択したproration modeで日割り計算を行います。顧客が自分でplanを変更できるようにするには、Customer Portalへリンクしてください。

Subscription Integration Guide

バックエンドの設定：webhookフロー、アクセス権の付与、キャンセル。

On-Demand Subscriptions

Mandateの承認、変動請求、retry policy。

Upgrade / Downgrade

Proration mode、plan変更、seat調整。

Customer Portal

顧客向けのセルフサービスsubscription管理。

Checkout離脱の削減

小さな画面では、すべてのフォームフィールドへの入力により多くの手間がかかります。以下の checkout session 設定により、フォームを短くして離脱を減らせます。

Formの最適化

次の設定で、モバイルのcheckout formを短縮できます。

Setting	推奨値	効果
`show_order_details`	`false`	注文概要を折りたたみ、決済手段を上部に表示
`minimal_address`	`true`	street、city、stateの代わりにpostcodeのみ、または必要な地域のみを要求
`show_saved_payment_methods`	`true`	returning customerに保存済み決済手段を表示
`allow_discount_code`	`false`	discount code fieldを削除
`theme`	`"system"`	デバイスのlightまたはdark設定に従う
`force_language`	アプリの言語	checkoutがブラウザーの言語を使用しないようにする

顧客データの事前入力

事前入力する各fieldは、顧客が入力する必要のないfieldになります。

新規顧客：auth sessionからcustomer.emailとcustomer.nameを設定します。
Returning customer：顧客の保存済みdetailsを使用するためにcustomer.customer_idを設定します。
Currency：billing_currencyとbilling_address.countryを一緒に渡します。

Recovery Tools

Recovery toolは、checkoutまたはrenewalが完了しなかった顧客を呼び戻します。

Abandoned Cart Recovery

abandonedまたはfailed checkout向けのemail sequence。

Payment Retries

失敗したsubscription renewalの自動retry。

Subscription Dunning

支払いに失敗したsubscriptionを復旧するemail。

Recovery Overview

すべてのrecovery toolと、それによって回収されたrevenue。

ベストプラクティス

セキュリティ: API key をアプリに含めないでください。バックエンドで checkout session を作成し、checkout_url のみをアプリに渡します。
権限: CheckoutResult.status は UI のヒントとして扱ってください。バックエンドで決済を確認した後にのみアクセスを許可します。
ユーザー体験: バックエンドが session を作成している間は、読み込み状態を表示します。cancelled を失敗として扱わないでください。決済がすでに成功している可能性があります。
テスト: test mode と test cards を使用し、シミュレーターだけでなく実機でも return URL の往復を確認します。
コンバージョン: show_order_details: false と minimal_address: true を設定します。これらを組み合わせることで、支払い方法がスクロールせずに表示され、住所フィールドの大部分が削除されます。
通貨: billing_currency と billing_address.country の両方を渡します。どちらか一方を省略すると、Adaptive Currency が顧客の IP アドレスから請求通貨を選択することがあります。
オンデマンド請求: オンデマンドサブスクリプションでカードの保存のみを行う場合は、show_on_demand_tag: false を設定します。ウォレットにチャージする顧客は、サブスクリプションに関する文言を想定していません。
リカバリー: ダッシュボードで Abandoned Cart Recovery を有効にすると、checkout を完了しなかった顧客にメールを送信できます。

トラブルシューティング

よくある問題

Callback が届かない: returnUrl の scheme は、登録した scheme と一致している必要があります。Android では、これは dodoCallbackScheme の manifest placeholder です。iOS では、Info.plist の URL type です。React Native と Flutter のアプリでは両方が必要で、Expo では config plugin が両方を設定します。
checkout がアプリではなくブラウザーに戻る（iOS）: アプリが受信した URL を転送していません。.onOpenURL、scene(_:openURLContexts:)、または React Native の Linking listener から DodoCheckout.handleOpenURL(url) を呼び出してください。
Android で PLATFORM_ERROR: 最も一般的な原因は scheme の不一致です。また、MainActivity が android:taskAffinity=""（flutter create のデフォルト値）を設定している場合にも発生します。この設定により、一部の Android OEM ビルドで進行中の checkout が失われることがあります。
ALREADY_IN_PROGRESS: checkout がまだ開いています。別の checkout を開始する前に、前の checkout が完了するまで待つか、閉じてください。
未解決の placeholder によりビルドが失敗する: Android SDK を追加しましたが、manifestPlaceholders["dodoCallbackScheme"] を設定していません。
決済は成功したがアクセスが許可されない: アプリがモバイルの結果からアクセスを許可しています。代わりに payment.succeeded または subscription.active webhook からアクセスを許可してください。
モバイルで Apple Pay または Google Pay が表示されない: checkout が埋め込み WebView（WKWebView または Android WebView）内で読み込まれていないか確認してください。SDK、またはシステムのブラウザー画面で開きます。Android では Custom Tab、iOS では SFSafariViewController または ASWebAuthenticationSession を使用してください。

追加リソース

Contact Support

ご質問やサポートについては、support@dodopayments.com までメールでお問い合わせください。

Quick Start

Platform Examples

Checkout Customization

Mobile Recipes

​前提条件

​統合ワークフロー

Checkout Session API Docs

Pick your mobile SDK

​SDKを選択する

Android

iOS

React Native

Flutter

​Callback URL Schemeの登録

​外観のカスタマイズ

​Checkoutページのカスタマイズ

Full checkout session parameter reference

​モバイル最適化レシピ

​モバイルからのサブスクリプションフロー

​通常のRecurring Subscription

​On-Demand Subscription

​Free Trial付きSubscription

​UpgradeとDowngrade

Subscription Integration Guide

On-Demand Subscriptions

Upgrade / Downgrade

Customer Portal

​Checkout離脱の削減

​Formの最適化

​顧客データの事前入力

​Recovery Tools

Abandoned Cart Recovery

Payment Retries

Subscription Dunning

Recovery Overview

​ベストプラクティス

​トラブルシューティング

​よくある問題

​追加リソース

Contact Support

前提条件

統合ワークフロー

SDKを選択する

Callback URL Schemeの登録

外観のカスタマイズ

Checkoutページのカスタマイズ

モバイル最適化レシピ

モバイルからのサブスクリプションフロー

通常のRecurring Subscription

On-Demand Subscription

Free Trial付きSubscription

UpgradeとDowngrade

Checkout離脱の削減

Formの最適化

顧客データの事前入力

Recovery Tools

ベストプラクティス

トラブルシューティング

よくある問題

追加リソース