Hướng Dẫn Tích Hợp Di Động

​

Điều kiện tiên quyết

• Tài khoản Dodo Payments: Tài khoản merchant đang hoạt động có quyền truy cập API
• Thông tin xác thực API: API key và webhook secret key từ dashboard
• Dự án ứng dụng di động: Ứng dụng Android, iOS, React Native hoặc Flutter
• Backend Server: Để xử lý việc tạo checkout session một cách an toàn

​

Quy trình tích hợp

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

​

Chọn SDK

​

Đăng ký 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" }
      ]
    ]
  }
}

​

Tùy chỉnh giao diện

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

​

Tùy chỉnh trang Checkout

​

Recipe tối ưu cho thiết bị di động

Minimal Mobile Checkout - fastest path to payment

Dùng recipe này khi bạn muốn form ngắn nhất có thể: phương thức thanh toán ở đầu, chỉ yêu cầu postcode cho địa chỉ, không có field giảm giá và theme khớp với thiết bị.

• 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

Xem Checkout Sessions để biết tất cả tham số khả dụng và giá trị mặc định.

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

Dùng recipe này khi trang checkout cần tạo cảm giác như một phần của ứng dụng. Đặt màu thương hiệu, font tùy chỉnh và nhãn nút thanh toán được bản địa hóa.

• 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 chấp nhận các object dark và light riêng biệt để bảng màu thích ứng với giao diện hiện tại của thiết bị. Xem Checkout Sessions để biết đầy đủ tài liệu tham chiếu về color key.

One-Click Returning Customer - saved card, instant confirmation

Dùng recipe này cho người dùng đã đăng nhập và từng thanh toán trước đó. Kết hợp customer ID, payment method đã lưu của họ và confirm: true để bỏ qua hoàn toàn form checkout.

• 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' },
  billing_address: { country: 'US' },
  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 11 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    billing_address={"country": "US"},
    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 11 lines

status trong deep-link return chỉ là gợi ý UI. Xác nhận quyền truy cập bằng cách lắng nghe webhook payment.succeeded trên backend.

Subscription with Free Trial - trial before first charge

Dùng recipe này cho các sản phẩm subscription cung cấp thời gian dùng thử miễn phí trước chu kỳ billing đầu tiên.

• 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

Cấp quyền sử dụng tính năng khi backend nhận webhook subscription.active - không phải khi SDK di động trả về. Xem Subscription Integration Guide để biết toàn bộ quy trình webhook.

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

Dùng recipe này để tokenise card của khách hàng cho các khoản charge sau này (nạp ví, pay-as-you-go, BNPL) mà không hiển thị nhãn “subscription”. Khách hàng ủy quyền payment method một lần; sau đó bạn charge các khoản biến đổi theo nhu cầu.

Đây là pattern được các ứng dụng tính phí dựa trên mức sử dụng sử dụng - ví dụ ứng dụng chiêm tinh tính phí theo từng phiên từ card đã được ủy quyền trước, thay vì theo lịch cố định.

• 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 23 lines

On-demand charge yêu cầu tối thiểu 1 USD (100 cents). Các khoản dưới 1 USD sẽ bị từ chối với "value out of range". Để authorization với số tiền bằng 0, hãy dùng mandate_only: true như bên trên, sau đó charge ít nhất 1 USD trong các request tiếp theo.

Xem On-Demand Subscriptions để biết toàn bộ quy trình charge, sự kiện webhook và chính sách retry.

​

Quy trình Subscription trên thiết bị di động

​

Subscription định kỳ thông thường

​

On-Demand Subscription

• Đặt show_on_demand_tag: false để trang checkout không hiển thị ngôn ngữ “subscription” hoặc “on-demand”. Với các trường hợp tokenise card, khách hàng không mong đợi thuật ngữ subscription.
• Sau khi mandate được ủy quyền, backend nhận subscription.active. Lưu subscription_id - bạn sẽ sử dụng nó cho mọi khoản charge trong tương lai.

