Guida all'Integrazione Mobile

​

Prerequisiti

• Account Dodo Payments: Account commerciante attivo con accesso API
• Credenziali API: Chiave API e chiave segreta webhook dalla dashboard
• Progetto dell’app mobile: Applicazione Android, iOS, React Native o Flutter
• Server backend: Per gestire in modo sicuro la creazione delle sessioni di checkout

​

Flusso di integrazione

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

​

Scegli il tuo SDK

​

Registrazione di uno schema URL di callback

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>

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        { "android": { "manifestPlaceholders": { "dodoCallbackScheme": "myapp" } } }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [{ "CFBundleURLSchemes": ["myapp"] }]
      }
    }
  }
}

​

Best practice

• Sicurezza: non includere mai una chiave API nella tua app. Crea le sessioni di checkout nel backend e passa al client solo l’checkout_url risultante.
• Autorità: tratta CheckoutResult.status come un’indicazione dell’interfaccia. Concedi l’accesso solo dopo che il backend ha confermato il pagamento.
• Esperienza utente: mostra uno stato di caricamento mentre il backend crea la sessione e gestisci cancelled come un esito normale, non come un errore.
• Test: usa la modalità di test e le carte di test e verifica il ciclo completo dell’URL di ritorno su un dispositivo reale oltre che su un simulatore.

​

Risoluzione dei problemi

​

Problemi comuni

• Il callback non arriva mai: lo schema in returnUrl deve corrispondere a quello registrato. Su Android è il placeholder del manifest dodoCallbackScheme; su iOS e React Native è il tipo di URL Info.plist.
• Il checkout torna al browser invece che alla tua app (iOS): non hai inoltrato l’URL in arrivo. Chiama DodoCheckout.handleOpenURL(url) da .onOpenURL, scene(_:openURLContexts:) o da un listener Linking di React Native.
• PLATFORM_ERROR su Android: nella maggior parte dei casi si tratta di una mancata corrispondenza dello schema. Può verificarsi anche se MainActivity imposta android:taskAffinity="" (il valore predefinito standard flutter create), permettendo ad alcune build OEM di perdere il checkout in corso.
• ALREADY_IN_PROGRESS: un checkout è ancora aperto. Attendi o chiudi quello precedente prima di avviarne un altro.
• La build non riesce a causa di un placeholder non risolto: hai aggiunto l’SDK Android ma non hai mai impostato manifestPlaceholders["dodoCallbackScheme"].
• Il pagamento è riuscito ma l’accesso non è stato concesso: è previsto se utilizzi il risultato mobile come riferimento. Concedi l’accesso dal webhook payment.succeeded / subscription.active invece.

​

Risorse aggiuntive

• Guida all’integrazione dei pagamenti
• Documentazione sui webhook
• Processo di test
• FAQ tecniche