Guida all'Integrazione Mobile - Dodo Payments Documentation

Quick Start

Avvia l’integrazione dei pagamenti mobile in 4 semplici passaggi

Platform Examples

Esempi di codice completi per Android, iOS, React Native e Flutter

Requisiti Preliminari

Prima di integrare Dodo Payments nella tua app mobile, assicurati di avere:

Account Dodo Payments: Account commerciante attivo con accesso API
Credenziali API: Chiave API e chiave segreta webhook dal tuo dashboard
Progetto App Mobile: Applicazione Android, iOS, React Native o Flutter
Server Backend: Per gestire in modo sicuro la creazione della sessione di checkout

Flusso di Integrazione

L’integrazione mobile segue un processo sicuro in 4 passaggi in cui il tuo backend gestisce le chiamate API e la tua app mobile gestisce l’esperienza utente.

Backend: Create Checkout Session

Checkout Session API Docs

Impara come creare una sessione di checkout nel tuo backend usando Node.js, Python e altro. Consulta esempi completi e riferimenti ai parametri nella documentazione dedicata dell’Checkout Sessions API.

Sicurezza: Le sessioni di checkout devono essere create sul tuo server backend, mai nell’app mobile. Questo protegge le tue chiavi API e garantisce una corretta validazione.

Mobile: Get Checkout URL

La tua app mobile chiama il tuo backend per ottenere l’URL di checkout:

iOS (Swift)
Android (Kotlin)
React Native (JavaScript)

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
}

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

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

Sicurezza: Le app mobili comunicano solo con il tuo backend, mai direttamente con l’API di Dodo Payments.

Mobile: Open Checkout in Browser

Apri l’URL di checkout in un browser sicuro all’interno dell’app per elaborare il pagamento.

See platform-specific integration examples

Visualizza il codice completo e le istruzioni di configurazione per i pagamenti mobili su Android, iOS e Flutter.

Backend: Handle Payment Completion

Gestisci il completamento del pagamento tramite webhook e URL di reindirizzamento per confermare lo stato del pagamento.

Integrazione Specifica per Piattaforma

Scegli la tua piattaforma mobile qui sotto per esempi di implementazione completi:

Android
iOS
React Native
Flutter

Integrazione Android

Implementazione delle Chrome Custom Tabs

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

Integrazione iOS

Implementazione di SFSafariViewController

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

Gestione dei Deep Link

Configura gli schemi URL per gestire i reindirizzamenti al completamento del pagamento:1. Configura gli schemi URL in Info.plist:

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

2. Gestisci i reindirizzamenti in AppDelegate:

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. Ascolta il completamento del pagamento:

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

Integrazione React Native

Utilizzando i Link di Checkout (InAppBrowser)

Apri la pagina di checkout ospitata da Dodo in un browser in-app.

Implementazione di InAppBrowser

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 (
    <View style={{ padding: 20 }}>
      <TouchableOpacity
        style={{
          backgroundColor: '#007AFF',
          padding: 15,
          borderRadius: 8,
          alignItems: 'center'
        }}
        onPress={openPaymentLink}
      >
        <Text style={{ color: 'white', fontSize: 16, fontWeight: 'bold' }}>
          Pay Now
        </Text>
      </TouchableOpacity>
    </View>
  );
};

export default PaymentButton;

Gestione dei Deep Link per i Callback di Pagamento

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

Dipendenze del Pacchetto

Aggiungi questa dipendenza a package.json:

{
  "dependencies": {
    "react-native-inappbrowser-reborn": "^6.4.0"
  }
}

Comandi di Installazione

# Install InAppBrowser
npm install react-native-inappbrowser-reborn
cd ios && pod install

Configurazione Android

Aggiungi a android/app/src/main/AndroidManifest.xml:

<activity
  android:name="com.reactnativeinappbrowserreborn.InAppBrowserActivity"
  android:theme="@style/Theme.AppCompat.Dialog"
  android:exported="false" />

