> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Apri il checkout ospitato di Dodo Payments da un'app React Native in una scheda del browser di sistema e ottieni un risultato tipizzato con una sola chiamata.

<Info>
  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.
</Info>

<CardGroup cols={2}>
  <Card title="Checkout Sessions API" icon="cart-shopping" href="/developer-resources/checkout-session">
    Crea checkout\_url, che questo SDK apre, dal tuo backend.
  </Card>

  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Scopri come si inserisce nel flusso completo dei pagamenti mobile.
  </Card>
</CardGroup>

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.

<Warning>
  Questo SDK richiede esclusivamente la **New Architecture**, React Native 0.76+, iOS 16+ e Android `minSdk` 24.
</Warning>

## Installazione

<Steps>
  <Step title="Install the Package">
    <Tabs>
      <Tab title="Android">
        Il pacchetto viene collegato automaticamente e recupera `com.dodopayments.api:checkout-android` da Maven.

        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        ```

        Non è necessaria alcuna configurazione aggiuntiva; la dipendenza nativa viene risolta automaticamente.
      </Tab>

      <Tab title="iOS">
        ```sh theme={null}
        npm i @dodopayments/react-native-checkout
        cd ios && pod install
        ```

        Il core Swift è incluso nel pacchetto e viene installato tramite CocoaPods.
      </Tab>

      <Tab title="Expo">
        Solo build di sviluppo (non Expo Go).

        ```sh theme={null}
        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).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Register a Callback URL Scheme">
    La tua app deve registrare uno schema URL per ricevere l'URL di ritorno dal checkout.

    <Tabs>
      <Tab title="Android (Gradle)">
        In `android/app/build.gradle`:

        ```kotlin android/app/build.gradle theme={null}
        android {
            defaultConfig {
                manifestPlaceholders["dodoCallbackScheme"] = "myapp"
            }
        }
        ```

        Sostituisci `"myapp"` con lo schema della tua app.
      </Tab>

      <Tab title="iOS (Info.plist)">
        In `ios/YourApp/Info.plist`:

        ```xml Info.plist theme={null}
        <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.
      </Tab>

      <Tab title="Expo (both platforms)">
        In `app.json`:

        ```json app.json theme={null}
        {
          "expo": {
            "plugins": [
              [
                "expo-build-properties",
                {
                  "android": {
                    "manifestPlaceholders": {
                      "dodoCallbackScheme": "myapp"
                    }
                  }
                }
              ]
            ],
            "ios": {
              "infoPlist": {
                "CFBundleURLTypes": [
                  {
                    "CFBundleURLSchemes": ["myapp"]
                  }
                ]
              }
            }
          }
        }
        ```

        <Warning>
          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.
        </Warning>

        <Note>
          Ricostruisci il progetto nativo dopo aver modificato `app.json`:

          ```sh theme={null}
          npx expo prebuild --clean
          ```

          Funziona solo con le build di sviluppo, non con Expo Go.
        </Note>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Utilizzo

```typescript theme={null}
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.

```typescript theme={null}
import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

## Significato del risultato

<Warning>
  `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`.
</Warning>

<ParamField body="status" type="CheckoutStatus" required>
  Uno tra `succeeded`, `failed`, `cancelled`, `pending`, `expired`.
</ParamField>

<ParamField body="paymentId" type="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.
</ParamField>

<ParamField body="subscriptionId" type="string">
  Impostato per i checkout degli abbonamenti.
</ParamField>

<ParamField body="licenseKeys" type="string[]">
  Impostato quando il checkout include prodotti con chiavi di licenza.
</ParamField>

<ParamField body="customerEmail" type="string">
  Impostato quando il checkout acquisisce un indirizzo email.
</ParamField>

<ParamField body="raw" type="Record<string, string>">
  Ogni parametro di query dell'URL di ritorno, senza modifiche.
</ParamField>

## Verificare il pagamento

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Dodo Payments chiama il tuo backend quando un pagamento va a buon fine o un abbonamento viene attivato.
  </Card>

  <Card title="Get Payment Detail" icon="magnifying-glass" href="/api-reference/payments/get-payments-1">
    Cerca `paymentId` con la tua secret key per verificarne direttamente lo stato.
  </Card>
</CardGroup>

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.

```typescript theme={null}
import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

## Correlati

<CardGroup cols={2}>
  <Card title="Mobile Integration Guide" icon="mobile" href="/developer-resources/mobile-integration">
    Lo stesso contratto per Android, iOS e Flutter.
  </Card>

  <Card title="Expo Boilerplate" icon="layer-group" href="/developer-resources/expo-boilerplate">
    Un esempio Expo completo con integrazione del checkout.
  </Card>
</CardGroup>