iOS

このページでは、Swift用の公式Dodo Payments iOSチェックアウトSDKについて説明します。Dodo Paymentsのホスト型チェックアウトをネイティブブラウザビューで開き、型付きの結果を返します。

Checkout Sessions API

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

Mobile Integration Guide

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

iOS SDKはDodo Paymentsのホスト型チェックアウトをSFSafariViewControllerで開き、顧客がチェックアウトを完了または離脱したときに型付きのCheckoutResultを返します。APIキーを保持せず、ネットワーク通信コードも含まれていないため、Dodo Payments APIを呼び出すことはありません。チェックアウトはブラウザビューで実行されます。SDKはそのビューを表示および閉じ、リターンURLから結果を読み取ります。 要件: iOS 16以降、およびSwift 6.2以降（パッケージではswift-tools-version: 6.2が宣言されています）。SDKにサードパーティ依存関係はありません。

インストール

Add the Package

Xcodeで File → Add Package Dependencies に移動し、パッケージURLを入力します。

https://github.com/dodopayments/dodopayments-mobile-sdk-ios

バージョン1.1.0以降を選択します。外観のカスタマイズには1.1.0が必要です。代わりにPackage.swiftへパッケージを追加するには、次の依存関係を追加します。

Package.swift

.package(url: "https://github.com/dodopayments/dodopayments-mobile-sdk-ios", from: "1.1.0")

ライブラリプロダクトはDodoCheckoutです。

iOSがチェックアウトのリターンURLをアプリに戻せるよう、URLスキームを登録します。Info.plistにURLタイプを追加します。

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 からURLタイプを追加することもできます。SDKに渡すreturnUrlでこのスキームを使用します。たとえばmyapp://checkout/returnです。バックエンドでセッションを作成するときは、チェックアウトセッションのreturn_urlに同じURLを設定します。SDKはスキーム、ホスト、パスに基づいてリターンURLを照合します。URLが実際のページを読み込む必要はありません。

使用方法

DodoCheckout.startはメインアクター上で実行されるasync関数です。バックエンドが返すcheckout_urlから構築したURLとして、checkoutUrlを渡します。

import DodoCheckout

// showSuccess(_:), showFailure(), showExpired(), and reconcileAbandonedSession()
// are your own functions. See Abandoned Sessions for what to reconcile.
let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,   // from your backend's checkout session
    returnUrl: URL(string: "myapp://checkout/return")!,
    onEvent: { event in print(event.name) }  // logging only
)

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

onEventは.opened、.returnReceived、.closedイベントを受け取ります。それらのname値は、checkout.opened、checkout.return_received、checkout.closedです。イベントはロギングにのみ使用し、結果の判断には決して使用しないでください。

リターンURLの転送

SFSafariViewControllerは自身のリターンURLを捕捉できないため、iOSは代わりにアプリでURLを開きます。受信するすべてのURLをDodoCheckout.handleOpenURL(_:)に転送します。シーンを使用しないアプリでは、アプリデリゲートのapplication(_:open:options:)から呼び出します。

SwiftUI
SceneDelegate

.onOpenURL { url in
    DodoCheckout.handleOpenURL(url)
}

SceneDelegate.swift

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    DodoCheckout.handleOpenURL(url)
}

すべてのURLを転送できます。handleOpenURLは、進行中のチェックアウトのreturnUrlに一致するURLに対してのみ処理を行い、そのURLに対してtrueを返します。それ以外のURLにはfalseを返すため、そのURLはアプリ側で処理してください。

結果の意味

SDKはリターンURLのクエリパラメータからCheckoutResultを構築します。

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

CheckoutStatus

必須

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

succeeded: リターンURLにstatus=succeeded（単発決済）またはstatus=active（サブスクリプション）が含まれています。
failed: 支払いが拒否されました（status=failed）。
cancelled: リターンURLが到着する前に顧客がシートを閉じました。SDKは結果を把握できず、支払いが成功している可能性もあるため、失敗画面を表示しないでください。代わりに放棄されたセッションを照合してください。
pending: 支払いが後で確定します（status=processingまたは任意のrequires_*値）。またはstatusパラメータがないか、認識されませんでした。cancelledと同様に照合してください。
expired: チェックアウトセッションの有効期限が切れました（status=expired）。

String?

リターンURLにpayment_idクエリパラメータが含まれている場合、その値です。UIに表示できますが、アクセス権の付与には使用しないでください。支払いの確認を参照してください。

String?

subscription_idクエリパラメータです。サブスクリプションのチェックアウトで設定されます。

[String]?

license_keyクエリパラメータです。チェックアウトにライセンスキー商品が含まれる場合に設定されます。

String?

emailクエリパラメータです。チェックアウトでメールアドレスを取得するときに設定されます。

[String: String]

