iOS

This is the official Dodo Payments iOS checkout SDK for Swift. It opens Dodo’s hosted checkout in a native browser view and returns a typed result.

Checkout Sessions API

Create the checkout_url this SDK opens, from your backend.

Mobile Integration Guide

See how this fits into the full mobile payment flow.

The iOS SDK opens Dodo’s hosted checkout in SFSafariViewController, holds no API key, and never calls the Dodo API directly. All checkout logic runs in the browser; the SDK simply manages the view lifecycle and captures the return URL. Requires iOS 16+, Swift 6.

Installation

Add the Package

In Xcode, go to File → Add Package Dependencies and enter:

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

Select version 1.0.0 or later.Alternatively, add to your Package.swift:

Package.swift

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

Your app must register a URL scheme to receive the return URL from the checkout. Add this to your Info.plist:

Info.plist

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

You can also add this via Xcode’s Info → URL Types UI.

Usage

import DodoCheckout

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: dismiss()
case .pending:   showPending()
case .expired:   showExpired()
}

Forwarding the Return URL

SFSafariViewController has no in-process way to catch its own return URL. Your app must forward incoming URLs into the SDK.

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)
}

It’s safe to forward every URL here. handleOpenURL only acts on URLs matching your registered returnUrl and returns false for anything else.

What the Result Means

result.status is a UI hint, not proof of payment. Confirm every payment from your backend, via the payment.succeeded / subscription.active webhook.

CheckoutStatus

required

One of succeeded, failed, cancelled, pending, expired.

String?

Set when the return URL included one. Display it in the UI, don’t use it to grant access. See Verify the Payment below.

String?

Set for subscription checkouts.

[String]?

Set when the checkout includes license key products.

String?

Set when the checkout captures an email.

[String: String]

Every query parameter from the return URL, verbatim.

Verify the Payment

Webhooks

Dodo Payments calls your backend when a payment succeeds or a subscription activates.

Get Payment Detail

Look up paymentId with your secret key to check its status directly.

Grant access after one of these confirms the payment, never from result.status alone.

Errors

start throws CheckoutError only for misuse or a platform failure. A cancelled or declined payment is always a result, never an exception.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): not a checkout.dodopayments.com session URL.
invalidReturnUrl (INVALID_RETURN_URL): not a valid absolute URL.
alreadyInProgress (ALREADY_IN_PROGRESS): a checkout is already running.
platformError (PLATFORM_ERROR): unexpected platform failure.

Abandoned Sessions

If the app is killed mid-checkout, recover the session on next launch and reconcile it with your backend.

import DodoCheckout

if let abandoned = DodoCheckout.getAbandonedSession() {
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession()
}

Mobile Integration Guide

The same contract for Android, React Native, and Flutter.

React Native SDK

Wraps this same Swift core on iOS.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installation

Usage

Forwarding the Return URL

What the Result Means

Verify the Payment

Webhooks

Get Payment Detail

Errors

Abandoned Sessions

Mobile Integration Guide

React Native SDK

Checkout Sessions API

Mobile Integration Guide

​Installation

​Usage

​Forwarding the Return URL

​What the Result Means

​Verify the Payment

Webhooks

Get Payment Detail

​Errors

​Abandoned Sessions

​Related

Mobile Integration Guide

React Native SDK

Installation

Usage

Forwarding the Return URL

What the Result Means

Verify the Payment

Errors

Abandoned Sessions

Related