Configurazione iOS

Aggiungi a ios/YourApp/Info.plist:

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

Usa InAppBrowser per un’esperienza browser nativa. Gestisci i deep link per i callback di pagamento.

Alternativa: SDK di Pagamento Nativo

Per un’esperienza di pagamento più integrata con UI nativa e opzioni di personalizzazione complete, Dodo Payments offre un SDK per React Native.

Conformità regionale: gli SDK di pagamento in-app hanno restrizioni regionali. Su iOS, gli SDK di pagamento nativi sono legali solo nell’UE (ai sensi del DMA). Su Android, sono legali nei mercati User Choice Billing (UCB). Per altre regioni, usa l’approccio dei link di checkout sopra per garantire la conformità con App Store e Play Store.

React Native SDK Integration Guide

Guida completa all’integrazione dell’SDK React Native di Dodo con fogli di pagamento nativi, opzioni di personalizzazione complete e gestione diretta dei pagamenti. Include istruzioni per l’installazione, l’implementazione e i test.

Consulta la Guida al bypass delle commissioni dell’App Store per capire i requisiti di conformità regionale per le integrazioni di pagamento in-app.

Integrazione Flutter

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<String> 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<PaymentScreen> {
  late WebViewController _controller;
  String? checkoutURL;
  
  @override
  void initState() {
    super.initState();
    _getCheckoutURL();
  }
  
  Future<void> _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
    }
  }
}

Usa WebView per i link di pagamento. Gestisci l’URL di reindirizzamento per rilevare il completamento del pagamento.

Migliori Pratiche

Sicurezza: Non memorizzare mai le chiavi API nel codice della tua app. Utilizza uno storage sicuro e SSL pinning.
Esperienza Utente: Mostra indicatori di caricamento, gestisci gli errori in modo elegante e fornisci messaggi chiari.
Test: Utilizza carte di test, simula errori di rete e testa su vari dispositivi.

Risoluzione dei Problemi

Problemi Comuni

WebView non apre il link di pagamento: Assicurati che il link di pagamento sia valido e utilizzi HTTPS.
Callback non ricevuto: Controlla il tuo URL di ritorno e la configurazione del webhook.
Errori di chiave API: Verifica che la tua chiave API sia corretta e abbia le autorizzazioni necessarie.

Risorse Aggiuntive

Per domande o supporto, contatta support@dodopayments.com.

Quick Start

Platform Examples

​Requisiti Preliminari

​Flusso di Integrazione

Checkout Session API Docs

See platform-specific integration examples

​Integrazione Specifica per Piattaforma

​Integrazione Android

​Implementazione delle Chrome Custom Tabs

​Integrazione iOS

​Implementazione di SFSafariViewController

​Gestione dei Deep Link

​Integrazione React Native

​Utilizzando i Link di Checkout (InAppBrowser)

Implementazione di InAppBrowser

​Gestione dei Deep Link per i Callback di Pagamento

​Dipendenze del Pacchetto

​Comandi di Installazione

​Configurazione Android

​Configurazione iOS

​Alternativa: SDK di Pagamento Nativo

React Native SDK Integration Guide

​Integrazione Flutter

​Migliori Pratiche

​Risoluzione dei Problemi

​Problemi Comuni

​Risorse Aggiuntive

Requisiti Preliminari

Flusso di Integrazione

Integrazione Specifica per Piattaforma

Integrazione Android

Implementazione delle Chrome Custom Tabs

Integrazione iOS

Implementazione di SFSafariViewController

Gestione dei Deep Link

Integrazione React Native

Utilizzando i Link di Checkout (InAppBrowser)

Gestione dei Deep Link per i Callback di Pagamento

Dipendenze del Pacchetto

Comandi di Installazione

Configurazione Android

Configurazione iOS

Alternativa: SDK di Pagamento Nativo

Integrazione Flutter

Migliori Pratiche

Risoluzione dei Problemi

Problemi Comuni

Risorse Aggiuntive