Flutter

このページでは、pub.dev にある公式の Dodo Payments Flutter package、dodopayments_checkout について説明します。別途、コミュニティが開発した package もあります。詳しくは Community Projectsをご覧ください。

Checkout Sessions API

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

Mobile Integration Guide

この SDK がモバイル決済フロー全体の中でどのように機能するかを確認します。

dodopayments_checkout は、iOS では SFSafariViewController で、Android では Custom Tab で Dodo Payments hosted checkout を開き、型付き CheckoutResult を返します。スタンドアロンの iOS SDK および Android SDK と同じ native code を使用し、checkout のロジックはすべてその native code にあります。Dart layer は、型付き Pigeon channel を介して各呼び出しを渡します。この package は API key を保持せず、Dodo Payments API を呼び出すこともありません。 要件: Dart 3.12 以降を備えた Flutter 3.44 以降、iOS 16 以降、および Android minSdk 23。

インストール

Add the Dependency

package を pubspec.yaml に追加します。

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.1.0

Appearance customizationには version 1.1.0 以降が必要です。Android plugin はデフォルトで Android SDK 35 に対してコンパイルされます。別の plugin がより高い compileSdk を必要とする場合は、アプリの gradle.properties に dodoCompileSdk を設定します。

オペレーティングシステムが checkout の return URL をアプリに戻せるよう、URL scheme を登録します。この scheme を SDK に渡す returnUrl で使用し、バックエンドが session を作成するときに checkout session の return_url に同じ URL を設定します。この URL が実際のページを読み込む必要はありません。

iOS
Android

ios/Runner/Info.plist に scheme の URL type を追加します。

ios/Runner/Info.plist

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

SFSafariViewController は自身の return URL を捕捉できないため、iOS は代わりにその URL をアプリで開きます。受信したすべての URL を SDK に転送します。たとえば app_linksから転送できます。

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

// url is the incoming link as a String. For a Uri from app_links, pass uri.toString().
DodoCheckout.instance.handleOpenURL(url);

すべての URL を転送できます。handleOpenURL は、進行中の checkout の returnUrl に一致する URL に対してのみ動作し、その URL に対して true を解決します。それ以外の URL については false を解決します。Android では常に false を解決します。

android/app/build.gradle.kts に callback scheme を Gradle manifest placeholder として設定します。同じ行は Groovy build.gradle file でも使用できます。

android/app/build.gradle.kts

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

MainActivity が android:taskAffinity=""（flutter create template のデフォルト）を設定している場合は、それを削除するか、SDK の activities に同じ affinity を指定します。そうしないと、一部の OEM Android build で進行中の checkout が失われ、PLATFORM_ERROR とメッセージ「Checkout was launched without its parameters.」が発生することがあります。

使用方法

バックエンドから取得した checkout_url を使用して DodoCheckout.instance.start を呼び出します。

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

// showSuccess(), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Installation)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: await reconcileAbandonedSession(); // outcome unknown, not a failure
  case CheckoutStatus.pending:   await reconcileAbandonedSession();
  case CheckoutStatus.expired:   showExpired();
}

onEvent は、type が CheckoutEventType.opened、returnReceived、または closed である event を受け取ります。これらは logging のみに使用し、結果の判定には決して使用しないでください。

結果の意味

SDK は return URL の query parameters から CheckoutResult を構築します。

result.status は UI hint であり、支払いの証明ではありません。すべての payment は、バックエンドから payment.succeeded または subscription.active webhook を使用して確認してください。

CheckoutStatus

必須

次の 5 つの値のいずれかです。

succeeded: return URL に status=succeeded（one-time payment）または status=active（subscription）が含まれています。
failed: payment が declined されました（status=failed）。
cancelled: return URL が届く前に customer が browser view を閉じました。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 checkout に設定されます。

List<String>?

license_key query parameter。checkout に license key products が含まれる場合に設定されます。

String?

email query parameter。checkout が email address を取得する場合に設定されます。

Map<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 のカスタマイズ

