Flutter

Questo è il pacchetto Flutter ufficiale di Dodo Payments (dodopayments_checkout su pub.dev). Esiste anche un pacchetto separato sviluppato dalla community; consulta Progetti della community.

Checkout Sessions API

Crea checkout_url, che questo SDK apre, dal tuo backend.

Mobile Integration Guide

Scopri come si integra nel flusso completo dei pagamenti mobile.

dodopayments_checkout apre il checkout ospitato di Dodo in SFSafariViewController su iOS e in una Chrome Custom Tab su Android — gli stessi core nativi utilizzati dagli SDK standalone per iOS e Android. Tutta la logica del checkout risiede in questi core nativi; il livello Dart inoltra la chiamata tramite un canale tipizzato Pigeon. Non contiene alcuna API key e non chiama mai l’API di Dodo Payments. Richiede Flutter 3.44+ / Dart 3.12+, iOS 16+ e Android minSdk 23.

Installazione

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

Aggiungi un tipo URL per il tuo schema in ios/Runner/Info.plist:

ios/Runner/Info.plist

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

Inoltra quindi gli URL in entrata (ad esempio tramite app_links) all’SDK, perché SFSafariViewController non può intercettare il proprio URL di ritorno:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

È sicuro inoltrare qui ogni URL. handleOpenURL agisce solo sugli URL corrispondenti a returnUrl registrato e risolve false per qualsiasi altro URL.

Imposta lo schema di callback come placeholder del manifest Gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Se MainActivity imposta android:taskAffinity="" (il valore predefinito di flutter create), rimuovilo oppure assegna alle activity dell’SDK la stessa affinity. In caso contrario, alcune build Android di determinati OEM possono perdere il checkout in corso e restituire PLATFORM_ERROR.

Utilizzo

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

Significato del risultato

result.status è un’indicazione per l’interfaccia, non una prova del pagamento. Conferma ogni pagamento dal tuo backend, tramite il webhook payment.succeeded / subscription.active.

CheckoutStatus

obbligatorio

Uno tra succeeded, failed, cancelled, pending, expired.

String?

Impostato quando l’URL di ritorno ne include uno. Visualizzalo nell’interfaccia, ma non usarlo per concedere l’accesso. Consulta Verifica il pagamento qui sotto.

String?

Impostato per i checkout degli abbonamenti.

List<String>?

Impostato quando il checkout include prodotti con chiavi di licenza.

String?

Impostato quando il checkout raccoglie un indirizzo email.

Map<String, String>

Ogni parametro di query dell’URL di ritorno, senza modifiche.

Verifica il pagamento

Webhooks

Dodo Payments chiama il tuo backend quando un pagamento va a buon fine o un abbonamento viene attivato.

Get Payment Detail

Cerca paymentId con la tua secret key per verificarne direttamente lo stato.

Concedi l’accesso dopo che uno di questi ha confermato il pagamento, mai basandoti solo su result.status.

Personalizzazione dell’aspetto

Personalizza la barra degli strumenti, i pulsanti e la combinazione di colori del browser di checkout tramite customization su CheckoutParams. Le opzioni sono raggruppate per piattaforma perché la Custom Tab di Android e SFSafariViewController di iOS espongono controlli nativi diversi. Tutti i campi sono facoltativi; se ometti customization viene utilizzato l’aspetto predefinito di ciascuna piattaforma.

Android — Custom Tab

Colore di sfondo della barra degli strumenti.

Colore della barra di navigazione.

Colore del divisore sopra la barra di navigazione.

CloseButtonStyle

standard mostra l’icona di sistema “X”; back disegna invece una freccia indietro.

CloseButtonPosition

Lato della barra degli strumenti in cui viene visualizzato il pulsante di chiusura.

Mostra l’icona di condivisione della barra degli strumenti.

bool

Mostra il titolo della pagina sotto l’URL nella barra degli strumenti.

bool

Consente alla barra degli strumenti di nascondersi automaticamente mentre si scorre la pagina.

bool

Mostra “Aggiungi questa pagina ai segnalibri” nel menu con altre opzioni.

bool

Mostra “Scarica pagina” nel menu con altre opzioni.

BrowserColorScheme

Imposta l’aspetto chiaro o scuro indipendentemente dalle impostazioni di sistema del dispositivo.

iOS — SFSafariViewController

DismissButtonStyle

Etichetta o icona del pulsante di chiusura.

PresentationStyle

pageSheet viene visualizzato come una scheda con chiusura tramite scorrimento; fullScreen copre l’intero schermo.

bool

Consente alla barra degli strumenti di comprimersi durante lo scorrimento. Visibile solo quando presentationStyle è fullScreen — pageSheet mantiene le barre fissate indipendentemente da questa impostazione.

BrowserColorScheme

Imposta l’aspetto chiaro o scuro indipendentemente dalle impostazioni di sistema del dispositivo.

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

Errori

start genera un’eccezione CheckoutException solo in caso di utilizzo errato o di un errore della piattaforma. Un pagamento annullato o rifiutato restituisce sempre un risultato, non un’eccezione.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): URL di sessione non checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): URL assoluto non valido.
alreadyInProgress (ALREADY_IN_PROGRESS): è già in corso un checkout.
platformError (PLATFORM_ERROR): errore imprevisto della piattaforma.

Sessioni abbandonate

Se l’app viene terminata durante il checkout, recupera la sessione al successivo avvio e riconcíliala con il tuo backend.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installazione

Utilizzo

Significato del risultato

Verifica il pagamento

Webhooks

Get Payment Detail

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​Installazione

​Utilizzo

​Significato del risultato

​Verifica il pagamento

Webhooks

Get Payment Detail

​Personalizzazione dell’aspetto

​Errori

​Sessioni abbandonate

​Correlati

Mobile Integration Guide

Community Projects

Installazione

Utilizzo

Significato del risultato

Verifica il pagamento

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati