> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 移动集成指南
> 统一指南，用于将 Dodo Payments 集成到 Android、iOS、React Native 和 Flutter 移动应用程序中。
通过四个简单步骤启动移动支付集成
提供 Android、iOS、React Native 和 Flutter 的完整代码示例
## 前提条件
在将 Dodo Payments 集成到您的移动应用之前，请确保您拥有：
* **Dodo Payments 账户**：具有 API 访问权限的活跃商户账户
* **API 凭证**：来自仪表板的 API 密钥和 webhook 密钥
* **移动应用项目**：Android、iOS、React Native 或 Flutter 应用程序
* **后端服务器**：安全处理结账会话创建
## 集成工作流程
移动集成遵循一个安全的 4 步骤流程，其中您的后端处理 API 调用，而您的移动应用管理用户体验。
了解如何在后端使用 Node.js、Python 等创建结账会话。在专门的 Checkout Sessions API 文档中查看完整示例和参数参考。
**Security**：结账会话必须在后端服务器上创建，绝不能在移动应用中。这样可以保护 API 密钥并确保正确的验证。
您的移动应用调用您的后端以获取结账 URL：
```swift theme={null}
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")
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
}
```
```kotlin theme={null}
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")
.post(requestBody)
.build()
val response = client.newCall(request).execute()
val responseBody = response.body?.string()
val jsonResponse = JSONObject(responseBody ?: "")
return jsonResponse.getString("checkout_url")
}
```
```javascript theme={null}
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',
},
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;
}
};
```
**Security**：移动应用仅与您的后端通信，绝不直接与 Dodo Payments API 通信。
在安全的应用内浏览器中打开结账 URL 以处理付款。
查看 Android、iOS 和 Flutter 移动支付的完整代码和设置说明。
通过 webhook 和重定向 URL 处理付款完成，以确认付款状态。
## 平台特定集成
在下面选择您的移动平台以获取完整的实现示例：
### Android 集成
#### Chrome 自定义标签实现
```kotlin theme={null}
// Add Chrome Custom Tabs dependency to build.gradle
implementation 'androidx.browser:browser:1.5.0'
// In your Activity
class PaymentActivity : AppCompatActivity() {
private var customTabsSession: CustomTabsSession? = null
private var customTabsClient: CustomTabsClient? = null
private var customTabsServiceConnection: CustomTabsServiceConnection? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Initialize Custom Tabs
customTabsServiceConnection = object : CustomTabsServiceConnection() {
override fun onCustomTabsServiceConnected(name: ComponentName, client: CustomTabsClient) {
customTabsClient = client
customTabsClient?.warmup(0L)
customTabsSession = customTabsClient?.newSession(object : CustomTabsCallback() {
override fun onNavigationEvent(navigationEvent: Int, extras: Bundle?) {
// Handle navigation events
}
})
}
override fun onServiceDisconnected(name: ComponentName) {
customTabsClient = null
}
}
CustomTabsClient.bindCustomTabsService(
this,
"com.android.chrome",
customTabsServiceConnection!!
)
// Get checkout URL from backend and launch
lifecycleScope.launch {
try {
val checkoutURL = getCheckoutURL("prod_123", "customer@example.com", "Customer Name")
val customTabsIntent = CustomTabsIntent.Builder(customTabsSession)
.build()
customTabsIntent.launchUrl(this@PaymentActivity, Uri.parse(checkoutURL))
} catch (e: Exception) {
// Handle error
Log.e("PaymentActivity", "Failed to get checkout URL", e)
}
}
}
}
```
### iOS 集成
#### SFSafariViewController 实现
```swift theme={null}
import SafariServices
class PaymentViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
Task {
do {
let checkoutURL = try await getCheckoutURL(
productId: "prod_123",
customerEmail: "customer@example.com",
customerName: "Customer Name"
)
if let url = URL(string: checkoutURL) {
let safariVC = SFSafariViewController(url: url)
present(safariVC, animated: true, completion: nil)
}
} catch {
// Handle error
print("Failed to get checkout URL: \(error)")
}
}
}
}
```
#### 深度链接处理
配置 URL 方案以处理支付完成重定向：
**1. 在 Info.plist 中设置 URL 方案：**
```xml theme={null}
CFBundleURLTypes
CFBundleURLName
myapp
CFBundleURLSchemes
myapp
```
**2. 在 AppDelegate 中处理重定向：**
```swift theme={null}
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
if url.scheme == "myapp" && url.host == "payment-status" {
NotificationCenter.default.post(name: .paymentCompleted, object: url)
return true
}
return false
}
```
**3. 监听支付完成：**
```swift theme={null}
NotificationCenter.default.addObserver(self, selector: #selector(handlePaymentCompletion(_:)), name: .paymentCompleted, object: nil)
@objc func handlePaymentCompletion(_ notification: Notification) {
if let url = notification.object as? URL {
safariVC?.dismiss(animated: true)
// Parse payment status from URL parameters
let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
let paymentId = components?.queryItems?.first(where: { $0.name == "payment_id" })?.value
let status = components?.queryItems?.first(where: { $0.name == "status" })?.value
// Handle payment completion
}
}
```
### React Native 集成
#### 使用结账链接 (InAppBrowser)
在应用内浏览器中打开 Dodo 的托管结账页面。
##### InAppBrowser 实现
```javascript theme={null}
import React from 'react';
import { View, TouchableOpacity, Text, Alert } from 'react-native';
import { InAppBrowser } from 'react-native-inappbrowser-reborn';
const PaymentButton = ({ productId, onPaymentComplete }) => {
const openPaymentLink = async () => {
try {
// Get checkout URL from backend
const checkoutURL = await getCheckoutURL(
productId,
'customer@example.com',
'Customer Name'
);
const result = await InAppBrowser.open(checkoutURL, {
// iOS options
dismissButtonStyle: 'cancel',
preferredBarTintColor: '#453AA4',
preferredControlTintColor: 'white',
readerMode: false,
animated: true,
modalPresentationStyle: 'fullScreen',
modalTransitionStyle: 'coverVertical',
modalEnabled: true,
enableBarCollapsing: false,
// Android options
showTitle: true,
toolbarColor: '#453AA4',
secondaryToolbarColor: 'black',
navigationBarColor: 'black',
navigationBarDividerColor: 'white',
enableUrlBarHiding: true,
enableDefaultShare: true,
forceCloseOnRedirection: false,
animations: {
startEnter: 'slide_in_right',
startExit: 'slide_out_left',
endEnter: 'slide_in_left',
endExit: 'slide_out_right'
},
headers: {
'my-custom-header': 'my custom header value'
}
});
// Handle payment completion based on result
if (result.type === 'dismiss') {
// User dismissed the browser
console.log('Payment browser dismissed');
}
} catch (error) {
Alert.alert('Error', 'Failed to open payment page');
console.error('InAppBrowser error:', error);
}
};
return (
Pay Now
);
};
export default PaymentButton;
```
#### 支付回调的深度链接处理
```javascript theme={null}
// App.js or your main component
import React, { useEffect } from 'react';
import { Linking } from 'react-native';
const App = () => {
useEffect(() => {
// Handle deep links when app is already running
const handleDeepLink = (url) => {
if (url.includes('payment-status')) {
const urlParams = new URLSearchParams(url.split('?')[1]);
const paymentId = urlParams.get('payment_id');
const status = urlParams.get('status');
// Handle payment completion
handlePaymentCallback(paymentId, status);
}
};
// Listen for deep links
const subscription = Linking.addEventListener('url', ({ url }) => {
handleDeepLink(url);
});
// Handle deep link if app was opened from a link
Linking.getInitialURL().then((url) => {
if (url) {
handleDeepLink(url);
}
});
return () => subscription?.remove();
}, []);
const handlePaymentCallback = (paymentId, status) => {
if (status === 'succeeded') {
// Navigate to success screen or show success message
console.log('Payment successful:', paymentId);
} else {
// Handle payment failure
console.log('Payment failed:', paymentId);
}
};
// Your app components...
};
export default App;
```
#### 包依赖
将此依赖添加到您的 `package.json`：
```json theme={null}
{
"dependencies": {
"react-native-inappbrowser-reborn": "^6.4.0"
}
}
```
#### 安装命令
```bash theme={null}
# Install InAppBrowser
npm install react-native-inappbrowser-reborn
cd ios && pod install
```
#### Android 配置
添加到 `android/app/src/main/AndroidManifest.xml`：
```xml theme={null}
```
#### iOS 配置
添加到 `ios/YourApp/Info.plist`：
```xml theme={null}
CFBundleURLTypes
CFBundleURLName
myapp
CFBundleURLSchemes
myapp
```
使用 InAppBrowser 提供原生浏览器体验。处理支付回调的深度链接。
***
#### 备选方案：原生支付 SDK
为了获得更集成的支付体验，具有原生 UI 和完全自定义，Dodo Payments 提供了 React Native SDK。
**Regional Compliance**：应用内支付 SDK 有地区限制。在 **iOS** 上，原生支付 SDK 仅在 **欧盟**（根据 DMA 条款）是合法的。在 **Android** 上，它们在用户选择计费（UCB）市场是合法的。对于其他地区，请使用上面的结账链接方法以确保 App Store 和 Play Store 合规。
提供完整指南，介绍如何将 Dodo 的 React Native SDK 与原生支付表单集成、全定制选项以及直接支付处理。包括设置、实现和测试说明。
查看[App Store Fee Bypass Guide](/features/bypassing-app-store-fees)，以了解应用内支付集成的地区合规要求。
### Flutter 集成
```dart theme={null}
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';
Future getCheckoutURL(String productId, String customerEmail, String customerName) async {
final response = await http.post(
Uri.parse('https://your-backend.com/api/create-checkout-session'),
headers: {'Content-Type': 'application/json'},
body: json.encode({
'productId': productId,
'customerEmail': customerEmail,
'customerName': customerName,
}),
);
if (response.statusCode == 200) {
final data = json.decode(response.body);
return data['checkout_url'];
} else {
throw Exception('Failed to get checkout URL: ${response.statusCode}');
}
}
class PaymentScreen extends StatefulWidget {
@override
_PaymentScreenState createState() => _PaymentScreenState();
}
class _PaymentScreenState extends State {
late WebViewController _controller;
String? checkoutURL;
@override
void initState() {
super.initState();
_getCheckoutURL();
}
Future _getCheckoutURL() async {
try {
final url = await getCheckoutURL('prod_123', 'customer@example.com', 'Customer Name');
setState(() {
checkoutURL = url;
});
} catch (e) {
// Handle error
print('Failed to get checkout URL: $e');
}
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('Payment')),
body: checkoutURL == null
? Center(child: CircularProgressIndicator())
: WebView(
initialUrl: checkoutURL,
javascriptMode: JavascriptMode.unrestricted,
onWebViewCreated: (WebViewController webViewController) {
_controller = webViewController;
},
navigationDelegate: (NavigationRequest request) {
if (request.url.contains('payment_id') && request.url.contains('status')) {
// Handle payment completion
final uri = Uri.parse(request.url);
final paymentId = uri.queryParameters['payment_id'];
final status = uri.queryParameters['status'];
handlePaymentCompletion(paymentId, status);
return NavigationDecision.prevent;
}
return NavigationDecision.navigate;
},
),
);
}
void handlePaymentCompletion(String? paymentId, String? status) {
if (status == 'succeeded') {
// Payment successful
} else {
// Payment failed
}
}
}
```
使用 WebView 处理支付链接。处理重定向 URL 以检测付款完成。
## 最佳实践
* **安全性**：绝不要在应用代码中存储 API 密钥。使用安全存储和 SSL 钉扎。
* **用户体验**：显示加载指示器，优雅地处理错误，并提供清晰的消息。
* **测试**：使用测试卡，模拟网络错误，并在各种设备上进行测试。
## 故障排除
### 常见问题
* **WebView 未打开支付链接**：确保支付链接有效并使用 HTTPS。
* **未收到回调**：检查您的返回 URL 和 webhook 配置。
* **API 密钥错误**：验证您的 API 密钥是否正确并具有必要的权限。
## 其他资源
* [支付集成指南](/developer-resources/integration-guide)
* [Webhook 文档](/developer-resources/webhooks/intents/webhook-events-guide)
* [测试流程](/miscellaneous/testing-process)
* [技术常见问题](/miscellaneous/faq)
如有疑问或需要支持，请联系 [support@dodopayments.com](mailto:support@dodopayments.com)。