React Native

Questo è l’SDK ufficiale per il checkout React Native di Dodo Payments, @dodopayments/react-native-checkout. Apre il checkout ospitato di Dodo in una vista browser nativa e restituisce un risultato tipizzato. Nota: esiste un pacchetto meno recente e non correlato denominato dodopayments-react-native-sdk (senza scope), con un’API completamente diversa. Questa pagina documenta esclusivamente l’attuale pacchetto ufficiale con scope.

Checkout Sessions API

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

Mobile Integration Guide

Scopri come si inserisce nel flusso completo dei pagamenti mobile.

L’SDK React Native è un sottile wrapper Turbo Module sui medesimi core nativi Swift e Kotlin. Apre SFSafariViewController su iOS e una Chrome Custom Tab su Android, non conserva alcuna chiave API e non chiama mai direttamente l’API di Dodo. Tutta la logica del checkout viene eseguita nel browser; l’SDK gestisce semplicemente il ciclo di vita della vista e acquisisce l’URL di ritorno.

Questo SDK richiede esclusivamente la New Architecture, React Native 0.76+, iOS 16+ e Android minSdk 24.

Installazione

Install the Package

Android
iOS
Expo

Il pacchetto viene collegato automaticamente e recupera com.dodopayments.api:checkout-android da Maven.

npm i @dodopayments/react-native-checkout

Non è necessaria alcuna configurazione aggiuntiva; la dipendenza nativa viene risolta automaticamente.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Il core Swift è incluso nel pacchetto e viene installato tramite CocoaPods.

Solo build di sviluppo (non Expo Go).

npm i @dodopayments/react-native-checkout
npx expo install expo-build-properties

Quindi configura il tuo app.json (vedi Registrare uno schema URL per i callback di seguito).

La tua app deve registrare uno schema URL per ricevere l’URL di ritorno dal checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

In android/app/build.gradle:

android/app/build.gradle

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

Sostituisci "myapp" con lo schema della tua app.

In ios/YourApp/Info.plist:

Info.plist

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

Puoi anche aggiungerlo tramite l’interfaccia Info → URL Types di Xcode.

In app.json:

app.json

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

Il pacchetto include anche un plugin di configurazione Expo @dodopayments/react-native-checkout, ma attualmente non inserisce alcuno schema URL né alcun manifest placeholder. Aggiungerlo da solo non registrerà lo schema per i callback: usa la configurazione expo-build-properties e infoPlist riportata sopra.

Ricostruisci il progetto nativo dopo aver modificato app.json:

npx expo prebuild --clean

Funziona solo con le build di sviluppo, non con Expo Go.

Utilizzo

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

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

Inoltro dell’URL di ritorno

Il listener Linking è necessario per la gestione dell’URL di ritorno su iOS. Su Android, handleOpenURL è un no-op che risolve false, poiché il core Android gestisce il redirect in modo nativo. È sicuro registrare il listener incondizionatamente su entrambe le piattaforme.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Significato del risultato

result.status è un suggerimento 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 includeva uno. Visualizzalo nell’interfaccia, ma non usarlo per concedere l’accesso. Vedi Verificare il pagamento di seguito.

string

Impostato per i checkout degli abbonamenti.

string[]

Impostato quando il checkout include prodotti con chiavi di licenza.

string

Impostato quando il checkout acquisisce un indirizzo email.

Record<string, string>

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

Verificare 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.

Errori

start restituisce un errore CheckoutError solo in caso di uso errato o di un errore della piattaforma. Un pagamento annullato o rifiutato è sempre un risultato, mai un’eccezione.

INVALID_CHECKOUT_URL: non è un URL di sessione checkout.dodopayments.com.
INVALID_RETURN_URL: non è un URL assoluto valido.
ALREADY_IN_PROGRESS: è già in esecuzione un checkout.
PLATFORM_ERROR: errore imprevisto della piattaforma.

Sessioni abbandonate

Se l’app o il bundle JS viene terminato durante il checkout, la promise viene persa, ma il livello nativo mantiene la sessione. Recuperala al successivo mount e riconcíliala con il tuo backend.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installazione

Utilizzo

Inoltro dell’URL di ritorno

Significato del risultato

Verificare il pagamento

Webhooks

Get Payment Detail

Errori

Sessioni abbandonate

Correlati

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Installazione

​Utilizzo

​Inoltro dell’URL di ritorno

​Significato del risultato

​Verificare il pagamento

Webhooks

Get Payment Detail

​Errori

​Sessioni abbandonate

​Correlati

Mobile Integration Guide

Expo Boilerplate

Installazione

Utilizzo

Inoltro dell’URL di ritorno

Significato del risultato

Verificare il pagamento

Errori

Sessioni abbandonate

Correlati