リターンURLに含まれるすべてのクエリパラメータをそのまま保持します。

支払いの確認

Webhooks

支払いが成功したとき、またはサブスクリプションが有効になったとき、Dodo Paymentsはバックエンドを呼び出します。

Get Payment Detail

シークレットキーを使用してpaymentIdを検索し、ステータスを確認します。

これらのいずれかによって支払いが確認された後にのみアクセス権を付与してください。result.statusだけに依存しないでください。

外観のカスタマイズ

シートの閉じるボタン、表示スタイル、カラースキームを変更するには、BrowserCustomizationをcustomizationとしてstart(...)に渡します。すべてのフィールドは任意です。nilフィールドでは、SDKはそのオプションを設定せず、iOS独自のデフォルトが適用されます。例外はpresentationStyleで、nilはpageSheetを意味します。

DismissButtonStyle?

閉じるボタンのスタイルです。done、close、またはcancelを指定します。ラベルとして表示するかアイコンとして表示するかはiOSが決定します。

PresentationStyle?

pageSheet（デフォルト）は、顧客が下にスワイプして閉じられるカードを表示します。fullScreenは画面全体を覆い、閉じるジェスチャーはありません。

Bool?

ページのスクロールに合わせてツールバーを折りたためるようにします。効果があるのはpresentationStyleがfullScreenの場合のみです。pageSheetでは、この設定に関係なくバーは固定されたままです。

ColorScheme?

lightまたはdarkを指定すると、デバイスのシステム設定に関係なく、その外観が適用されます。systemはシステム設定に従います。このオプションでテーマが変更されるのは、ページ周辺のネイティブコントロールのみです。チェックアウトページ自体のライトモードまたはダークモードはチェックアウトセッションのcustomization.themeから決まり、色はcustomization.theme_configから決まります。

iOSにはツールバーの色を設定するオプションがありません。基盤となるSFSafariViewControllerのtintプロパティはiOS 26以降非推奨です。

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

エラー

startは、誤った使用またはプラットフォーム障害の場合にのみCheckoutErrorをスローします。理由はerror.codeから読み取ります。顧客によるキャンセルや支払いの拒否は常に結果として返され、スローされるエラーではありません。

invalidCheckoutUrl（INVALID_CHECKOUT_URL）: checkoutUrlは、checkout.dodopayments.comまたはtest.checkout.dodopayments.com上の/session/で始まるパスを持つ、httpsチェックアウトセッションURLではありません。
invalidReturnUrl（INVALID_RETURN_URL）: returnUrlはスキームとホストを持つ絶対URLではありません。
alreadyInProgress（ALREADY_IN_PROGRESS）: 別のチェックアウトが実行中です。同時に実行できるチェックアウトは1つだけです。
platformError（PLATFORM_ERROR）: 表示元のビューコントローラーが存在しないなど、予期しないプラットフォーム障害です。

エラーがスローされた後も、放棄されたセッションを確認してください。シートの表示が確認されなかった場合、チェックアウトがまだ開いている可能性があるため、SDKはセッションを記録として保持します。例外はalreadyInProgressです。その場合、見つかった記録は実行中のチェックアウトに属します。

放棄されたセッション

SDKはチェックアウトを表示した時点でチェックアウトセッションを記録し、チェックアウトがsucceeded、failed、またはexpiredで終了した場合にのみ記録を削除します。チェックアウト中にアプリが終了した場合や、cancelledまたはpendingの結果が返された後も、記録は残ります。次回起動時、およびcancelledまたはpendingの結果が返るたびに確認してください。

import DodoCheckout

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

abandoned.sessionIdは、cks_で始まるチェックアウトセッションIDです。abandoned.createdAtは、チェックアウトが開始されたDateです。バックエンドではGet Checkout Sessionを使用してセッションを検索できます。これによりpayment_idとpayment_statusが返されます。支払いが最終ステータスに到達するまでは、失敗ではなく保留中として扱ってください。

Mobile Integration Guide

Android、React Native、Flutter向けの同じコントラクトです。

React Native SDK

iOSで同じSwiftコアをラップします。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

インストール

使用方法

リターンURLの転送

結果の意味

支払いの確認

Webhooks

Get Payment Detail

外観のカスタマイズ

エラー

放棄されたセッション

関連情報

Mobile Integration Guide

React Native SDK

Checkout Sessions API

Mobile Integration Guide

​インストール

​使用方法

​リターンURLの転送

​結果の意味

​支払いの確認

Webhooks

Get Payment Detail

​外観のカスタマイズ

​エラー

​放棄されたセッション

​関連情報

Mobile Integration Guide

React Native SDK

インストール

使用方法

リターンURLの転送

結果の意味

支払いの確認

外観のカスタマイズ

エラー

放棄されたセッション

関連情報