Mobile Integration Guide

​

Prerequisites

• A Dodo Payments account.
• An API key from Developer → API Keys and a webhook signing secret from Developer → Webhooks.
• An Android, iOS, React Native, or Flutter app.
• A backend server that creates checkout sessions. The API key stays on this server.

​

Integration Workflow

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

​

Choose Your SDK

​

Registering a Callback URL Scheme

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

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

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

​

Appearance Customization

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 Page Customization

​

Mobile-Optimized Recipes

Minimal Mobile Checkout - fastest path to payment

Use this recipe for the shortest form: payment methods at the top, only a postcode for the address, no discount field, and a theme that follows the device.

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

See all 26 lines

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)

See all 27 lines

See Checkout Sessions for all available parameters and their defaults.

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

Use this recipe when the checkout page must look like part of your app. It sets your brand colors, a border radius, and a custom pay button label.

• 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',
    },
  },
});

See all 24 lines

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

See all 24 lines

theme_config accepts separate dark and light objects, so the palette follows the device’s appearance. For every color key and the font option, see Checkout Sessions.

One-Click Returning Customer - saved card, instant confirmation

Use this recipe for signed-in customers who have paid before. Pass the customer’s customer_id, their saved payment_method_id, and confirm: true to skip the checkout form. With a payment_method_id, the session charges the saved method directly and returns no checkout_url, so your app has nothing to open. Learn the outcome from webhooks.

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

See all 18 lines

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

See all 18 lines

Grant access when your backend receives the payment.succeeded webhook. Any status your app shows is a UI hint only.

Subscription with Free Trial - trial before first charge

Use this recipe for a subscription product with a free trial before the first charge. trial_period_days sets the trial length for this session.

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

See all 14 lines

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

See all 11 lines

Grant access when your backend receives the subscription.active webhook, not when the mobile SDK returns. For the full webhook flow, see the Subscription Integration Guide.

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

Use this recipe to save a customer’s payment method for later charges, such as wallet top-ups, pay-as-you-go, or BNPL, without showing a subscription label. The customer authorizes the payment method once, and you charge variable amounts later.

Apps that charge by usage follow this pattern. For example, an astrology app charges a pre-authorized card for each session instead of on a fixed schedule.

• 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',
// });

See all 26 lines

# 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",
# )

See all 24 lines

An on-demand charge must be at least 100 in the smallest currency unit ($1.00 for USD). The API rejects a lower product_price with "product_price: value out of range". To authorize without charging, use mandate_only: true as shown above, then charge at least that minimum later.

For the full charge flow, webhook events, and retry policies, see On-Demand Subscriptions.

​

Subscription Flows from Mobile

​

Regular Recurring Subscriptions

​

On-Demand Subscriptions

• Set show_on_demand_tag: false so the checkout page doesn’t show subscription or on-demand wording. Customers who save a card for top-ups don’t expect subscription terms.
• After the customer authorizes the mandate, your backend receives subscription.active. Store the subscription_id, because every later charge uses it.

​

Subscription with Free Trial

​

Upgrades and Downgrades

​

Reducing Checkout Drop-Offs

​

Optimize the Form

​

Pre-Fill Customer Data

• New customers: set customer.email and customer.name from your auth session.
• Returning customers: set customer.customer_id to use the customer’s stored details.
• Currency: pass billing_currency and billing_address.country together.

​

Recovery Tools

​

Các phương pháp hay nhất

• Bảo mật: Không bao giờ đưa API key vào ứng dụng của bạn. Tạo checkout session trên backend và chỉ truyền checkout_url cho ứng dụng.
• Quyền hạn: Xem CheckoutResult.status như một gợi ý về giao diện người dùng. Chỉ cấp quyền sau khi backend xác nhận thanh toán.
• Trải nghiệm người dùng: Hiển thị trạng thái đang tải trong khi backend tạo session. Đừng coi cancelled là lỗi, vì thanh toán vẫn có thể đã thành công.
• Kiểm thử: Sử dụng chế độ test và thẻ test, đồng thời kiểm tra toàn bộ quy trình return URL trên thiết bị thật cũng như trình mô phỏng.
• Tỷ lệ chuyển đổi: Thiết lập show_order_details: false và minimal_address: true. Kết hợp lại, chúng đưa các phương thức thanh toán lên phần đầu màn hình và loại bỏ hầu hết các trường địa chỉ.
• Tiền tệ: Truyền cả billing_currency và billing_address.country. Nếu thiếu một trong hai, Adaptive Currency có thể chọn tiền tệ thanh toán dựa trên địa chỉ IP của khách hàng.
• Thanh toán theo nhu cầu: Thiết lập show_on_demand_tag: false khi bạn chỉ sử dụng subscription theo nhu cầu để lưu thẻ. Khách hàng nạp tiền vào ví sẽ không mong đợi nội dung về subscription.
• Khôi phục: Bật Abandoned Cart Recovery trong dashboard để gửi email cho những khách hàng không hoàn tất checkout.

​

Khắc phục sự cố

​

Các vấn đề thường gặp

• Callback không bao giờ đến: Scheme trong returnUrl phải khớp với scheme bạn đã đăng ký. Trên Android, đó là manifest placeholder dodoCallbackScheme. Trên iOS, đó là URL type Info.plist. Ứng dụng React Native và Flutter cần cả hai, còn trong Expo, config plugin sẽ thiết lập cả hai.
• Checkout quay lại trình duyệt thay vì ứng dụng của bạn (iOS): Ứng dụng của bạn không chuyển tiếp URL đến. Hãy gọi DodoCheckout.handleOpenURL(url) từ .onOpenURL, scene(_:openURLContexts:) hoặc listener Linking của React Native.
• PLATFORM_ERROR trên Android: Nguyên nhân phổ biến nhất là scheme không khớp. Lỗi này cũng xuất hiện khi MainActivity của bạn thiết lập android:taskAffinity="" (giá trị mặc định flutter create), khiến một số bản build Android của OEM làm mất checkout đang thực hiện.
• ALREADY_IN_PROGRESS: Một checkout vẫn đang mở. Hãy chờ checkout trước đó hoàn tất hoặc đóng nó trước khi bắt đầu checkout khác.
• Build thất bại với placeholder chưa được phân giải: Bạn đã thêm Android SDK nhưng chưa thiết lập manifestPlaceholders["dodoCallbackScheme"].
• Thanh toán thành công nhưng quyền truy cập chưa được cấp: Ứng dụng của bạn cấp quyền truy cập dựa trên kết quả từ mobile. Thay vào đó, hãy cấp quyền truy cập từ webhook payment.succeeded hoặc subscription.active.
• Apple Pay hoặc Google Pay không xuất hiện trên mobile: Kiểm tra xem checkout có đang tải bên trong embedded WebView hay không (WKWebView hoặc Android WebView). Hãy mở bằng SDK hoặc trong giao diện trình duyệt hệ thống: Custom Tab trên Android, hoặc SFSafariViewController hay ASWebAuthenticationSession trên iOS.

​

Tài nguyên bổ sung

• Hướng dẫn tích hợp thanh toán
• Tài liệu Webhook
• Quy trình kiểm thử
• Câu hỏi thường gặp về kỹ thuật
• Tùy chỉnh Checkout Session
• Subscription theo nhu cầu
• Nâng cấp/Hạ cấp Subscription
• Khôi phục giỏ hàng bị bỏ quên
• Customer Portal