checkout browser の toolbar、buttons、color scheme を変更するには、BrowserCustomization を CheckoutParams 上の customization として渡します。Android Custom Tabs と iOS SFSafariViewController では公開される native controls が異なるため、options は AndroidBrowserOptions と IosBrowserOptions に分かれています。各 platform はもう一方の options を無視します。すべての field は optional で、デフォルトは null です。null field では、SDK はその option を設定せず、platform 独自の default が適用されます。

Android — Custom Tab

Toolbar の background color。

Navigation bar の color。

Navigation bar の上にある divider の color。

CloseButtonStyle?

standard は system の「X」icon を表示します。back は SDK が描画する back arrow を表示します。

CloseButtonPosition?

close button が表示される toolbar の側：start または end。

toolbar の share icon を表示します。false は非表示にします。

bool?

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

bool?

page の scroll に合わせて toolbar を自動的に非表示にします。

bool?

overflow menu に「このページをブックマーク」を表示します。

bool?

overflow menu に「ページをダウンロード」を表示します。

BrowserColorScheme?

light または dark は、device の system setting にかかわらず、その appearance を強制します。system は system setting に従います。

iOS — SFSafariViewController

DismissButtonStyle?

dismiss button の style：done、close、または cancel。iOS は label と icon のどちらとして render するかを決定します。

PresentationStyle?

pageSheet（この null を指定しない場合に使用）は、customer が swipe down して dismiss できる card を表示します。fullScreen は画面全体を覆います。

bool?

page の scroll に合わせて toolbar を collapse できるようにします。効果があるのは presentationStyle が fullScreen の場合だけです。pageSheet では、この setting にかかわらず bars は固定されたままです。

BrowserColorScheme?

light または dark は、device の system setting にかかわらず、その appearance を強制します。system は system setting に従います。

iOS には toolbar color option がありません。基盤となる SFSafariViewController の tint properties は iOS 26 以降 deprecated であるためです。

import 'package:dodopayments_checkout/dodopayments_checkout.dart';
import 'package:flutter/material.dart' show Color;

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,
      ),
    ),
  ),
);

Errors

start は、誤用または platform failure の場合にのみ CheckoutException を throw します。理由は code（CheckoutErrorCode）から読み取ります。native code の string は nativeCode にあります。 customer によるキャンセル、または declined payment は常に result であり、exception ではありません。

invalidCheckoutUrl（INVALID_CHECKOUT_URL）：checkoutUrl は、checkout.dodopayments.com または test.checkout.dodopayments.com 上の /session/ で始まる checkout session URL ではありません。
invalidReturnUrl（INVALID_RETURN_URL）：returnUrl は scheme と host を持つ absolute URL ではありません。
alreadyInProgress（ALREADY_IN_PROGRESS）：別の checkout が実行中です。同時に実行できる checkout は 1 つだけです。
platformError（PLATFORM_ERROR）：予期しない platform failure です。不明な native errors もこの code にマッピングされます。

Abandoned Sessions

native SDK は checkout の開始時に checkout session を記録し、checkout が succeeded、failed、または expired で終了した場合にのみ、その記録を消去します。checkout 中に app が終了した場合や、cancelled または pending result の後も記録は残ります。次回の launch 時、および cancelled または pending result のたびに確認してください。

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // Ask your backend for the outcome of abandoned.sessionId, and show it.
  // Clear the record only after the outcome is final:
  await DodoCheckout.instance.clearAbandonedSession();
}

abandoned.sessionId は checkout session ID で、cks_ で始まります。abandoned.createdAt は checkout が開始された DateTime です。バックエンドでは Get Checkout Session を使用して session を lookup できます。この API は payment_id と payment_status を返します。payment が final status に達するまでは、failed ではなく pending として扱ってください。

Mobile Integration Guide

Android、iOS、React Native で同じ contract を使用します。

Community Projects

別途、コミュニティが開発した Flutter package もあります。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

インストール

使用方法

結果の意味

Payment の確認

Webhooks

Get Payment Detail

Appearance のカスタマイズ

Errors

Abandoned Sessions

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​インストール

​使用方法

​結果の意味

​Payment の確認

Webhooks

Get Payment Detail

​Appearance のカスタマイズ

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

Community Projects

インストール

使用方法

結果の意味

Payment の確認

Appearance のカスタマイズ

Errors

Abandoned Sessions

Related