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>

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

​

Personalizzazione dell’aspetto

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

​

Personalizzazione della pagina di checkout

​

Ricette ottimizzate per dispositivi mobili

Minimal Mobile Checkout - fastest path to payment

Usalo quando vuoi il modulo più breve possibile: metodi di pagamento in alto, solo il CAP richiesto per l’indirizzo, nessun campo per gli sconti e tema corrispondente al dispositivo.

• 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

Consulta Checkout Sessions per tutti i parametri disponibili e i relativi valori predefiniti.

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

Usalo quando la pagina di checkout deve sembrare parte della tua app. Imposta i colori del brand, un carattere personalizzato e un’etichetta localizzata per il pulsante di pagamento.

• 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 accetta oggetti separati dark e light, così la palette si adatta all’aspetto attuale del dispositivo. Consulta Checkout Sessions per il riferimento completo ai colori.

One-Click Returning Customer - saved card, instant confirmation

Usalo per gli utenti autenticati che hanno già effettuato un pagamento. Combina un ID cliente, il relativo metodo di pagamento salvato e confirm: true per saltare completamente il modulo di 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

L’status nel ritorno del deep link è solo un suggerimento per l’interfaccia. Conferma l’accesso ascoltando il webhook payment.succeeded sul backend.

Subscription with Free Trial - trial before first charge

Usalo per i prodotti in abbonamento che offrono un periodo di prova gratuito prima del primo ciclo di fatturazione.

• 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

Concedi l’accesso alla funzionalità quando il backend riceve il webhook subscription.active, non quando ritorna lo SDK mobile. Consulta Subscription Integration Guide per il flusso completo dei webhook.

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

Usalo per tokenizzare la carta di un cliente per addebiti futuri (ricariche del wallet, pay-as-you-go, BNPL) senza mostrare l’etichetta “subscription”. Il cliente autorizza una volta il metodo di pagamento; in seguito addebiti importi variabili on demand.

Questo è il pattern usato dalle app che addebitano in base all’utilizzo, ad esempio un’app di astrologia che addebita ogni sessione da una carta preautorizzata, anziché secondo una pianificazione fissa.

• 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

Gli addebiti on-demand richiedono un minimo di 1 USD (100 centesimi). Gli importi inferiori a 1 USD verranno rifiutati con "value out of range". Per un’autorizzazione a importo zero, usa mandate_only: true come mostrato sopra, quindi addebita almeno 1 USD nelle chiamate successive.

Consulta On-Demand Subscriptions per il flusso completo degli addebiti, gli eventi webhook e le policy di retry.

​

Flussi di abbonamento da dispositivi mobili

​

Abbonamenti ricorrenti standard

​

Abbonamenti on-demand

• Imposta show_on_demand_tag: false affinché la pagina di checkout non mostri il linguaggio “subscription” o “on-demand”. Nei casi d’uso di tokenizzazione delle carte, i clienti non si aspettano la terminologia degli abbonamenti.
• Dopo l’autorizzazione del mandato, il backend riceve subscription.active. Salva subscription_id: lo userai per tutti gli addebiti futuri.

​

Abbonamento con prova gratuita

​

Upgrade e downgrade

​

Riduzione degli abbandoni durante il checkout

​

Ottimizza il modulo

​

Precompila i dati del cliente

• Nuovi clienti: imposta customer.email e customer.name dalla sessione di autenticazione.
• Clienti abituali: imposta customer.customer_id per precompilare automaticamente tutti i dati salvati.
• Valuta: passa sempre billing_currency e billing_address.country insieme.

​

Strumenti di recupero

​

Best practice

• Sicurezza: non inserire mai una chiave API nella tua app. Crea le sessioni di checkout sul backend e passa al client solo il checkout_url risultante.
• Autorità: tratta CheckoutResult.status come un suggerimento per l’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 risultato normale, non come un errore.
• Test: usa la modalità test e le carte di test e verifica il percorso completo dell’URL di ritorno su un dispositivo reale e su un simulatore.
• Conversione: imposta show_order_details: false e minimal_address: true per ottenere i migliori tassi di completamento del checkout mobile. Spostare i metodi di pagamento above the fold e ridurre i campi del modulo sono le due modifiche con il maggiore impatto.
• Valuta: passa sempre esplicitamente billing_currency e billing_address.country; se manca uno dei due, Adaptive Currency può modificare la valuta di fatturazione in base all’indirizzo IP del cliente.
• Fatturazione on-demand: imposta show_on_demand_tag: false quando usi abbonamenti on-demand per la tokenizzazione delle carte. I clienti che utilizzano un flusso di ricarica del wallet non si aspettano di vedere il linguaggio “subscription”.
• Recupero: abilita il recupero dei carrelli abbandonati nella dashboard di Dodo Payments per coinvolgere nuovamente in modo automatico i clienti che non completano il checkout.

​

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 URL Info.plist.
• Il checkout torna al browser invece che all’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ò anche comparire se MainActivity imposta android:taskAffinity="" (il valore predefinito standard flutter create), consentendo 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 fallisce a causa di un placeholder non risolto: hai aggiunto lo 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 invece l’accesso dal webhook payment.succeeded / subscription.active.
• Apple Pay / Google Pay non vengono mostrati su mobile: il checkout viene caricato in una WebView incorporata (WKWebView / Android WebView), che disabilita i wallet e può interrompere 3-D Secure. Aprilo invece con lo SDK o nel browser di sistema (Custom Tabs / SFSafariViewController).

​

Risorse aggiuntive

• Payment Integration Guide
• Webhook Documentation
• Testing Process
• Technical FAQs
• Checkout Session Customization
• On-Demand Subscriptions
• Subscription Upgrade/Downgrade
• Abandoned Cart Recovery
• Customer Portal