​

Subscription có Free Trial

​

Nâng cấp và hạ cấp

​

Giảm tỷ lệ rời bỏ Checkout

​

Tối ưu Form

​

Điền sẵn dữ liệu khách hàng

• Khách hàng mới - đặt customer.email và customer.name từ auth session.
• Khách hàng quay lại - đặt customer.customer_id để tự động điền sẵn mọi thông tin đã lưu.
• Currency - luôn truyền billing_currency và billing_address.country cùng nhau.

​

Công cụ khôi phục

​

Best Practices

• Bảo mật: Không bao giờ đưa API key vào ứng dụng. Tạo checkout session trên backend và chỉ truyền checkout_url kết quả đến client.
• Quyền quyết định: Xem CheckoutResult.status là gợi ý UI. 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 loading trong khi backend tạo session và xử lý cancelled như một kết quả bình thường thay vì lỗi.
• Kiểm thử: Dùng test mode và test card, đồng thời xác minh vòng lặp return-URL trên thiết bị thật cũng như simulator.
• Chuyển đổi: Đặt show_order_details: false và minimal_address: true để đạt tỷ lệ hoàn tất checkout di động tốt nhất. Đưa phương thức thanh toán lên phần đầu màn hình và giảm số field trong form là hai thay đổi có tác động lớn nhất.
• Currency: Luôn truyền rõ ràng cả billing_currency và billing_address.country - nếu thiếu một trong hai, Adaptive Currency có thể thay đổi currency billing dựa trên địa chỉ IP của khách hàng.
• On-demand billing: Đặt show_on_demand_tag: false khi dùng on-demand subscription để tokenise card. Khách hàng sử dụng quy trình nạp ví không mong đợi thấy ngôn ngữ “subscription”.
• Khôi phục: Bật khôi phục giỏ hàng bị bỏ dở trong dashboard Dodo Payments để tự động tái tương tác với 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

• Không bao giờ nhận được callback: Scheme trong returnUrl phải khớp với scheme bạn đã đăng ký. Trên Android, đó là manifest placeholder dodoCallbackScheme; trên iOS và React Native, đó là URL type Info.plist.
• Checkout quay lại trình duyệt thay vì ứng dụng (iOS): Bạn chưa chuyển tiếp URL đến. Gọi DodoCheckout.handleOpenURL(url) từ .onOpenURL, scene(_:openURLContexts:) hoặc listener Linking của React Native.
• PLATFORM_ERROR trên Android: Thường là do scheme không khớp. Cũng có thể xảy ra nếu MainActivity đặt android:taskAffinity="" (giá trị mặc định flutter create), khiến một số bản build OEM làm mất checkout đang thực hiện.
• ALREADY_IN_PROGRESS: Một checkout vẫn đang mở. Hãy chờ hoặc dismiss checkout trước đó rồi mới bắt đầu checkout khác.
• Build thất bại với placeholder chưa được resolve: Bạn đã thêm Android SDK nhưng chưa đặt manifestPlaceholders["dodoCallbackScheme"].
• Thanh toán thành công nhưng chưa cấp quyền: Đây là điều được dự đoán nếu bạn dựa vào kết quả trên thiết bị di động. Thay vào đó, hãy cấp quyền từ webhook payment.succeeded / subscription.active.
• Apple Pay / Google Pay không hiển thị trên thiết bị di động: Checkout đang được tải bên trong embedded WebView (WKWebView / Android WebView), làm ẩn các ví và có thể khiến 3-D Secure bị lỗi. Hãy mở bằng SDK hoặc trong trình duyệt hệ thống (Custom Tabs / SFSafariViewController).

​

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
• On-Demand Subscriptions
• Nâng cấp/hạ cấp Subscription
• Khôi phục giỏ hàng bị bỏ dở
• Customer Portal