# Connettere un lettore

Connetti l'applicazione a un lettore Stripe Terminal.

> Se non hai ancora scelto un lettore, confronta i [lettori Terminal](https://docs.stripe.com/terminal/payments/setup-reader.md) disponibili e scegli quello più adatto alle tue esigenze.

# Lettore simulato

> This is a Lettore simulato for when terminal-sdk-platform is server-driven and reader-type is simulated. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=server-driven&reader-type=simulated.

Stripe fornisce un lettore basato su server simulato, in modo tale che tu possa sviluppare e testare l’app e simulare i pagamenti con Terminal senza connetterti all’hardware fisico.

## Creare un lettore simulato

Per creare un lettore simulato, utilizza uno dei codici di registrazione designati (`simulated-wpe`, `simulated-s700`, o `simulated-s710`) al momento della registrazione del lettore. Questo codice di registrazione crea un oggetto WisePOS E, lettore Stripe S700 o lettore Stripe S710 simulato solo in una sandbox. Puoi registrare il lettore simulato utilizzando l’API Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "location={{TERMINALLOCATION_ID}}" \
  -d registration_code=simulated-wpe
```

Restituisce un oggetto [reader](https://docs.stripe.com/api/terminal/readers.md) che rappresenta il lettore simulato:

```json
{
  "id": "tmr_xxx",
  "object": "terminal.reader",
  "device_sw_version": "2.37.2.0",
  "device_type": "simulated_wisepos_e",
  "ip_address": "0.0.0.0",
  "label": "simulated-wpe-xxx-xxx-xx-xxx",
  "livemode": false,
  "location": "tml_xxx",
  "serial_number": "simulated-wpe-xxx-xxx-xx-xxx",
  "status": "online"
}
```

## Interrogare il lettore simulato

Il lettore simulato si comporta come un lettore reale. Puoi recuperare le informazioni dall’[endpoint del lettore](https://docs.stripe.com/api/terminal/readers/retrieve.md):

```curl
curl https://api.stripe.com/v1/terminal/readers/tmr_xxx \
  -u "<<YOUR_SECRET_KEY>>:"
```

```json
{
  "id": "tmr_xxx",
  "object": "terminal.reader",
  "action": null,
  "device_sw_version": "2.37.2.0",
  "device_type": "simulated_wisepos_e",
  "ip_address": "0.0.0.0",
  "label": "simulated-wpe-xxx-xxx-xx-xxx",
  "livemode": false,
  "location": "tml_xxx",
  "metadata": {
  },
  "serial_number": "simulated-wpe-xxx-xxx-xx-xxx",
  "status": "offline"
}
```


# Lettore simulato

> This is a Lettore simulato for when terminal-sdk-platform is js and reader-type is simulated. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=js&reader-type=simulated.

Gli SDK di Stripe Terminal e l’integrazione basata su server sono dotati di un lettore di carte simulato integrato, quindi puoi sviluppare e testare l’app senza connetterti all’hardware fisico. Se l’integrazione è completa o la stai ancora sviluppando, utilizza il lettore simulato per emulare tutti i flussi di Terminal nell’app.

Il lettore simulato non fornisce una interfaccia utente. Dopo aver effettuato la connessione nella tua app, la conferma del corretto funzionamento avviene quando le chiamate all’SDK o all’API di Stripe vanno a buon fine.

I lettori simulati per gli SDK simulano automaticamente la presentazione delle carte in base alle esigenze. Per l’integrazione basata su server, aggiorna l’integrazione per [simulare la presentazione della carta](https://docs.stripe.com/terminal/references/testing.md#simulated-card-presentment).

Per utilizzare il lettore simulato, chiama [discoverReaders](https://docs.stripe.com/terminal/references/api/js-sdk.md#discover-readers) per cercare i lettori, con l’opzione `simulated` impostata su `true`. Quando `discoverReaders` restituisce un risultato, chiama [connectReader](https://docs.stripe.com/terminal/references/api/js-sdk.md#connect-reader) per connetterti al lettore simulato.

```javascript
// Handler for a "Connect Reader" button
async function connectReaderHandler() {
  const config = {simulated: true};
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // Just select the first reader here.
    const selectedReader = discoverResult.discoveredReaders[0];

    const connectResult = await terminal.connectReader(selectedReader);
    if (connectResult.error) {
      console.log('Failed to connect: ', connectResult.error);
    } else {
      console.log('Connected to reader: ', connectResult.reader.label);
    }
  }
}
```

### Configurazione lettore simulato

- [setSimulatorConfiguration (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-setsimulatorconfig)

Puoi configurare il lettore simulato per testare vari flussi nella tua applicazione POS, ad esempio circuiti carta diversi o scenari di errore come un addebito rifiutato. Per attivare questo comportamento, utilizza il codice seguente prima di acquisire il metodo di pagamento:

```javascript
terminal.setSimulatorConfiguration({testCardNumber: '4242424242424242'});
```


# Lettore simulato

> This is a Lettore simulato for when terminal-sdk-platform is ios and reader-type is simulated. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=simulated.

Gli SDK di Stripe Terminal e l’integrazione basata su server sono dotati di un lettore di carte simulato integrato, quindi puoi sviluppare e testare l’app senza connetterti all’hardware fisico. Se l’integrazione è completa o la stai ancora sviluppando, utilizza il lettore simulato per emulare tutti i flussi di Terminal nell’app.

Il lettore simulato non fornisce una interfaccia utente. Dopo aver effettuato la connessione nella tua app, la conferma del corretto funzionamento avviene quando le chiamate all’SDK o all’API di Stripe vanno a buon fine.

I lettori simulati per gli SDK simulano automaticamente la presentazione delle carte in base alle esigenze. Per l’integrazione basata su server, aggiorna l’integrazione per [simulare la presentazione della carta](https://docs.stripe.com/terminal/references/testing.md#simulated-card-presentment).

Per utilizzare il lettore simulato, chiama [discoverReaders](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:) per cercare i lettori, con l’opzione `simulated` impostata su `true`. Quando `discoverReaders` restituisce un risultato, chiama [connectReader](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:delegate:completion:) per connetterti al lettore simulato.

Quando ti connetti a un lettore mobile o a un lettore Tap to Pay, la tua integrazione deve includere il parametro `locationId` nella configurazione della connessione, anche per il lettore simulato. Dato che il lettore simulato non può essere associato a una posizione reale, fornisci invece il parametro `locationId` fittizio del lettore simulato.

```swift
import UIKit
import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {let config = try BluetoothScanDiscoveryConfigurationBuilder().setSimulated(true).build()
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    // This delegate method can get called multiple times throughout the discovery process.
    // You might want to update a UITableView and display all available readers.
    // Here, we're automatically connecting to the first reader we discover.
    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {

        // Select the first reader we discover
        guard let selectedReader = readers.first else { return }

        // Since the simulated reader is not associated with a real location, we recommend
        // specifying its existing mock location.
        guard let locationId = selectedReader.locationId else { return }

        // Only connect if we aren't currently connected.
        guard terminal.connectionStatus == .notConnected || terminal.connectionStatus == .discovering else { return }
// Replace 'yourMobileReaderDelegate' with your actual MobileReaderDelegate implementation
        let mobileReaderDelegate = yourMobileReaderDelegate
        do {
            connectionConfig = try BluetoothConnectionConfigurationBuilder(
                // When connecting to a physical reader, your integration should specify either the
                // same location as the last connection (selectedReader.locationId) or a new location
                // of your user's choosing.
                delegate: mobileReaderDelegate,
                locationId: locationId
            )
            .setAutoReconnectOnUnexpectedDisconnect(true) // This is optional as it's the default value
            .build()
        } catch {
            // Handle error building the connection configuration
            return
        }

        // Note `readerDelegate` should be provided by your application.
        // See our Quickstart guide at https://stripe.com/docs/terminal/quickstart
        // for more example code.
        Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
            if let reader = reader {
                print("Successfully connected to reader: \(reader)")
            } else if let error = error {
                print("connectReader failed: \(error)")
            }
        }
    }
}
```

### Configurazione lettore simulato

- [SimulatorConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPSimulatorConfiguration.html)

Puoi configurare il lettore simulato per testare vari flussi nella tua applicazione POS, ad esempio circuiti carta diversi o scenari di errore come un addebito rifiutato. Per attivare questo comportamento, utilizza il codice seguente prima di acquisire il metodo di pagamento:

#### Swift

```swift
let simulatorConfiguration = Terminal.shared.simulatorConfiguration
simulatorConfiguration.simulatedCard = SimulatedCard(type: .amex)
simulatorConfiguration.simulatedTipAmount = 1000
```


# Lettore simulato

> This is a Lettore simulato for when terminal-sdk-platform is android and reader-type is simulated. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=simulated.

Gli SDK di Stripe Terminal e l’integrazione basata su server sono dotati di un lettore di carte simulato integrato, quindi puoi sviluppare e testare l’app senza connetterti all’hardware fisico. Se l’integrazione è completa o la stai ancora sviluppando, utilizza il lettore simulato per emulare tutti i flussi di Terminal nell’app.

Il lettore simulato non fornisce una interfaccia utente. Dopo aver effettuato la connessione nella tua app, la conferma del corretto funzionamento avviene quando le chiamate all’SDK o all’API di Stripe vanno a buon fine.

I lettori simulati per gli SDK simulano automaticamente la presentazione delle carte in base alle esigenze. Per l’integrazione basata su server, aggiorna l’integrazione per [simulare la presentazione della carta](https://docs.stripe.com/terminal/references/testing.md#simulated-card-presentment).

Per utilizzare il lettore simulato, chiama [discoverReaders](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html) per cercare i lettori, con l’opzione `isSimulated` nella `DiscoveryConfiguration` scelta impostata su `true`. Quando `discoverReaders` restituisce un risultato, chiama [connectReader](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html) per connetterti al lettore simulato.

Quando ti connetti a un lettore mobile, la tua integrazione deve includere il parametro `locationId` nella configurazione della connessione, anche per il lettore simulato. Dato che il lettore simulato non può essere associato a una posizione reale, fornisci invece il parametro `locationId` fittizio del lettore simulato.

```kotlin
// Handler for a "Connect Reader" button
fun onConnect() {
    val config = BluetoothDiscoveryConfiguration(timeout = 0, isSimulated = true)

    Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Select the first reader here.
                val firstReader = readers.first()
                // Replace 'yourMobileReaderListener' with your actual MobileReaderListener implementation
                val mobileReaderListener = yourMobileReaderListener
                val autoReconnectOnUnexpectedDisconnect = true

                // When connecting to a physical reader, specify either the
                // same location as the last connection (selectedReader.location?.id) or a new location
                // of your user's choosing.
                //
                // Since the simulated reader isn't associated with a real location, we recommend
                // specifying its existing mock location.
                val connectionConfig = BluetoothConnectionConfiguration(
                    locationId = firstReader.location?.id.orEmpty(),
                    autoReconnectOnUnexpectedDisconnect = autoReconnectOnUnexpectedDisconnect,
                    bluetoothReaderListener = mobileReaderListener
                )

                Terminal.getInstance().connectReader(
                    firstReader,
                    connectionConfig,
                    object : ReaderCallback {
                        override fun onSuccess(reader: Reader) {
                            // Placeholder for handling successful operation
                        }

                        override fun onFailure(e: TerminalException) {
                            // Placeholder for handling exception
                        }
                    }
                )
            }
        },
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}
```

### Configurazione lettore simulato

- [SimulatorConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-simulator-configuration/index.html)

Puoi configurare il lettore simulato per testare vari flussi nella tua applicazione POS, ad esempio circuiti carta diversi o scenari di errore come un addebito rifiutato. Per attivare questo comportamento, utilizza il codice seguente prima di acquisire il metodo di pagamento:

#### Kotlin

```kotlin
val simulatedFixedTipAmount = 1000L;

val simulatorConfig = SimulatorConfiguration(
    simulatedCard = SimulatedCard(SimulatedCardType.AMEX),
    simulatedTipAmount = simulatedFixedTipAmount
);

Terminal.getInstance().setSimulatorConfiguration(simulatorConfig);
```


# Lettore simulato

> This is a Lettore simulato for when terminal-sdk-platform is react-native and reader-type is simulated. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=react-native&reader-type=simulated.

Gli SDK di Stripe Terminal e l’integrazione basata su server sono dotati di un lettore di carte simulato integrato, quindi puoi sviluppare e testare l’app senza connetterti all’hardware fisico. Se l’integrazione è completa o la stai ancora sviluppando, utilizza il lettore simulato per emulare tutti i flussi di Terminal nell’app.

Il lettore simulato non fornisce una interfaccia utente. Dopo aver effettuato la connessione nella tua app, la conferma del corretto funzionamento avviene quando le chiamate all’SDK o all’API di Stripe vanno a buon fine.

I lettori simulati per gli SDK simulano automaticamente la presentazione delle carte in base alle esigenze. Per l’integrazione basata su server, aggiorna l’integrazione per [simulare la presentazione della carta](https://docs.stripe.com/terminal/references/testing.md#simulated-card-presentment).

Per utilizzare il lettore simulato, chiama [discoverReaders](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverReaders) per cercare i lettori, con l’opzione `simulated` impostata su `true`. Quando viene chiamato il callback `onUpdateDiscoveredReaders` con un array di lettori come argomento, chiama [connectReader](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1) per connetterti al lettore simulato.

Quando ti connetti a un lettore mobile o a un lettore TapToPay, la tua integrazione deve includere il parametro `locationId` nella configurazione della connessione, anche per il lettore simulato. Dato che il lettore simulato non può essere associato a una posizione reale, fornisci invece il parametro `locationId` fittizio del lettore simulato.

```js
function DiscoverReadersScreen() {
  const { discoverReaders, connectReader, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
        // Here, we're automatically connecting to the first discovered reader.
        handleConnectBluetoothReader(readers[0]);
      },
    });

  useEffect(() => {
    handleDiscoverReaders();
  }, []);

  const handleDiscoverReaders = async () => {
    // The list of discovered readers is reported in the `onUpdateDiscoveredReaders` method
    // within the `useStripeTerminal` hook.
    const { error } = await discoverReaders({
      discoveryMethod: 'bluetoothScan',
      simulated: true,
    });

    if (error) {
      Alert.alert(
        'Discover readers error: ',
        `${error.code}, ${error.message}`
      );
    }
  };

  const handleConnectBluetoothReader = async (discoveredReader: Reader.Type) => {
    const { reader, error } = await connectReader({
        discoveryMethod: 'bluetoothScan',
        reader: discoveredReader,
        // Since the simulated reader is not associated with a real location, we recommend
        // specifying its existing mock location.
        locationId: discoveredReader.locationId,
      });

    if (error) {
      console.log('connectReader error', error);
      return;
    }

    console.log('Reader connected successfully', reader);
  };

  return <View />;
}
```

### Configurazione lettore simulato

- [setSimulatedCard (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#setSimulatedCard)

Puoi configurare il lettore simulato per testare vari flussi nella tua applicazione POS, ad esempio circuiti carta diversi o scenari di errore come un addebito rifiutato. Per attivare questo comportamento, utilizza il codice seguente prima di acquisire il metodo di pagamento:

```js
const { error } = await setSimulatedCard('4242424242424242');

if (error) {
  // Placeholder for handling exception
}

// Placeholder for handling successful operation
```


# Lettori Bluetooth

> This is a Lettori Bluetooth for when terminal-sdk-platform is ios and reader-type is bluetooth. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=bluetooth.

I lettori connessi tramite Bluetooth sono dispositivi Bluetooth LE. Raccolgono i dati di pagamento, ma si basano su un dispositivo mobile associato per la comunicazione con Stripe.

Per connettere l’app a un lettore Terminal tramite Bluetooth, attieniti a questa procedura:

1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers).
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader).

> Non utilizzare le impostazioni del dispositivo mobile per abbinarle al lettore. L’associazione del lettore alle impostazioni del dispositivo rende il lettore non disponibile per la connessione all’app.

## Rilevare i lettori [Lato client]

- [discoverReaders (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:)
- [BluetoothScanDiscoveryConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothScanDiscoveryConfiguration.html)

Per iniziare, accertati che il lettore sia acceso e nelle immediate vicinanze.

Quindi, dall’app, cerca i lettori connessi via Bluetooth nelle vicinanze con il metodo `discoverReaders` , utilizzando `BluetoothScanDiscoveryConfiguration`.

#### Swift

```swift
import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try BluetoothScanDiscoveryConfigurationBuilder().build()
        // In addition to Terminal's completion block methods, Swift async alternatives are available.
        // See our Example app for usage examples: https://github.com/stripe/stripe-terminal-ios/tree/master/Example
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

```

#### Prossimità Bluetooth  * (BBPOS Chipper 2X BT only)

I risultati di ricerca dei filtri di prossimità Bluetooth restituiscono il lettore più vicino. Una volta individuato, sul lettore lampeggiano luci multicolori per consentire all’utente di identificare il lettore individuato tra molti altri lettori. Dopo che l’SDK ha individuato un lettore, non passa a un lettore più vicino a meno che il lettore individuato non si spenga.

Quando utilizzi la prossimità Bluetooth, l’SDK restituisce due volte il lettore al callback dell’app. La prima volta, l’app riceve un oggetto `Reader` popolato solo con il numero di serie del lettore. Dopo un breve ritardo, l’app riceve lo stesso oggetto `Reader` popolato con nuove informazioni, ad esempio il livello della batteria del lettore.

Consigliamo di visualizzare il lettore individuato nell’interfaccia utente dell’app, per consentire all’utente di confermare la connessione al lettore o di annullarla se non vuole connettersi a questo lettore.

#### Scansione Bluetooth

La scansione Bluetooth cerca tutti i lettori nelle vicinanze e restituisce all’app un elenco dei lettori individuati. Mentre è in corso la scansione, l’SDK continua a chiamare il metodo `DiscoveryDelegate.didUpdateDiscoveredReaders` con l’elenco più recente dei lettori nelle vicinanze.

Durante il processo di individuazione, lo stato `SCPConnectionStatus` di Terminal passa a `SCPConnectionStatus.SCPConnectionStatusDiscovering` mentre è in corso l’individuazione.

Con il metodo di rilevamento tramite scansione Bluetooth, puoi impostare un timeout per eseguire la scansione per un determinato periodo di tempo. In questo modo puoi gestire la durata della batteria o attivare un messaggio di errore se non vengono trovati dispositivi.

Nell’applicazione mobile, si consiglia di visualizzare un elenco aggiornato automaticamente dei lettori rilevati con i numeri di serie per aiutare gli utenti a identificare il proprio lettore mobile. La proprietà `label` non viene compilata per i lettori mobili durante il rilevamento dei lettori. Se è necessario visualizzare nomi descrittivi per i lettori, mantenere la propria mappatura dei numeri di serie alle etichette nell’applicazione.

#### Abbinamento Bluetooth

Per migliorare la sicurezza ed essere conforme alle normative UE, dal novembre 2025 Stripe elabora il confronto numerico tramite Bluetooth dei lettori di carte WisePad 3. Il processo di confronto numerico richiede la verifica di una passkey sul lettore di carte e sul dispositivo POS durante l’associazione. Dopo aver aggiornato il dispositivo all’[ultima versione del software](https://docs.stripe.com/terminal/readers/bbpos-wisepad3.md#reader-software-releases), segui questa procedura quando colleghi il WisePad 3 a una nuova applicazione mobile. A questo punto il dispositivo POS individuo e visualizza il lettore WisePad 3:

1. Verifica che il codice a 6 cifre corrisponda sul WisePad 3 e sul dispositivo POS.
1. Seleziona **Conferma** sul WisePad 3.
1. Seleziona **Abbina** sul dispositivo POS.

> #### Nota
> 
> È sufficiente eseguire il confronto numerico quando si associa un WisePad 3 a un nuovo POS, o quando si esegue nuovamente il confronto con POS “dimenticato” esistente.

## Connettere un lettore [Lato client]

- [connectReader (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:connectionConfig:completion:)
- [BluetoothConnectionConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPBluetoothConnectionConfiguration.html)

Per connetterti a un lettore individuato, chiama il metodo `connectReader` dall’app.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tal scopo, durante la connessione, crea e utilizza una `BluetoothConnectionConfiguration` con `locationId` impostato sull’ID posizione pertinente.

#### Swift

```swift
// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: ""{{LOCATION_ID}}"")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}
```

Affinché la tua app venga eseguita in background e rimanga connessa al lettore, [configurala](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=ios#configure) per includere la modalità di background richiesta.

> #### Utilizzare la modalità standby
> 
> Non programmare la tua app per chiamare `disconnectReader` per risparmiare energia. Il lettore gestisce in modo efficiente l’alimentazione utilizzando la modalità standby.

## Gestire le disconnessioni del lettore

- [MobileReaderDelegate (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPMobileReaderDelegate.html)
- [DisconnectReason (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPDisconnectReason.html)

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dall’app se è fuori portata o la batteria è scarica. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

Il `MobileReaderDelegate` include un metodo `reader:didDisconnect:` che fornisce all’applicazione il `DisconnectReason` per consentire di identificare il motivo della disconnessione del lettore.

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su `false` durante la connessione.
1. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

#### Swift

```swift
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}
```

### Riavviare il lettore connesso

- [rebootReader (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)rebootReader:.html)

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API `rebootReader`. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

#### Swift

```swift
Terminal.shared.rebootReader { error in
    if let error = error {
        // Placeholder for handling the error
    } else {
        // Reboot succeeded and the reader will disconnect.
        // If your app is using automatic reconnect the reconnect will begin.
    }
}

```

#### Tentare automaticamente la riconnessione

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Implementa i callback di riconnessione del lettore in `MobileReaderDelegate`.
1. Specifica il `MobileReaderDelegate` in `BluetoothConnectionConfiguration`.
1. Quando l’SDK invia [`reader:didStartReconnect:disconnectReason:`](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)reader:didStartReconnect:disconnectReason:) alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   - Puoi utilizzare l’oggetto `Cancelable` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Quando l’SDK indica l’avvenuta riconnessione inviando [`readerDidSucceedReconnect:`](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)readerDidSucceedReconnect:), visualizza un messaggio che annuncia che la connessione è stata ripristinata e di continuare le normali operazioni.
1. Se l’SDK non riesce a riconnettersi al lettore e invia sia [`readerDidFailReconnect:`](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)readerDidFailReconnect:) che`reader:didDisconnect:`, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

#### Swift

```swift
import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}
```

#### Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults) (iOS).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

## Aggiorna il software del lettore [Lato client]



- [MobileReaderDelegate (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPMobileReaderDelegate.html)

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

- Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
- Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

> Per installare gli aggiornamenti, il livello della batteria del lettore deve essere superiore al 50%.

### Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, il `MobileReaderDelegate` dell’integrazione riceve il callback `didStartInstallingUpdate` con un `ReaderSoftwareUpdate`.

Il `ReaderSoftwareUpdate` fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da `durationEstimate`.

Durante la procedura di installazione, lo stato `connectionStatus`di Terminal diventa `connecting` mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore a `MobileReaderDelegate` con `didFinishInstallingUpdate`. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

- Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
- La versione dell’SDK iOS è successiva o uguale alla `3.5.0`.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

#### Swift

```swift
import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // Show UI communicating that a required update has started installing
    }

    func reader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // Update the progress of the installation
    }

    func reader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // Report success or failure of the update
    }

    // ...
}
```

Puoi annullare gli aggiornamenti richiesti utilizzando l’oggetto `Cancelable`, il che comporta anche un errore nella connessione al lettore. Non puoi annullare gli aggiornamenti incrementali in corso.

### Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti notifica gli aggiornamenti facoltativi tramite `MobileReaderDelegate` ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, il `MobileReaderDelegate` dell’applicazione riceve il callback `didReportAvailableUpdate` con l’oggetto `ReaderSoftwareUpdate` contenente i dettagli dell’aggiornamento, tra cui:

- Tempo stimato per il completamento dell’aggiornamento (`durationEstimate`)
- Timestamp dopo il quale l’aggiornamento diventa obbligatorio (`requiredAt`)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con `didReportAvailableUpdate`, chiama `Terminal.shared.installAvailableUpdate`.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come `reader.availableUpdate`.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedigli di tenere il lettore a portata di mano e acceso fino al completamento dell’operazione. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. `MobileReaderDelegate` segnala lo stato di avanzamento dell’aggiornamento nel metodo `didReportReaderSoftwareUpdateProgress`.

Se la data `requiredAt` di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

#### Swift

```swift
import UIKit
import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {

    // ...

    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didReportAvailableUpdate update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.shared.installAvailableUpdate`.
    }

}
```

Consulta [Testare gli aggiornamenti del lettore Bluetooth](https://docs.stripe.com/terminal/references/testing.md#simulated-reader-updates) per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.


# Lettori Bluetooth

> This is a Lettori Bluetooth for when terminal-sdk-platform is android and reader-type is bluetooth. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=bluetooth.

I lettori connessi tramite Bluetooth sono dispositivi Bluetooth LE. Raccolgono i dati di pagamento, ma si basano su un dispositivo mobile associato per la comunicazione con Stripe.

Per connettere l’app a un lettore Terminal tramite Bluetooth, attieniti a questa procedura:

1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers).
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader).

> Non utilizzare le impostazioni del dispositivo mobile per abbinarle al lettore. L’associazione del lettore alle impostazioni del dispositivo rende il lettore non disponibile per la connessione all’app.

## Rilevare i lettori [Lato client]

- [discoverReaders (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html)
- [BluetoothDiscoveryConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-bluetooth-discovery-configuration/index.html)

Per iniziare, accertati che il lettore sia acceso e nelle immediate vicinanze.

Quindi, dall’app, cerca i lettori connessi tramite Bluetooth nelle vicinanze con il metodo `discoverReaders`, utilizzando `BluetoothDiscoveryConfiguration`.

#### Kotlin

```kotlin
class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {

    var discoverCancelable: Cancelable? = null

    // ...

    // Action for a "Discover Readers" button
    fun discoverReadersAction() {
        val timeout = 0
        val isSimulated = false

        val config = BluetoothDiscoveryConfiguration(
            timeout = timeout,
            isSimulated = isSimulated
        )

        discoverCancelable = Terminal.getInstance().discoverReaders(
            config,
            this,
            object : Callback {
                override fun onSuccess() {
                    // Placeholder for handling successful operation
                }

                override fun onFailure(e: TerminalException) {
                    // Placeholder for handling exception
                }
            }
        )
    }

    // DiscoveryListener
    override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}
```

#### Scansione Bluetooth

La scansione Bluetooth cerca tutti i lettori nelle vicinanze e restituisce all’app un elenco dei lettori individuati. Mentre è in corso la scansione, l’SDK continua a chiamare il metodo `onUpdateDiscoveredReaders` con l’elenco più recente dei lettori nelle vicinanze.

Durante il processo di individuazione, lo stato `connectionStatus` di Terminal passa a `ConnectionStatus.DISCOVERING` mentre è in corso l’individuazione.

Con il metodo di rilevamento tramite scansione Bluetooth, puoi impostare un timeout per eseguire la scansione per un determinato periodo di tempo. In questo modo puoi gestire la durata della batteria o attivare un messaggio di errore se non vengono trovati dispositivi.

Nell’applicazione mobile, si consiglia di visualizzare un elenco aggiornato automaticamente dei lettori rilevati con i numeri di serie per aiutare gli utenti a identificare il proprio lettore mobile. La proprietà `label` non viene compilata per i lettori mobili durante il rilevamento dei lettori. Se è necessario visualizzare nomi descrittivi per i lettori, mantenere la propria mappatura dei numeri di serie alle etichette nell’applicazione.

#### Abbinamento Bluetooth

Per migliorare la sicurezza ed essere conforme alle normative UE, dal novembre 2025 Stripe elabora il confronto numerico tramite Bluetooth dei lettori di carte WisePad 3. Il processo di confronto numerico richiede la verifica di una passkey sul lettore di carte e sul dispositivo POS durante l’associazione. Dopo aver aggiornato il dispositivo all’[ultima versione del software](https://docs.stripe.com/terminal/readers/bbpos-wisepad3.md#reader-software-releases), segui questa procedura quando colleghi il WisePad 3 a una nuova applicazione mobile. A questo punto il dispositivo POS individuo e visualizza il lettore WisePad 3:

1. Verifica che il codice a 6 cifre corrisponda sul WisePad 3 e sul dispositivo POS.
1. Seleziona **Conferma** sul WisePad 3.
1. Seleziona **Abbina** sul dispositivo POS.

> #### Nota
> 
> È sufficiente eseguire il confronto numerico quando si associa un WisePad 3 a un nuovo POS, o quando si esegue nuovamente il confronto con POS “dimenticato” esistente.

## Connettere un lettore [Lato client]

- [connectReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html)
- [BluetoothConnectionConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-bluetooth-connection-configuration/index.html)

Per connetterti a un lettore individuato, chiama il metodo `connectReader` dall’app.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tal scopo, durante la connessione, crea e utilizza una `BluetoothConnectionConfiguration` con `locationId` impostato sull’ID posizione pertinente.

#### Kotlin

```kotlin
// Implement your MobileReaderListener
val mobileReaderListener = yourMobileReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val connectionConfig = BluetoothConnectionConfiguration(
    ""{{LOCATION_ID}}"",
    autoReconnectOnUnexpectedDisconnect,
    mobileReaderListener
)

Terminal.getInstance().connectReader(
    selectedReader,
    connectionConfig,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

> #### Utilizzare la modalità standby
> 
> Non programmare la tua app per chiamare `disconnectReader` per risparmiare energia. Il lettore gestisce in modo efficiente l’alimentazione utilizzando la modalità standby.

## Gestire le disconnessioni del lettore

- [MobileReaderListener (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html)
- [DisconnectReason (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-disconnect-reason/index.html)

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dall’app se è fuori portata o la batteria è scarica. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

Il `MobileReaderListener` include il callback `onDisconnect` che fornisce all’applicazione il `DisconnectReason` per consentire di identificare il motivo della disconnessione del lettore.

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su `false` durante la connessione.
1. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}
```

### Riavviare il lettore connesso

- [rebootReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/reboot-reader.html)

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API `rebootReader`. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

#### Kotlin

```kotlin
Terminal.getInstance().rebootReader(
    object : Callback {
        override fun onSuccess() {
            // Reboot succeeded and the reader will disconnect.
            // If your app is using automatic reconnect the reconnect will begin.
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

#### Tentare automaticamente la riconnessione

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Implementa i callback di riconnessione del lettore in `MobileReaderListener`.
1. Specifica il `MobileReaderListener` in `BluetoothConnectionConfiguration`.
1. Quando l’SDK invia [onReaderReconnectStarted](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-started.html) alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   - Puoi utilizzare l’oggetto `Cancelable` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Quando l’SDK indica l’avvenuta riconnessione inviando [`onReaderReconnectSucceeded`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-succeeded.html), visualizza un messaggio che annuncia che la connessione è stata ripristinata e di continuare le normali operazioni.
1. Se l’SDK non è in grado di riconnettersi al lettore e invia sia [`onReaderReconnectFailed`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-failed.html) che `onDisconnect`, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

#### Kotlin

```kotlin
class CustomMobileReaderListener : MobileReaderListener {
    // ...

    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }

    // ...
}
```

#### Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences) (Android).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

## Aggiorna il software del lettore [Lato client]



- [MobileReaderListener (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html)

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

- Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
- Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

> Per installare gli aggiornamenti, il livello della batteria del lettore deve essere superiore al 50%.

### Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, il `MobileReaderListener` dell’integrazione riceve un `onStartInstallingUpdate` con un `ReaderSoftwareUpdate`.

Il `ReaderSoftwareUpdate` fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da `durationEstimate`.

Durante la procedura di installazione, lo stato `connectionStatus`di Terminal diventa `ConnectionStatus.CONNECTING` mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore a `MobileReaderListener` con `onFinishInstallingUpdate`. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

- Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
- La versione dell’SDK Android è successiva o uguale alla `3.5.0`.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onStartInstallingUpdate(update: ReaderSoftwareUpdate, cancelable: Cancelable) {
        // Show UI communicating that a required update has started installing
    }

    override fun onReportReaderSoftwareUpdateProgress(progress: Float) {
        // Update the progress of the installation
    }

    override fun onFinishInstallingUpdate(update: ReaderSoftwareUpdate?, e: TerminalException?) {
        // Report success or failure of the update
    }

    // ...
}
```

Puoi annullare gli aggiornamenti richiesti utilizzando l’oggetto `Cancelable`, il che comporta anche un errore nella connessione al lettore. Non puoi annullare gli aggiornamenti incrementali in corso.

### Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti avvisa degli aggiornamenti facoltativi tramite `MobileReaderListener` ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, il `MobileReaderListener` dell’applicazione riceve il callback `onReportAvailableUpdate` con l’oggetto `ReaderSoftwareUpdate` contenente i dettagli dell’aggiornamento, tra cui:

- Tempo stimato per il completamento dell’aggiornamento (`durationEstimate`)
- Data a partire dalla quale l’aggiornamento diventa obbligatorio (`requiredAt`)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con `onReportAvailableUpdate`, chiama `Terminal.getInstance().installAvailableUpdate`.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come `reader.availableUpdate`.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedigli di tenere il lettore a portata di mano e acceso fino al completamento dell’operazione. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. Il `MobileReaderListener` segnala lo stato di avanzamento dell’aggiornamento nel metodo `onReportReaderSoftwareUpdateProgress`.

Se la data `requiredAt` di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onReportAvailableUpdate(update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.getInstance().installAvailableUpdate`.
    }

    // ...
}
```

Consulta [Testare gli aggiornamenti del lettore Bluetooth](https://docs.stripe.com/terminal/references/testing.md#simulated-reader-updates) per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.


# Lettori Bluetooth

> This is a Lettori Bluetooth for when terminal-sdk-platform is react-native and reader-type is bluetooth. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=react-native&reader-type=bluetooth.

I lettori connessi tramite Bluetooth sono dispositivi Bluetooth LE. Raccolgono i dati di pagamento, ma si basano su un dispositivo mobile associato per la comunicazione con Stripe.

Per connettere l’app a un lettore Terminal tramite Bluetooth, attieniti a questa procedura:

1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers).
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader).

> Non utilizzare le impostazioni del dispositivo mobile per abbinarle al lettore. L’associazione del lettore alle impostazioni del dispositivo rende il lettore non disponibile per la connessione all’app.

## Rilevare i lettori [Lato client]

- [discoverReaders (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverReaders)

Per iniziare, accertati che il lettore sia acceso e nelle immediate vicinanze.

Quindi, dall’app, cerca i lettori connessi tramite Bluetooth nelle vicinanze con il metodo `discoverReaders`, impostando `discoveryMethod` su `bluetoothScan`.

```js
function DiscoverReadersScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
      },
    });

  useEffect(() => {
    handleDiscoverReaders();
  }, [discoverReaders]);

  const handleDiscoverReaders = async () => {
    // The list of discovered readers is reported in the `onUpdateDiscoveredReaders` method
    // within the `useStripeTerminal` hook.
    const { error } = await discoverReaders({
      discoveryMethod: 'bluetoothScan',
    });

    if (error) {
      Alert.alert(
        'Discover readers error: ',
        `${error.code}, ${error.message}`
      );
    }
  };

  return <View />;
}
```

#### Scansione Bluetooth

La scansione Bluetooth cerca tutti i lettori nelle vicinanze e restituisce all’app un elenco dei lettori individuati. Mentre è in corso la scansione, l’SDK continua a chiamare `onUpdateDiscoveredReaders` nell’hook `useStripeTerminal` con l’elenco più recente dei lettori nelle vicinanze.

Con il metodo di rilevamento tramite scansione Bluetooth, puoi impostare un timeout per eseguire la scansione per un determinato periodo di tempo. In questo modo puoi gestire la durata della batteria o attivare un messaggio di errore se non vengono trovati dispositivi.

Nell’applicazione mobile, si consiglia di visualizzare un elenco aggiornato automaticamente dei lettori rilevati con i numeri di serie per aiutare gli utenti a identificare il proprio lettore mobile. La proprietà `label` non viene compilata per i lettori mobili durante il rilevamento dei lettori. Se è necessario visualizzare nomi descrittivi per i lettori, mantenere la propria mappatura dei numeri di serie alle etichette nell’applicazione.

#### Abbinamento Bluetooth

Per migliorare la sicurezza ed essere conforme alle normative UE, dal novembre 2025 Stripe elabora il confronto numerico tramite Bluetooth dei lettori di carte WisePad 3. Il processo di confronto numerico richiede la verifica di una passkey sul lettore di carte e sul dispositivo POS durante l’associazione. Dopo aver aggiornato il dispositivo all’[ultima versione del software](https://docs.stripe.com/terminal/readers/bbpos-wisepad3.md#reader-software-releases), segui questa procedura quando colleghi il WisePad 3 a una nuova applicazione mobile. A questo punto il dispositivo POS individuo e visualizza il lettore WisePad 3:

1. Verifica che il codice a 6 cifre corrisponda sul WisePad 3 e sul dispositivo POS.
1. Seleziona **Conferma** sul WisePad 3.
1. Seleziona **Abbina** sul dispositivo POS.

> #### Nota
> 
> È sufficiente eseguire il confronto numerico quando si associa un WisePad 3 a un nuovo POS, o quando si esegue nuovamente il confronto con POS “dimenticato” esistente.

## Connettere un lettore [Lato client]

- [connectReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1)

Per connetterti a un lettore individuato, chiama il metodo `connectReader` dall’app.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tale scopo, durante la connessione, assicurati che `locationId` sia impostato sull’ID posizione pertinente.

```js
const handleConnectBluetoothReader = async (id) => {
  const { reader, error } = await connectReader({
    discoveryMethod: 'bluetoothScan',
    reader: selectedReader,
    locationId: {{LOCATION_ID}},
  });

  if (error) {
    console.log('connectReader error', error);
    return;
  }

  console.log('Reader connected successfully', reader);
};
```

> #### Utilizzare la modalità standby
> 
> Non programmare la tua app per chiamare `disconnectReader` per risparmiare energia. Il lettore gestisce in modo efficiente l’alimentazione utilizzando la modalità standby.

## Gestire le disconnessioni del lettore

- [REPORT_UNEXPECTED_READER_DISCONNECT (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#REPORT_UNEXPECTED_READER_DISCONNECT)
- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#UserCallbacks)
- [DisconnectReason (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/modules/Reader.html#DisconnectReason)

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dall’app se è fuori portata o la batteria è scarica. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

`UserCallbacks` include `onDidDisconnect` che fornisce all’applicazione il `DisconnectReason` per consentire di identificare il motivo della disconnessione del lettore.

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su `false` durante la connessione.
1. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

```js
const terminal = useStripeTerminal({
  onDidDisconnect: (result) => {
    // Consider displaying a UI to notify the user and start rediscovering readers
  },
});
```

### Riavviare il lettore connesso

- [rebootReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#rebootReader)

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API `rebootReader`. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

```js
const { error } = await rebootReader();

if (error) {
  console.log('rebootReader error:', error);
  return;
}

console.log('rebootReader succeeded');
```

#### Tentare automaticamente la riconnessione

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su true in `ConnectBluetoothReaderParams`.
1. Implementa i callback di riconnessione automatica trovati in `UserCallbacks`.
1. Quando l’SDK invia `onDidStartReaderReconnect` alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   - Puoi utilizzare `cancelReaderReconnection` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Quando l’SDK indica l’avvenuta riconnessione inviando `onDidSucceedReaderReconnect`, visualizza un messaggio che annuncia che la connessione è stata ripristinata e il lettore funziona normalmente.
1. Se l’SDK non riesce a riconnettersi al lettore e invia `onDidFailReaderReconnect`, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

#### Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come [Async Storage](https://github.com/react-native-async-storage/async-storage) (React Native).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

## Aggiorna il software del lettore [Lato client]



- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#UserCallbacks)

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

- Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
- Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

> Per installare gli aggiornamenti, il livello della batteria del lettore deve essere superiore al 50%.

### Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, l’integrazione riceve `onDidStartInstallingUpdate` dall’hook `useStripeTerminal` con un `Reader.SoftwareUpdate`.

Il `Reader.SoftwareUpdate` fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da `estimatedUpdateTime`.

Durante la procedura di installazione, lo stato `connectionStatus`di Terminal diventa `"connecting"` mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore all’hook `useStripeTerminal` con `onDidFinishInstallingUpdate`. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

- Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
- La versione dell’SDK React Native è successiva o uguale a `0.0.1-beta.18`.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

```js
const terminal = useStripeTerminal({
  onDidReportReaderSoftwareUpdateProgress: (progress) => {
    setCurrentProgress((Number(progress) * 100).toFixed(0).toString());
  },
  onDidFinishInstallingUpdate: ({ error }) => {
  },
  onDidStartInstallingUpdate: (update) => {
  },
});
```

Puoi annullare gli aggiornamenti richiesti utilizzando l’API `cancelInstallingUpdate`, che comporta anche un errore di connessione al lettore. Non puoi annullare gli aggiornamenti incrementali in corso.

### Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti notifica gli aggiornamenti facoltativi tramite il callback `onDidReportAvailableUpdate` dall’hook `useStripeTerminal` ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, l’hook `useStripeTerminal` dell’applicazione riceve il callback `onDidReportAvailableUpdate` con l’oggetto `SoftwareUpdate` contenente i dettagli dell’aggiornamento, tra cui:

- Tempo stimato per il completamento dell’aggiornamento (`estimatedUpdateTime`)
- Data a partire dalla quale l’aggiornamento diventa obbligatorio (`requiredAt`)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con `onDidReportAvailableUpdate`, chiama `installAvailableUpdate` dall’hook `useStripeTerminal`.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come `reader.availableUpdate`.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedigli di tenere il lettore a portata di mano e acceso fino al completamento dell’operazione. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. L’hook `useStripeTerminal` segnala lo stato di avanzamento dell’aggiornamento nel metodo `onDidReportReaderSoftwareUpdateProgress`.

Se la data `requiredAt` di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

```js
const terminal = useStripeTerminal({
  onDidReportAvailableUpdate: (update) => {
    // An update is available for the connected reader. Show this update in your application.
    // Install this update using the `installAvailableUpdate` method from the `useStripeTerminal` hook.
  },
});
```

Consulta [Testare gli aggiornamenti del lettore Bluetooth](https://docs.stripe.com/terminal/references/testing.md#simulated-reader-updates) per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.


# Lettori USB

> This is a Lettori USB for when terminal-sdk-platform is android and reader-type is usb. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=usb.

Utilizza SDK Android 3.0.0  (o versione successiva) di Stripe Terminal per supportare le connessioni USB per [Stripe Reader M2](https://docs.stripe.com/terminal/payments/setup-reader/stripe-m2.md) e [BBPOS WisePad 3](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepad3.md).

Devi utilizzare un cavo USB che supporti sia i dati che la ricarica, come il cavo USB 2.0 incluso in Stripe Reader M2 e BBPOS WisePad 3. Se il cavo incluso nel lettore Terminal è di sola ricarica, utilizza un cavo USB 2.0 di terze parti in grado di trasferire i dati.

Per connettere l’app a un lettore di Terminal con un cavo USB:

1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers).
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader).

## Rilevare i lettori [Lato client]

- [discoverReaders (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html)
- [UsbDiscoveryConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-usb-discovery-configuration/index.html)

Assicurati che il lettore sia acceso e connesso con un cavo USB 2.0 al dispositivo che esegue l’app e che sia stata concessa l’autorizzazione per accedere al lettore connesso tramite USB.

Se stai collegando il lettore per la prima volta, viene visualizzato un messaggio del sistema Android per connetterti al lettore. Puoi selezionare la casella di controllo “Sempre aperta” per aprire la tua app senza chiedere quando è connessa a un lettore.

Quindi, dall’app, cerca il lettore connesso con il metodo `discoverReaders`, utilizzando  `UsbDiscoveryConfiguration`.

#### Kotlin

```kotlin
class DiscoverReadersActivity : AppCompatActivity(), DiscoveryListener {
    // ...

    var discoverCancelable: Cancelable? = null

    // Action for a "Discover Readers" button
    fun discoverReadersAction() {
        val timeout = 0
        val isSimulated = false

        val config = UsbDiscoveryConfiguration(
            timeout = timeout,
            isSimulated = isSimulated
        )

        Terminal.getInstance().discoverReaders(
            config,
            this,
            object : Callback {
                override fun onSuccess() {
                    // Placeholder for handling successful operation
                }

                override fun onFailure(e: TerminalException) {
                    // Placeholder for handling exception
                }
            }
        )
    }

    override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        // In your app, display the discovered readers to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }

    // ...
}
```

## Connettere un lettore [Lato client]

- [connectReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html)
- [UsbConnectionConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-usb-connection-configuration/index.html)

Per connetterti a un lettore individuato, chiama il metodo `connectReader` dall’app.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tale scopo, durante la connessione  crea e utilizza una `UsbConnectionConfiguration` con `locationId` impostato sull’ID posizione pertinente .

#### Kotlin

```kotlin
// Implement your MobileReaderListener
val mobileReaderListener = yourMobileReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val connectionConfig = UsbConnectionConfiguration(
    ""{{LOCATION_ID}}"",
    autoReconnectOnUnexpectedDisconnect,
    mobileReaderListener
)

Terminal.getInstance().connectReader(
    selectedReader,
    connectionConfig,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

> #### Utilizzare la modalità standby
> 
> Non programmare la tua app per chiamare `disconnectReader` per risparmiare energia. Il lettore gestisce in modo efficiente l’alimentazione utilizzando la modalità standby.

## Gestire le disconnessioni del lettore

- [MobileReaderListener (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html)
- [DisconnectReason (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-disconnect-reason/index.html)

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dall’app se il cavo USB che lo collega al dispositivo è scollegato. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

Il `MobileReaderListener` include il callback `onDisconnect` che fornisce all’applicazione il `DisconnectReason` per consentire di identificare il motivo della disconnessione del lettore.

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su `false` durante la connessione.
1. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}
```

### Riavviare il lettore connesso

- [rebootReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/reboot-reader.html)

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API `rebootReader`. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

#### Kotlin

```kotlin
Terminal.getInstance().rebootReader(
    object : Callback {
        override fun onSuccess() {
            // Reboot succeeded and the reader will disconnect.
            // If your app is using automatic reconnect the reconnect will begin.
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

#### Tentare automaticamente la riconnessione

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Implementa i callback di riconnessione del lettore in `MobileReaderListener`.
1. Specifica il `MobileReaderListener` in `UsbConnectionConfiguration`.
1. Quando l’SDK invia [onReaderReconnectStarted](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-started.html) alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   - Puoi utilizzare l’oggetto `Cancelable` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Quando l’SDK indica l’avvenuta riconnessione inviando [`onReaderReconnectSucceeded`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-succeeded.html), visualizza un messaggio che annuncia che la connessione è stata ripristinata e di continuare le normali operazioni.
1. Se l’SDK non è in grado di riconnettersi al lettore e invia sia [`onReaderReconnectFailed`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-failed.html) che `onDisconnect`, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

#### Kotlin

```kotlin
class CustomMobileReaderListener : MobileReaderListener {
    // ...

    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }

    // ...
}
```

#### Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences) (Android).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

## Aggiornare il software lettore [Lato client]



- [MobileReaderListener (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html)

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

- Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
- Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

> Per installare gli aggiornamenti, il livello della batteria del lettore deve essere superiore al 50%.

### Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, il `MobileReaderListener` dell’integrazione riceve un `onStartInstallingUpdate` con un `ReaderSoftwareUpdate`.

Il `ReaderSoftwareUpdate` fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da `durationEstimate`.

Durante la procedura di installazione, lo stato `connectionStatus`di Terminal diventa `ConnectionStatus.CONNECTING` mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore a `MobileReaderListener` con `onFinishInstallingUpdate`. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

- Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
- La versione dell’SDK Android è successiva o uguale alla `3.5.0`.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onStartInstallingUpdate(update: ReaderSoftwareUpdate, cancelable: Cancelable) {
        // Show UI communicating that a required update has started installing
    }

    override fun onReportReaderSoftwareUpdateProgress(progress: Float) {
        // Update the progress of the installation
    }

    override fun onFinishInstallingUpdate(update: ReaderSoftwareUpdate?, e: TerminalException?) {
        // Report success or failure of the update
    }

    // ...
}
```

Puoi annullare gli aggiornamenti richiesti utilizzando l’oggetto `Cancelable`, il che comporta anche un errore nella connessione al lettore. Non puoi annullare gli aggiornamenti incrementali in corso.

### Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti avvisa degli aggiornamenti facoltativi tramite `MobileReaderListener` ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, il `MobileReaderListener` dell’applicazione riceve il callback `onReportAvailableUpdate` con l’oggetto `ReaderSoftwareUpdate` contenente i dettagli dell’aggiornamento, tra cui:

- Tempo stimato per il completamento dell’aggiornamento (`durationEstimate`)
- Data a partire dalla quale l’aggiornamento diventa obbligatorio (`requiredAt`)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con `onReportAvailableUpdate`, chiama `Terminal.getInstance().installAvailableUpdate`.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come `reader.availableUpdate`.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedi all’utente di mantenere connesso il lettore fino al completamento dell’aggiornamento. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. Il `MobileReaderListener` segnala lo stato di avanzamento dell’aggiornamento nel metodo `onReportReaderSoftwareUpdateProgress`.

Se la data `requiredAt` di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onReportAvailableUpdate(update: ReaderSoftwareUpdate) {
        // An update is available for the connected reader. Show this update in your application.
        // Install this update using `Terminal.getInstance().installAvailableUpdate`.
    }

    // ...
}
```

Consulta [Testare gli aggiornamenti del lettore Bluetooth](https://docs.stripe.com/terminal/references/testing.md#simulated-reader-updates) per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.


# Lettori USB

> This is a Lettori USB for when terminal-sdk-platform is react-native and reader-type is usb. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=react-native&reader-type=usb.

> #### Supporto della piattaforma
> 
> Al momento il supporto per la connessione a lettori mobili tramite l’SDK React Native è limitato alla piattaforma Android.

Utilizza  SDK React Native beta.13  (o versione successiva) di Stripe Terminal per supportare le connessioni USB per [Stripe Reader M2](https://docs.stripe.com/terminal/payments/setup-reader/stripe-m2.md) e [BBPOS WisePad 3](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepad3.md).

Devi utilizzare un cavo USB che supporti sia i dati che la ricarica, come il cavo USB 2.0 incluso in Stripe Reader M2 e BBPOS WisePad 3. Se il cavo incluso nel lettore Terminal è di sola ricarica, utilizza un cavo USB 2.0 di terze parti in grado di trasferire i dati.

Per connettere l’app a un lettore di Terminal con un cavo USB:

1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers).
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader).

## Rilevare i lettori [Lato client]

- [discoverReaders (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverreaders-1)
- [DiscoveryReaderParams (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/types/DiscoverReadersParams.html)

Assicurati che il lettore sia acceso e connesso con un cavo USB 2.0 al dispositivo che esegue l’app e che sia stata concessa l’autorizzazione per accedere al lettore connesso tramite USB.

Se stai collegando il lettore per la prima volta, viene visualizzato un messaggio del sistema Android per connetterti al lettore. Puoi selezionare la casella di controllo “Sempre aperta” per aprire la tua app senza chiedere quando è connessa a un lettore.

Quindi, dall’app, cerca il lettore connesso con il metodo `discoverReaders`, utilizzando  `usb` come `DiscoveryMethod` .

```js
function DiscoverReadersScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
      },
    });

  useEffect(() => {
    handleDiscoverReaders();
  }, []);

  const handleDiscoverReaders = async () => {
    // The list of discovered readers is reported in the `onUpdateDiscoveredReaders` method
    // within the `useStripeTerminal` hook.
    const { error } = await discoverReaders({
      discoveryMethod: 'usb',
    });

    if (error) {
      Alert.alert(
        'Discover readers error: ',
        `${error.code}, ${error.message}`
      );
    }
  };

  return <View />;
}
```

## Connettere un lettore [Lato client]

- [connectReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1)
- [ConnectUsbReaderParams (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/ConnectUsbReaderParams.html)

Per connetterti a un lettore individuato, chiama il metodo `connectReader` dall’app.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tale scopo, durante la connessione  specifica il `locationId` pertinente in `ConnectUsbReaderParams` .

```js
const handleConnectUsbReader = async (id) => {
  const { reader, error } = await connectReader({
    discoveryMethod: 'usb',
    reader: selectedReader,
    locationId: {{LOCATION_ID}},
  });

  if (error) {
    console.log('connectReader error', error);
    return;
  }

  console.log('Reader connected successfully', reader);
};
```

> #### Utilizzare la modalità standby
> 
> Non programmare la tua app per chiamare `disconnectReader` per risparmiare energia. Il lettore gestisce in modo efficiente l’alimentazione utilizzando la modalità standby.

## Gestire le disconnessioni del lettore

- [REPORT_UNEXPECTED_READER_DISCONNECT (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#REPORT_UNEXPECTED_READER_DISCONNECT)
- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#UserCallbacks)
- [DisconnectReason (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/modules/Reader.html#DisconnectReason)

A volte possono verificarsi disconnessioni del lettore tra l’app e il lettore. Ad esempio, il lettore può disconnettersi dall’app se il cavo USB che lo collega al dispositivo è scollegato. Puoi simulare una disconnessione imprevista durante il test spegnendo il lettore.

`UserCallbacks` include `onDidDisconnect` che fornisce all’applicazione il `DisconnectReason` per consentire di identificare il motivo della disconnessione del lettore.

Per gestire autonomamente la disconnessione del lettore, è possibile eseguire le operazioni seguenti:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su `false` durante la connessione.
1. Gestisci il callback di disconnessione per visualizzare un messaggio nell’app che avvisa l’utente che il lettore si è disconnesso inaspettatamente e avvia l’individuazione e la connessione del lettore.

```js
const terminal = useStripeTerminal({
  onDidDisconnect: (result) => {
    // Consider displaying a UI to notify the user and start rediscovering readers
  },
});
```

### Riavviare il lettore connesso

- [rebootReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#rebootReader)

Stripe Reader M2 e BBPOS WisePad 3 si riavviano automaticamente dopo 24 ore di funzionamento. Tuttavia, puoi forzare il riavvio del lettore e reimpostare il timer di 24 ore utilizzando l’API `rebootReader`. Dopo questa azione, il lettore si disconnette dall’SDK e poi si riavvia. Se utilizzi la riconnessione automatica, l’SDK tenta di ripristinare la connessione con il lettore.

```js
const { error } = await rebootReader();

if (error) {
  console.log('rebootReader error:', error);
  return;
}

console.log('rebootReader succeeded');
```

#### Tentare automaticamente la riconnessione

Quando un lettore si disconnette, tentiamo automaticamente la riconnessione. Ti consigliamo di mostrare delle notifiche nella tua app per comunicare lo stato del lettore durante l’intero processo.

Per visualizzare le notifiche nell’app durante la riconnessione automatica, procedi come segue:

1. Imposta `autoReconnectOnUnexpectedDisconnect` su true in `ConnectUsbReaderParams`.
1. Implementa i callback di riconnessione automatica trovati in `UserCallbacks`.
1. Quando l’SDK invia `onDidStartReaderReconnect` alla tua app, visualizza un messaggio che annuncia che il lettore ha perso la connessione ed è in corso la riconnessione.
   - Puoi utilizzare `cancelReaderReconnection` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Quando l’SDK indica l’avvenuta riconnessione inviando `onDidSucceedReaderReconnect`, visualizza un messaggio che annuncia che la connessione è stata ripristinata e il lettore funziona normalmente.
1. Se l’SDK non riesce a riconnettersi al lettore e invia `onDidFailReaderReconnect`, visualizza un messaggio che indica che si è verificata una disconnessione imprevista.

#### Riconnessione automatica all’avvio dell’applicazione

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come [Async Storage](https://github.com/react-native-async-storage/async-storage) (React Native).

1. Quando l’app viene avviata, controlla la posizione di archiviazione dei dati permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.

## Aggiornare il software lettore [Lato client]



- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#UserCallbacks)

La tua applicazione deve aggiornare i lettori mobili per applicare quanto segue:

- Configurazioni locali che ti consentono di rimanere al passo con i requisiti dei circuiti delle carte e delle società emittenti
- Aggiornamenti per la sicurezza

Gli aggiornamenti obbligatori iniziano a essere installati al momento della connessione al lettore. Non puoi utilizzare il lettore fino al completamento dell’aggiornamento.

> Per installare gli aggiornamenti, il livello della batteria del lettore deve essere superiore al 50%.

### Aggiornamenti obbligatori

Se sono disponibili aggiornamenti obbligatori per il lettore, l’integrazione riceve `onDidStartInstallingUpdate` dall’hook `useStripeTerminal` con un `Reader.SoftwareUpdate`.

Il `Reader.SoftwareUpdate` fornisce i dettagli necessari dell’aggiornamento, tra cui una stima della durata totale dell’aggiornamento, indicata da `estimatedUpdateTime`.

Durante la procedura di installazione, lo stato `connectionStatus`di Terminal diventa `"connecting"` mentre l’aggiornamento viene installato sul lettore.

L’applicazione deve informare gli utenti che è in corso l’installazione di un aggiornamento e mostrare lo stato di avanzamento nell’interfaccia utente. Fai in modo che sia chiaro il motivo per cui la connessione potrebbe richiedere più tempo del solito.

Se la procedura di aggiornamento obbligatorio non va a buon fine, Stripe comunica l’errore all’hook `useStripeTerminal` con `onDidFinishInstallingUpdate`. Non puoi riconnetterti al lettore dopo un errore di aggiornamento obbligatorio, a meno che non siano soddisfatte le seguenti condizioni:

- Il lettore esegue l’ultima versione del software in base alla posizione degli ultimi 30 giorni.
- La versione dell’SDK React Native è successiva o uguale a `0.0.1-beta.18`.

Se le condizioni sono soddisfatte, la procedura di connessione va a buon fine, nonostante l’aggiornamento non sia completo. Stripe ritenta l’aggiornamento la prossima volta che ti connetti al lettore fino a quando non viene installato correttamente.

```js
const terminal = useStripeTerminal({
  onDidReportReaderSoftwareUpdateProgress: (progress) => {
    setCurrentProgress((Number(progress) * 100).toFixed(0).toString());
  },
  onDidFinishInstallingUpdate: ({ error }) => {
  },
  onDidStartInstallingUpdate: (update) => {
  },
});
```

Puoi annullare gli aggiornamenti richiesti utilizzando l’API `cancelInstallingUpdate`, che comporta anche un errore di connessione al lettore. Non puoi annullare gli aggiornamenti incrementali in corso.

### Aggiornamenti facoltativi

Puoi rimandare gli aggiornamenti facoltativi fino alla data specificata, dopodiché diventano obbligatori. L’SDK ti notifica gli aggiornamenti facoltativi tramite il callback `onDidReportAvailableUpdate` dall’hook `useStripeTerminal` ogni volta che il lettore è connesso ma non esegue una transazione. Se è disponibile un aggiornamento facoltativo, l’hook `useStripeTerminal` dell’applicazione riceve il callback `onDidReportAvailableUpdate` con l’oggetto `SoftwareUpdate` contenente i dettagli dell’aggiornamento, tra cui:

- Tempo stimato per il completamento dell’aggiornamento (`estimatedUpdateTime`)
- Data a partire dalla quale l’aggiornamento diventa obbligatorio (`requiredAt`)

Nella tua applicazione informa gli utenti che è disponibile un aggiornamento e visualizzare un messaggio per continuare facoltativamente con l’aggiornamento.

Per procedere con l’aggiornamento precedentemente riportato con `onDidReportAvailableUpdate`, chiama `installAvailableUpdate` dall’hook `useStripeTerminal`.

L’aggiornamento disponibile viene memorizzato anche nell’oggetto reader come `reader.availableUpdate`.

Mentre è in corso l’aggiornamento, impedisci all’utente di uscire dalla pagina nell’app e chiedigli di tenere il lettore a portata di mano e acceso fino al completamento dell’operazione. Ti consigliamo inoltre di fornire all’utente un indicatore visivo dello stato di avanzamento dell’aggiornamento. L’hook `useStripeTerminal` segnala lo stato di avanzamento dell’aggiornamento nel metodo `onDidReportReaderSoftwareUpdateProgress`.

Se la data `requiredAt` di un aggiornamento facoltativo è passata, l’aggiornamento viene installato alla successiva connessione del lettore.

```js
const terminal = useStripeTerminal({
  onDidReportAvailableUpdate: (update) => {
    // An update is available for the connected reader. Show this update in your application.
    // Install this update using the `installAvailableUpdate` method from the `useStripeTerminal` hook.
  },
});
```

Consulta [Testare gli aggiornamenti del lettore Bluetooth](https://docs.stripe.com/terminal/references/testing.md#simulated-reader-updates) per ulteriori informazioni su come verificare che l’applicazione gestisca i diversi tipi di aggiornamento che un lettore può avere.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is server-driven and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=server-driven&reader-type=internet.

I lettori intelligenti eseguono il software dei lettori Stripe per comunicare direttamente con Stripe su Internet. Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account Stripe.

#### Dashboard

Puoi registrare il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore. Puoi registrare solo i lettori ordinati da te o dalla tua piattaforma.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’applicazione, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API di Stripe.

1. Vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings), poi tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nella tua applicazione.
1. La tua applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

Una volta registrato, il lettore è pronto per essere utilizzato con l’integrazione basata su server. Consigliamo di memorizzare l’ID del lettore (`tmr_xxx`) nell’applicazione in modo da sapere a quale lettore inviare le transazioni dal POS. Puoi recuperare gli ID dei lettori utilizzando l’endpoint [elenco lettori](https://docs.stripe.com/api/terminal/readers/list.md).


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is js and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=js&reader-type=internet.

> #### Raccomandazione per lettori intelligenti
> 
> Per i lettori smart, come il [lettore BBPOS WisePOS E](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md), [Stripe Reader S700/S710](https://docs.stripe.com/terminal/readers/stripe-reader-s700-s710.md) e i [lettori Verifone](https://docs.stripe.com/terminal/payments/setup-reader/verifone.md), consigliamo di utilizzare l’[integrazione basata su server](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=server-driven) anziché l’SDK JavaScript.
> 
> L’SDK JavaScript richiede che il POS e il lettore si trovino sulla stessa rete locale con un DNS locale funzionante. L’integrazione basata su server utilizza invece l’API Stripe, che può essere più semplice in ambienti di rete complessi. Consulta il nostro [confronto tra piattaforme](https://docs.stripe.com/terminal/payments/setup-reader.md#sdk) per scegliere quella più adatta alle tue esigenze.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [discoverReaders (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#discover-readers)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarli alla tua applicazione POS con `discoverReaders`, impostando `discoveryMethod` su `internet`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

```javascript
async function discoverReaders() {
  const config = {simulated: false, location: "{{LOCATION_ID}}"}
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // You should show the list of discoveredReaders to the
    // cashier here and let them select which to connect to (see below).
    connectReader(discoverResult);
  }
}
```

## Connettere un lettore [Lato client]

> Chrome 142 (rilasciato il 28 ottobre 2025) e le versioni successive richiedono un’autorizzazione esplicita prima che i siti web possano accedere ai dispositivi di rete locali (come i lettori Terminal) quando si utilizza l’SDK JavaScript di Stripe Terminal. Per le procedure di configurazione e la risoluzione dei problemi, consulta le [istruzioni per Chrome 142+](https://support.stripe.com/questions/ensuring-stripe-terminal-javascript-sdk-functionality-on-chrome-142).

Per collegare l’applicazione POS a un lettore, chiama [connectReader](https://docs.stripe.com/terminal/references/api/js-sdk.md#connect-reader) con il lettore selezionato.

```javascript
async function connectReader(discoverResult) {
  // Just select the first reader here.
  const selectedReader = discoverResult.discoveredReaders[0];

  const connectResult = await terminal.connectReader(selectedReader);
  if (connectResult.error) {
    console.log('Failed to connect:', connectResult.error);
  } else {
    console.log('Connected to reader:', connectResult.reader.label);
  }
}
```

- [connectReader (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#connect-reader)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `connectReader` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `connectReader`accetta un oggetto di configurazione con una proprietà `fail_if_in_use`, il cui valore predefinito è `false`. Quando l’applicazione imposta `fail_if_in_use` su true, la chiamata `connectReader` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `collectPaymentMethod` o `processPayment` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `collectPaymentMethod`), l’impostazione `fail_if_in_use` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione esistente da SDK a lettore.

```javascript
const connectResult = await terminal.connectReader(reader, {fail_if_in_use: true});
```

|                                                                                              | fail_if_in_use è impostato su false (impostazione predefinita)                                                                                                                                                              | fail_if_in_use è impostato su true                                                                                                                                                                                          |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                 |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `fail_if_in_use` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `fail_if_in_use` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [StripeTerminal.create (JavaScript)](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-create)

La tua app deve implementare il callback `onUnexpectedReaderDisconnect` per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare `discoverReaders` per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

```javascript
const terminal = StripeTerminal.create({
  onFetchConnectionToken: fetchConnectionToken,
  onUnexpectedReaderDisconnect: unexpectedDisconnect,
});

function unexpectedDisconnect() {
  // Consider displaying a UI to notify the user and start rediscovering readers
}
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
1. Quando l’app viene avviata, controlla l’archiviazione permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is ios and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=internet.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [discoverReaders (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:)
- [InternetDiscoveryConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPInternetDiscoveryConfiguration.html)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarli alla tua applicazione POS con `discoverReaders`, utilizzando `InternetDiscoveryConfiguration`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

#### Swift

```swift
import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {
  func discoverReadersAction() throws {
      let config = try InternetDiscoveryConfigurationBuilder()
                          .setLocationId(""{{LOCATION_ID}}"")
                          .build()
      // In addition to Terminal's completion block methods, Swift async alternatives are available.
      // See our Example app for usage examples: https://github.com/stripe/stripe-terminal-ios/tree/master/Example
      self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
          if let error = error {
              print("discoverReaders failed: \(error)")
          } else {
              print("discoverReaders succeeded")
          }
      }
  }
}
```

Per l’individuazione dei lettori intelligenti, il metodo `DiscoveryDelegate.didUpdateDiscoveredReaders` viene chiamato solo una volta per chiamata a `discoverReaders`. `didUpdateDiscoveredReaders` restituisce un elenco vuoto di lettori se non sono presenti lettori registrati o lettori associati alla posizione specificata. Se effettui una successiva chiamata `discoverReaders` per aggiornare l’elenco, devi prima annullare la chiamata precedente con la chiamata `Cancelable` restituita da `discoverReaders`.

`InternetDiscoveryConfiguration` supporta un valore `timeout` facoltativo per l’individuazione dei lettori online. In questo modo sarà possibile accedere più rapidamente all’individuazione offline dei lettori nel caso in cui il tentativo online non vada a buon fine.

## Connettere un lettore [Lato client]

> Nella versione `5.1.0` dell’SDK iOS, è possibile utilizzare il metodo `easyConnect` per unificare il rilevamento del lettore e la connessione in un’unica chiamata API, semplificando così l’integrazione. Per ulteriori dettagli, consulta la [guida alla migrazione dell’SDK](https://docs.stripe.com/terminal/references/sdk-migration-guide.md#update-your-reader-connection-usage-ios).

Per collegare l’applicazione POS a un lettore, chiama `connectReader` con il lettore selezionato, utilizzando `InternetConnectionConfiguration`.

#### Swift

```swift
let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: yourInternetReaderDelegate)
        .build()
} catch {
    // Handle error building the connection configuration
    return
}

Terminal.shared.connectReader(selectedReader, connectionConfig: config) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}
```

- [connectReader (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:connectionConfig:completion:)
- [InternetConnectionConfiguration](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPInternetConnectionConfiguration.html)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `connectReader` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `connectReader` accetta un oggetto di configurazione con una proprietà `failIfInUse`, il cui valore predefinito è `false`. Quando l’applicazione imposta `failIfInUse` su true, la chiamata `connectReader` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `collectPaymentMethod` o `confirmPaymentIntent` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `collectPaymentMethod`), l’impostazione `failIfInUse` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione SDK-lettore esistente.

#### Swift

```swift
let internetReaderDelegate = yourInternetReaderDelegate // implement your internetReaderDelegate

let config: InternetConnectionConfiguration
do {
    config = try InternetConnectionConfigurationBuilder(delegate: internetReaderDelegate)
          .setFailIfInUse(true)
          .build()
} catch {
    // Handle error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: config, completion: { reader, error in
    // ...
})
```

|                                                                                              | failIfInUse è impostato su false (impostazione predefinita)                                                                                                                                                                  | failIfInUse è impostato su true                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `didDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `didDisconnect` dell’app. |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `didDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                  |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `failIfInUse` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `failIfInUse` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [didDisconnect (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)reader:didDisconnect:)

La tua app deve implementare il callback `reader(_, didDisconnect:)` per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare `discoverReaders` per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

#### Swift

```swift
import StripeTerminal

class ReaderViewController: UIViewController, InternetReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti correttamente a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati persistente, ad esempio [UserDefaults API](https://developer.apple.com/documentation/foundation/userdefaults) (iOS)
1. Quando l’app viene avviata, controlla l’archiviazione permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is android and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=internet.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [discoverReaders (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html)
- [InternetDiscoveryConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-internet-discovery-configuration/index.html)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarli alla tua applicazione POS con `discoverReaders`, utilizzando `InternetDiscoveryConfiguration`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

#### Kotlin

```kotlin
var discoveryCancelable: Cancelable? = null

fun onDiscoverReaders() {
    val timeout = 0
    val isSimulated = false

    val config = InternetDiscoveryConfiguration(
        timeout = timeout,
        isSimulated = isSimulated,
        location = ""{{LOCATION_ID}}""
    )

    // Save this cancelable to an instance variable
    discoveryCancelable = Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Display the discovered readers to the user
            }
        },
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

override fun onStop() {
    super.onStop()

    // If you're leaving the activity or fragment without selecting a reader,
    // make sure you cancel the discovery process or the SDK will be stuck in
    // a discover readers phase.
    discoveryCancelable?.cancel(
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}
```

## Connettere un lettore [Lato client]

> Nella versione `5.0.0` dell’SDK Android, è possibile utilizzare il metodo `easyConnect` per combinare il rilevamento del lettore e la connessione in un’unica chiamata API per un’esperienza di integrazione più semplice. Per ulteriori dettagli, consultare la [guida alla migrazione dell’SDK](https://docs.stripe.com/terminal/references/sdk-migration-guide.md#update-your-reader-connection-usage).

Per collegare l’applicazione POS a un lettore, chiama `connectReader` con il lettore selezionato, utilizzando `InternetConnectionConfiguration`.

#### Kotlin

```kotlin
val internetReaderListener = yourInternetReaderListener

val config = InternetConnectionConfiguration(internetReaderListener)
Terminal.getInstance().connectReader(
    firstReader,
    config,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

- [connectReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html)
- [InternetConnectionConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-internet-connection-configuration/index.html)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `connectReader` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `connectReader` accetta un oggetto di configurazione con una proprietà `failIfInUse`, il cui valore predefinito è `false`. Quando l’applicazione imposta `failIfInUse` su true, la chiamata `connectReader` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `collectPaymentMethod` o `confirmPaymentIntent` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `collectPaymentMethod`), l’impostazione `failIfInUse` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione SDK-lettore esistente.

#### Kotlin

```kotlin
val failIfInUse = true
val internetReaderListener = yourInternetReaderListener

val config = InternetConnectionConfiguration(internetReaderListener, failIfInUse)
Terminal.getInstance().connectReader(
    reader,
    config,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)
```

|                                                                                              | failIfInUse è impostato su false (impostazione predefinita)                                                                                                                                                                 | failIfInUse è impostato su true                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                 |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `failIfInUse` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `failIfInUse` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [onDisconnect (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-disconnect-listener/on-disconnect.html)

La tua app deve implementare il callback `onDisconnect` per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare `discoverReaders` per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), InternetReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences) (Android).
1. Quando l’app viene avviata, controlla l’archiviazione permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is react-native and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=react-native&reader-type=internet.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [discoverReaders (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverReaders)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarli alla tua applicazione POS con `discoverReaders`, impostando `discoveryMethod` su `internet`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

```js
export default function DiscoverScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
      },
    });

  useEffect(() => {
    const fetchReaders = async () => {
      const { error } = await discoverReaders({
        discoveryMethod: 'internet',
      });
    }

    fetchReaders();
  }, [discoverReaders]);

  return <View />;
}
```

## Connettere un lettore [Lato client]

> Nella versione `0.0.1-beta.29` dell’SDK React Native, è possibile utilizzare il metodo [easyConnect](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#easyconnect) per unificare il rilevamento del lettore e la connessione in un’unica chiamata API in modo da ottenere un’esperienza di integrazione più semplice.

Per collegare l’applicazione POS a un lettore, chiama `connectReader` con il lettore selezionato.

```js
const { reader, error } = await connectReader({
  discoveryMethod: 'internet',
  reader,
});

if (error) {
  console.log('connectReader error:', error);
  return;
}

console.log('Reader connected successfully', reader);
```

- [connectReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `connectReader` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `connectReader` accetta un oggetto di configurazione con una proprietà `failIfInUse`, il cui valore predefinito è `false`. Quando l’applicazione imposta `failIfInUse` su true, la chiamata `connectReader` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `collectPaymentMethod` o `confirmPaymentIntent` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `collectPaymentMethod`), l’impostazione `failIfInUse` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione SDK-lettore esistente.

```js
const { reader: connectedReader, error } = await connectReader({
  discoveryMethod: 'internet',
  reader,
  failIfInUse: true,
});
```

|                                                                                                      | failIfInUse è impostato su false (impostazione predefinita)                                                                                                                                                                    | failIfInUse è impostato su true                                                                                                                                                                                                |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `connectInternetReader` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDidDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDidDisconnect` dell’app. |
| `connectInternetReader` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDidDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                    |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `failIfInUse` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `failIfInUse` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#UserCallbacks)

L’app deve implementare il callback `onDidDisconnect` per gestire la disconnessione del lettore si disconnette. Quando implementi questo callback, visualizza un’interfaccia utente che notifica all’utente la disconnessione dal lettore. Puoi chiamare `discoverReaders` per cercare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

```js
const terminal = useStripeTerminal({
  onDidDisconnect: (result) => {
    // Consider displaying a UI to notify the user and start rediscovering readers
  },
});
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is java and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=java&reader-type=internet.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [discoverReaders (Java)](https://stripe.dev/stripe-terminal-java/core/com.stripe.stripeterminal/-terminal/discover-readers.html)
- [InternetDiscoveryConfiguration (Java)](https://stripe.dev/stripe-terminal-java/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-internet-discovery-configuration/index.html)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarli alla tua applicazione POS con `discoverReaders`, utilizzando `InternetDiscoveryConfiguration`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

```java
private Cancelable discoveryCancelable;

public void onDiscoverReaders() {
    int timeout = 0;
    boolean isSimulated = false;

    InternetDiscoveryConfiguration config = new InternetDiscoveryConfiguration(
        timeout,
        ""{{LOCATION_ID}}"",
        isSimulated,
        DiscoveryFilter.None.INSTANCE
    );

    // Save this cancelable to an instance variable
    discoveryCancelable = Terminal.getInstance().discoverReaders(
        config,
        readers -> {
            // Display the discovered readers to the user
        },
        new Callback() {
            @Override
            public void onSuccess() {
                // Placeholder for handling successful operation
            }

            @Override
            public void onFailure(@NotNull TerminalException e) {
                // Placeholder for handling exception
            }
        }
    );
}
```

## Connettere un lettore [Lato client]

> Nella versione `1.0.0-b15` dell’SDK Java, è possibile utilizzare il metodo [easyConnect](https://stripe.dev/stripe-terminal-java/core/com.stripe.stripeterminal/-terminal/easy-connect.html) per unificare il rilevamento del lettore e la connessione in un’unica chiamata API, consentendo un’integrazione più semplice.

Per collegare l’applicazione POS a un lettore, chiama `connectReader` con il lettore selezionato, utilizzando `InternetConnectionConfiguration`.

```java
InternetReaderListener internetReaderListener = yourInternetReaderListener;

InternetConnectionConfiguration config = new InternetConnectionConfiguration(internetReaderListener);

Terminal.getInstance().connectReader(
    reader,
    config,
    new ReaderCallback() {
        @Override
        public void onSuccess(@NotNull Reader reader) {
            // Placeholder for handling successful operation
        }

        @Override
        public void onFailure(@NotNull TerminalException e) {
            // Placeholder for handling exception
        }
    }
);
```

- [connectReader (Java)](https://stripe.dev/stripe-terminal-java/core/com.stripe.stripeterminal/-terminal/connect-reader.html)
- [InternetConnectionConfiguration (Java)](https://stripe.dev/stripe-terminal-java/external/com.stripe.stripeterminal.external.models/-connection-configuration/-internet-connection-configuration/index.html)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `connectReader` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `connectReader` accetta un oggetto di configurazione con una proprietà `failIfInUse`, il cui valore predefinito è `false`. Quando l’applicazione imposta `failIfInUse` su true, la chiamata `connectReader` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `collectPaymentMethod` o `confirmPaymentIntent` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `collectPaymentMethod`), l’impostazione `failIfInUse` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione SDK-lettore esistente.

```java
boolean failIfInUse = true;
InternetReaderListener internetReaderListener = yourInternetReaderListener;

InternetConnectionConfiguration config =
    new InternetConnectionConfiguration(internetReaderListener, failIfInUse);

Terminal.getInstance().connectReader(
    reader,
    config,
    new ReaderCallback() {
        @Override
        public void onSuccess(@NotNull Reader reader) {
            // Placeholder for handling successful operation
        }

        @Override
        public void onFailure(@NotNull TerminalException e) {
            // Placeholder for handling exception
        }
    }
);
```

|                                                                                              | failIfInUse è impostato su false (impostazione predefinita)                                                                                                                                                                 | failIfInUse è impostato su true                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. |
| `connectReader` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `onDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                 |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `failIfInUse` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `failIfInUse` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [onDisconnect (Java)](https://stripe.dev/stripe-terminal-java/external/com.stripe.stripeterminal.external.callable/-reader-disconnect-listener/on-disconnect.html)

La tua app deve implementare il callback `onDisconnect` per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare `discoverReaders` per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

```java
public class CustomReaderListener implements InternetReaderListener {
    // ...

    @Override
    public void onDisconnect(@NotNull DisconnectReason reason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

1. Quando ti connetti a un lettore, salva il suo numero di serie in una posizione di archiviazione dei dati permanente, come l’[API Preferences](https://docs.oracle.com/javase/8/docs/api/java/util/prefs/Preferences.html).
1. Quando l’app viene avviata, controlla l’archiviazione permanente per trovare un numero di serie salvato. Se ne viene trovato uno, chiama il metodo `discoverReaders` in modo che la tua applicazione possa provare a trovare di nuovo quel lettore.
1. Se il numero di serie salvato corrisponde a uno dei lettori trovati, prova a connetterti a quel lettore con l’oggetto reader corrispondente restituito dalla chiamata a `discoverReaders`. Se il lettore a cui ti sei connesso in precedenza non viene trovato, arresta il processo di individuazione.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Lettori Internet

> This is a Lettori Internet for when terminal-sdk-platform is dotnet and reader-type is internet. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=dotnet&reader-type=internet.

I lettori intelligenti eseguono il software del lettore Stripe per comunicare direttamente con Stripe su Internet. Per connettere la tua app a un lettore intelligente, procedi nel seguente modo:

1. [Registra un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#register-reader) al tuo account Stripe.
1. [Scopri i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) con l’SDK.
1. [Connettiti al lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) con l’SDK.

## Registrare un lettore [Lato server]

Prima di poter connettere l’applicazione a un lettore intelligente, devi registrare il lettore sul tuo account.

#### Dashboard

### Registrarsi nella Dashboard

Puoi aggiungere il tuo lettore direttamente nella [Dashboard](https://dashboard.stripe.com/test/terminal).

#### Registra per codice di registrazione

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. Inserisci il codice di registrazione e fai clic su **Avanti**.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per numero di serie

1. Nella pagina [Lettori](https://dashboard.stripe.com/terminal/readers), fai clic su **Registra lettore**.
1. Trova il numero di serie sul dispositivo e inseriscilo. Per registrare più dispositivi contemporaneamente, puoi inserire più numeri di serie separati da virgole.
1. Facoltativamente, scegli un nome per il lettore.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione del lettore.

#### Registra per ordine hardware

1. Nella pagina [Ordini hardware](https://dashboard.stripe.com/terminal/hardware_orders), trova un ordine con lo stato “spedito” o “consegnato”. Fai clic sul menu extra (⋯) alla fine della riga, poi fai clic su **Registra**.
1. Nella pagina **Registra lettori**, seleziona uno o più lettori dall’ordine hardware da registrare, poi fai clic su **Registra**.
1. Facoltativamente, scegli un nome per il lettore. Se hai selezionato più lettori, il nome serve da prefisso e i lettori vengono nominati in sequenza. Ad esempio, se inserisci “Lettore di prova”, i lettori vengono chiamati “Lettore di prova 1”, “Lettore di prova 2” e così via.
1. Se hai già creato una posizione, seleziona la nuova posizione del lettore. Altrimenti, crea una posizione facendo clic su **+ Aggiungi nuovo**.
1. Fai clic su **Registra** per completare la registrazione dei lettori.

#### API

Per distribuzioni di grandi dimensioni, consenti agli utenti sul campo di ricevere e configurare nuovi lettori autonomamente. Nell’app, crea un flusso per [registrare](https://docs.stripe.com/api/terminal/readers/create.md) un lettore con l’API Stripe.

1. Se disponi di un [lettore intelligente](https://docs.stripe.com/terminal/smart-readers.md), inserisci la sequenza di tasti `0-7-1-3-9` per visualizzare un codice di registrazione univoco. Se disponi di un BBPOS WisePOS E o Stripe Reader S700/S710, vai alle [impostazioni del lettore](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md#settings) e tocca **Genera codice di accoppiamento**.
1. L’utente inserisce il codice nell’applicazione.
1. L’applicazione invia il codice a Stripe:

```curl
curl https://api.stripe.com/v1/terminal/readers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode "label=Alice's reader" \
  -d "location={{TERMINALLOCATION_ID}}"
```

Per confermare che hai registrato correttamente un lettore, elenca tutti i lettori registrati in quella posizione:

#### curl

```bash
curl https://api.stripe.com/v1/terminal/readers \
  -u <<YOUR_SECRET_KEY>>:
```

## Rilevare i lettori [Lato client]

- [DiscoverReadersAsync (.NET)](https://docs.stripe.com/terminal/payments/connect-reader.md#TODO-DOTNET-FIXME)

Dopo aver registrato il lettore sul tuo account, cerca i lettori registrati in precedenza per collegarti alla tua applicazione POS utilizzando il metodo `DiscoverReadersAsync`.

Puoi definire l’ambito della tua scoperta utilizzando la `location` in cui hai registrato il lettore nel passaggio precedente.

```csharp
public async Task<IImmutableList<Reader>> DiscoverReadersAsync()
{

    try
    {
        var config = new DiscoveryConfiguration.Builder()
          .SetIsSimulated(false)
          .SetLocation("{{LOCATION_ID}}")
          .Build();

        Console.WriteLine("Discovered readers");
        return await Terminal.Instance.DiscoverReadersAsync(config);
    }
    catch (TerminalException ex)
    {
        // Placeholder for handling exception
        throw;
    }

}
```

## Connettere un lettore [Lato client]

Per collegare l’applicazione POS a un lettore, chiama `ConnectInternetReaderAsync` con il lettore selezionato.

```csharp
// after selecting a reader to connect to
Reader connectedReader;
try
{
    var config = new InternetConnectionConfiguration.Builder()
        .Build();
    connectedReader = await Terminal.Instance.ConnectInternetReaderAsync(selectedReader, config);
    Console.WriteLine("Connected to reader");
}
catch (TerminalException ex)
{
    // Placeholder for handling exception
    throw;
}
```

- [ConnectInternetReaderAsync (.NET)](https://docs.stripe.com/terminal/payments/connect-reader.md#TODO-DOTNET-FIXME)

### Più connessioni

Solo un’istanza dell’SDK di Stripe Terminal può connettersi a un lettore in un determinato momento. Per impostazione predefinita, quando chiami `ConnectInternetReaderAsync` da un’altra applicazione, la connessione in entrata sostituisce la connessione esistente da SDK a lettore e l’SDK precedentemente connesso si disconnette dal lettore. Il metodo `ConnectInternetReaderAsync` accetta un oggetto di configurazione con una proprietà `failIfInUse`, il cui valore predefinito è '`false`. Quando l’applicazione imposta `failIfInUse` su `true`, la chiamata `ConnectInternetReaderAsync` ha un comportamento alternativo in cui la connessione in entrata non riesce se il lettore si trova nel bel mezzo di una chiamata `CollectPaymentMethodAsync` o `ConfirmPaymentIntentAsymc` avviata da un altro SDK. Se il lettore è connesso a un altro SDK ma è inattivo (visualizzando la schermata iniziale prima che venga chiamato `CollectPaymentMethodAsync`), l’impostazione `failIfInUse` non modifica il comportamento della connessione e la richiesta di connessione in entrata può sempre interrompere la connessione esistente da SDK a lettore.

```csharp
// after selecting a reader to connect to
Reader connectedReader;
try
{
    var config = new InternetConnectionConfiguration.Builder()
        .SetFailIfInUse(true)
        .Build();
    connectedReader = await Terminal.Instance.ConnectInternetReaderAsync(selectedReader, config);
    Console.WriteLine("Connected to reader");
}
catch (TerminalException ex)
{
    // Placeholder for handling exception
    throw;
}
```

|                                                                                                           | FailIfInUse è impostato su false (impostazione predefinita)                                                                                                                                                                                 | FailIfInUse è impostato su true                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConnectInternetReaderAsync` viene chiamato da un nuovo SDK quando il lettore è inattivo.                 | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `OnUnexpectedReaderDisconnect` dell’app. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `OnUnexpectedReaderDisconnect` dell’app. |
| `ConnectInternetReaderAsync` viene chiamato da un nuovo SDK quando il lettore è a metà della transazione. | La connessione esistente tra SDK e lettore si interrompe e il nuovo SDK si connette al lettore. Il comando successivo dall’SDK precedentemente connesso fallisce con un errore del lettore e l’app `OnUnexpectedReaderDisconnect` dell’app. | La connessione in entrata non riesce con un errore del lettore. La connessione esistente da SDK e lettore non si interrompe e il comando in corso continua.                                                                                 |

Per l’esperienza di connessione meno problematica in ambienti con più lettori, consigliamo di impostare `failIfInUse` su `true` nel tentativo di connessione iniziale dell’applicazione. Poi consenti agli utenti di ritentare la connessione con `failIfInUse` impostato su `false` se la connessione non riesce la prima volta.

Con questa impostazione, uno degli utenti non può interrompere accidentalmente una transazione connettendosi inavvertitamente a un lettore in uso, ma può comunque connettersi se necessario.

### Gestire le disconnessioni

- [TerminalListener (.NET)](https://docs.stripe.com/terminal/payments/connect-reader.md#TODO-DOTNET-FIXME)

La tua app deve implementare il callback `OnUnexpectedReaderDisconnect` per gestire la disconnessione di un lettore. Quando implementi questo callback, visualizzi un’interfaccia utente che notifica all’utente che il lettore si è disconnesso. Puoi chiamare `DiscoverReadersAsync` per scansionare i lettori e avviare la riconnessione.

L’app può tentare di riconnettersi automaticamente al lettore disconnesso oppure visualizzare un’interfaccia utente che chiede all’utente di riconnettersi a un altro lettore.

Il lettore può disconnettersi dalla tua app se perde la connessione al circuito. Per simulare una disconnessione imprevista, spegni il lettore.

```csharp
public class TerminalListener : ITerminalListener
{

    // ...

    Terminal.InitTerminal(
        connectionTokenProvider: connectionTokenProvider,
        terminalListener: this,
        offlineListener: offlineListener,
        applicationInformation: applicationInformation
    );

    // ITerminalListener
    public void OnUnexpectedReaderDisconnect(Reader reader)
    {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

}
```

### Riconnessione automatica

Stripe Terminal non si riconnette automaticamente a un lettore all’avvio dell’applicazione. Puoi invece creare un flusso di riconnessione memorizzando gli ID dei lettori e tentando di connetterti a un lettore noto all’avvio.

Durante la procedura di individuazione e connessione visualizza un messaggio dell’interfaccia utente che indica che è in corso una riconnessione automatica.


# Tap to Pay su iPhone

> This is a Tap to Pay su iPhone for when terminal-sdk-platform is ios and reader-type is tap-to-pay. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=tap-to-pay.

Tap to Pay su iPhone consente agli utenti di accettare pagamenti contactless di persona con un [iPhone compatibile](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=ios#supported-devices) e l’[SDK di Stripe Terminal](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=ios). Tap to Pay su iPhone supporta carte contactless Visa, Mastercard e American Express e wallet mobile basati su NFC (Apple Pay, Google Pay e Samsung Pay). Tap to Pay su iPhone è incluso nell’SDK Terminal iOS e consente di effettuare pagamenti direttamente nell’app mobile iOS.

## Rilevare i lettori

- [discoverReaders (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:)
- [TapToPayDiscoveryConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Reader%20Discovery%20%26%20Connection.html#/c:objc\(cs\)SCPTapToPayDiscoveryConfiguration)

Utilizza il metodo [discoverReaders](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)discoverReaders:delegate:completion:) per determinare se il tuo iPhone supporta Tap to Pay.

Il gestore `completion` gestore viene richiamato con un errore se l’applicazione viene eseguita su un dispositivo che non soddisfa i [criteri del dispositivo supportato](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=ios#supported-devices).

#### Swift

```swift
import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try TapToPayDiscoveryConfigurationBuilder().build()
        // In addition to Terminal's completion block methods, Swift async alternatives are available.
        // See our Example app for usage examples: https://github.com/stripe/stripe-terminal-ios/tree/master/Example
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the ability to use your phone as a reader
        // Call `connectReader` to initiate a session with the phone
    }
}
```

## Connettere un lettore

> Nella versione `5.1.0` dell’SDK iOS, è possibile utilizzare il metodo `easyConnect` per unificare il rilevamento del lettore e la connessione in un’unica chiamata API, semplificando così l’integrazione. Per ulteriori dettagli, consulta la [guida alla migrazione dell’SDK](https://docs.stripe.com/terminal/references/sdk-migration-guide.md#update-your-reader-connection-usage-ios).

- [connectReader (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc\(cs\)SCPTerminal\(im\)connectReader:connectionConfig:completion:)
- [TapToPayConnectionConfiguration (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTapToPayConnectionConfiguration.html)

Per iniziare ad accettare i pagamenti Tap to Pay su iPhone, fornisci il lettore individuato al metodo di chiamata `connectReader`. Dovrai anche [creare un delegato](https://docs.stripe.com/terminal/payments/connect-reader.md#device-setup) per gestire i potenziali aggiornamenti richiesti al lettore.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tale scopo, durante la connessione, crea e utilizza una `SCPTapToPayConnectionConfiguration` con `locationId` impostato sull’ID posizione pertinente.

Imposta `display_name` per mostrare il nome dell’attività durante la creazione di una posizione. Il cliente vede il parametro `display_name` sullo schermo del dispositivo, a meno che tu non fornisca esplicitamente il nome di un’attività quando ti connetti a un lettore. Puoi modificare le posizioni esistenti in base alle tue esigenze per adattare questo testo

Se utilizzi gli [addebiti indiretti con on_behalf_of](https://docs.stripe.com/terminal/features/connect.md#destination-payment-intents), devi fornire anche l’ID dell’account connesso in `SCPTapToPayConnectionConfiguration`.

#### Swift

```swift
// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig = try TapToPayConnectionConfigurationBuilder.init(locationId: ""{{LOCATION_ID}}"")
.delegate(yourTapToPayReaderDelegate)
.build()
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}
```

### Gestire la configurazione del dispositivo

Quando ti connetti a un lettore Tap to Pay su iPhone compatibile, potrebbe essere necessario eseguire un aggiornamento della configurazione che potrebbe richiedere fino a qualche minuto. Ti consigliamo di connetterti al lettore in anticipo in background per ridurre i tempi di attesa per le attività.

Assicurati che l’applicazione implementi `SCPTapToPayReaderDelegate` per gestire i passaggi della configurazione e mostrare messaggi di attesa per la tua attività. I passaggi della configurazione verranno visualizzati come un aggiornamento del software in modo da poter mostrare i progressi alle attività, se necessario.

#### Swift

```swift
class APPReaderViewController: TapToPayReaderDelegate {

    // MARK: TapToPayReaderDelegate

    // ...

    func tapToPayReader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // In your app, let the user know that an update is being installed on the reader
    }

    func tapToPayReader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // The update or configuration process has reached the specified progress (0.0 to 1.0)
        // If you are displaying a progress bar or percentage, this can be updated here
    }

    func tapToPayReader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // The reader has finished installing an update
        // If `error` is nil, it is safe to proceed and start collecting payments
        // Otherwise, check the value of `error` for more information on what went wrong
    }

    func tapToPayReader(_ reader: Reader, didRequestReaderDisplayMesage displayMessage: ReaderDisplayMessage) {
        // This is called to request that a prompt be displayed in your app.
        // Use Terminal.stringFromReaderDisplayMessage(:) to get a user-facing string for the prompt
    }

    func tapToPayReader(_ reader: Reader, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
        // This is called when the reader begins waiting for input
        // Use Terminal.stringFromReaderInputOptions(:) to get a user-facing string for the input options
    }

    // ...
}
```

### Collegamento di account e termini e condizioni Apple

Tutti gli utenti devono accettare i Termini e le condizioni di Tap to Pay su iPhone di Apple prima di accettare il pagamento per la prima volta. Per gli utenti collegati, ogni account connesso deve accettare individualmente i Termini e le condizioni quando:

- Un utente Connect crea addebiti diretti
- Un utente Connect crea un addebito indiretto e specifica un account `on_behalf_of`

Gli utenti possono accettare i Termini e le condizioni di Tap to Pay su iPhone di Apple sul web prima di connettersi al lettore per la prima volta utilizzando i [link di onboarding](https://docs.stripe.com/api/terminal/onboarding-link.md?api-version=2025-07-30.preview). In alternativa, agli utenti verranno presentati i Termini e le condizioni di Tap to Pay su iPhone di Apple la prima volta che si connettono al lettore all’interno di un’applicazione mobile. Per accettare i Termini e le condizioni di Apple, l’utente deve fornire un ID Apple valido che rappresenti l’attività. Dopo che gli utenti hanno accettato i Termini e le condizioni di Tap to Pay su iPhone di Apple, non verrà più richiesto loro di farlo nelle connessioni successive utilizzando lo stesso account Stripe, anche su altri dispositivi mobili.
![Processo in tre fasi che mostra l'accesso con l'ID Apple, l'accettazione dei termini e la conferma dell'avvenuta registrazione per Tap to Pay su iPhone.](https://b.stripecdn.com/docs-statics-srv/assets/ttpoi-account-linking-steps.56bc5c0bb037a98f788a7e8d43d0c87e.png)

Collega il tuo account Apple ID per accettare pagamenti Tap to Pay

Se chiami `connectReader` per Tap to Pay su iPhone, tutti gli iPhone possono utilizzare fino a tre account Stripe univoci sulle app per 24 ore. Se utilizzi altri account per il dispositivo nello stesso periodo di 24 ore, il metodo di chiamata `connectReader` genera un errore [SCPErrorTapToPayReaderMerchantBlocked](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPError.html#/c:@E@SCPError@SCPErrorTapToPayReaderMerchantBlocked).

Ulteriori informazioni sul collegamento dell’account nella sezione Tap to Pay su iPhone - Informazioni sull’attività nelle [Domande Frequenti su Tap to Pay su iPhone](https://register.apple.com/tap-to-pay-on-iphone/faq.html).

## Gestire le disconnessioni

Il lettore si disconnette quando l’applicazione entra in background o quando l’iPhone perde la connettività. Sono disponibili due modi per gestire questa disconnessione:

- [TapToPayReaderDelegate (iOS)](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPTapToPayReaderDelegate.html)

#### Gestire manualmente la disconnessione

Per gestire questa disconnessione, l’applicazione deve implementare il metodo delegato [SCPTapToPayReaderDelegate reader:didDisconnect:](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPReaderDelegate.html#/c:objc\(pl\)SCPReaderDelegate\(im\)reader:didDisconnect:). Puoi utilizzare questo callback come un’opportunità per notificare all’utente che qualcosa non ha funzionato e che è necessaria la connettività a Internet per continuare. Inoltre, puoi ristabilire la connessione al lettore manualmente quando l’applicazione torna in primo piano.

#### Swift

```swift
import StripeTerminal

class ReaderViewController: UIViewController, TapToPayReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}
```

#### Tentare automaticamente la riconnessione

Implementa i metodi automatici per ristabilire la connessione in `SCPTapToPayReaderDelegate`. Devi quindi trasmettere `SCPTapToPayReaderDelegate` a `SCPTapToPayConnectionConfiguration`.

#### Swift

```swift
let connectionConfig = try TapToPayConnectionConfigurationBuilder(locationId: locationId)
  .delegate(yourTapToPayReaderDelegate)
  .build()

Terminal.shared.connectReader(
  reader,
  connectionConfig: connectionConfig,
  completion: connectCompletion
)
```

Se tenti di eseguire automaticamente la riconnessione, si verifica quanto segue:

1. Quando si verifica una disconnessione, l’SDK tenta automaticamente di riconnettersi e invia una notifica tramite `onReaderReconnectStarted`. Assicurati che l’app annunci che la connessione è stata persa e che è in corso una riconnessione.
   - Puoi utilizzare l’oggetto `Cancelable` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Se l’SDK si riconnette al lettore, Stripe ti invia una notifica tramite `onReaderReconnectSucceeded`. Assicurati che la tua app annunci che la connessione è stata ripristinata e che funzioni normalmente.
1. Se l’SDK non è in grado di riconnettersi al lettore, Stripe ti invia una notifica tramite `onReaderReconnectFailed` e `reader:didDisconnect:`. Assicurati che la tua app annunci che si è verificata una disconnessione imprevista.

#### Swift

```swift
import StripeTerminal

extension ReaderViewController: TapToPayReaderDelegate {
    // MARK: ReconnectionDelegate

    func reader(_ reader: Reader, didStartReaderReconnect cancelable: Cancelable) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReaderReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReaderReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}
```


# Tap to Pay su Android

> This is a Tap to Pay su Android for when terminal-sdk-platform is android and reader-type is tap-to-pay. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=tap-to-pay.

Tap to Pay su Android (TTPA) consente agli utenti di accettare pagamenti contactless di persona con [dispositivi Android compatibili dotati di NFC](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android#supported-devices). TTPA richiede la versione più recente dell’[SDK di Terminal per Android](https://stripe.dev/stripe-terminal-android/). TTPA supporta le carte contactless Visa, Mastercard e American Express e wallet mobili basati su NFC (Apple Pay, Google Pay e Samsung Pay). TTPA è un’estensione dell’SDK di Terminal per Android e consente di effettuare pagamenti direttamente nella tua app Android.

Per connettere la tua app al lettore Tap to Pay su un dispositivo Android supportato, attieniti a questa procedura:

1. [Inizializzare l’SDK](https://docs.stripe.com/terminal/payments/connect-reader.md#initialize) per TTPA.
1. [Individua i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) utilizzando l’SDK per confermare la compatibilità del dispositivo.
1. [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) utilizzando l’SDK per accettare i pagamenti.
1. [Gestisci le disconnessioni impreviste](https://docs.stripe.com/terminal/payments/connect-reader.md#handling-disconnects) per assicurarti che l’utente possa continuare ad accettare pagamenti se il lettore si disconnette inaspettatamente.

Se l’applicazione viene eseguita su un dispositivo che non soddisfa i [criteri del dispositivo supportato](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android#supported-devices), l’SDK restituisce una `TerminalException` che fornisce ulteriore contesto in un callback `onFailure`.

## Inizializzare l'SDK

- [TapToPay (Android)](https://stripe.dev/stripe-terminal-android/cots/com.stripe.stripeterminal.taptopay/-tap-to-pay/-companion/is-in-tap-to-pay-process.html)

TTPA opera in un processo dedicato per rendere le transazioni più sicure. In questo processo, viene creata una seconda istanza di `Application`. Per evitare errori imprevisti causati dall’esecuzione del codice in questo processo, puoi saltare l’inizializzazione nella tua `Application` in questo processo selezionando `TapToPay.isInTapToPayProcess()`.

```kotlin
// Substitute with your application name, and remember to keep it the same as your AndroidManifest.xml
class StripeTerminalApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Skip initialization if running in the TTPA process.
        if (TapToPay.isInTapToPayProcess()) return

        // For example, this will be skipped.
        TerminalApplicationDelegate.onCreate(this)
    }
}
```

## Rilevare i lettori

- [discoverReaders (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/discover-readers.html)
- [TapToPayDiscoveryConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-discovery-configuration/-tap-to-pay-discovery-configuration/index.html)

Utilizza il metodo `discoverReaders` per determinare l’hardware supportato per Tap to Pay sul dispositivo Android. `discoverReaders` verifica i seguenti requisiti sul dispositivo Android:

- Dispone di un sensore NFC integrato funzionante e di un processore basato su ARM
- Funziona con Android 13 o versioni successive
- Dispone di un keystore con supporto hardware per ECDH ( la versione di [`FEATURE_HARDWARE_KEYSTORE`](https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_HARDWARE_KEYSTORE) deve essere 100 o successiva)
- Per la versione non simulata del lettore Tap to Pay, l’applicazione non può essere sottoposta a debug.

Affinché il servizio del lettore Tap to Pay possa essere avviato correttamente, l’applicazione *deve essere* in primo piano.

Se l’applicazione viene eseguita su un dispositivo che non soddisfa i requisiti sopra menzionati, il callback `onFailure` restituisce una `TerminalException` che contiene un [TerminalErrorCode](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/index.html) e ulteriore contesto. Gli errori in questa fase non sono risolvibili dall’utente finale.

Non è possibile utilizzare la versione di produzione non simulata del lettore Tap to Pay con applicazioni debuggabili o con le opzioni sviluppatore del dispositivo abilitate. Per testare l’integrazione con il lettore Tap to Pay su Android, imposta `TapToPayDiscoveryConfiguration.isSimulated` su `true` durante il rilevamento del lettore. È necessario impostare questo valore su `false` nella versione di rilascio dell’applicazione.

#### Kotlin

```kotlin
var discoverCancelable: Cancelable? = null

fun onDiscoverReaders() {
    val isApplicationDebuggable = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE
    val config = TapToPayDiscoveryConfiguration(isSimulated = isApplicationDebuggable)

    // Save this cancelable to an instance variable
    discoverCancelable = Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Automatically connect to supported mobile readers
            }
        },
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

override fun onStop() {
    super.onStop()

    // If you're leaving the activity or fragment without selecting a reader,
    // make sure you cancel the discovery process or the SDK will be stuck in
    // a discover readers phase
    discoverCancelable?.cancel(
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}
```

Per verificare se un dispositivo soddisfa i requisiti hardware e del sistema operativo di Tap to Pay in fase di esecuzione, utilizza la funzione [Terminal.supportsReadersOfType](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/supports-readers-of-type.html). Durante l’inizializzazione dell’SDK Terminal, questa funzione richiede che l’utente finale accetti le richieste di autorizzazione per accedere alla posizione e al Bluetooth. L’esecuzione di questa funzione richiede circa 10 millisecondi sulla maggior parte dei dispositivi.

## Connettere un lettore

> Nella versione `5.0.0` dell’SDK Android, è possibile utilizzare il metodo `easyConnect` per combinare il rilevamento del lettore e la connessione in un’unica chiamata API per semplificare l’integrazione. Per ulteriori dettagli, consulta la [guida alla migrazione dell’SDK](https://docs.stripe.com/terminal/references/sdk-migration-guide.md#update-your-reader-connection-usage).

- [connectReader (Android)](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html)
- [TapToPayConnectionConfiguration (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-tap-to-pay-connection-configuration/index.html)

Per accettare pagamenti Tap to Pay, fornisci il lettore individuato nel passaggio precedente al metodo `connectReader`.

`connectReader` verifica che il dispositivo Android soddisfi i seguenti requisiti:

- Non ha accesso root e il bootloader del dispositivo è bloccato e invariato
- Ha installato un aggiornamento di sicurezza negli ultimi 12 mesi
- Utilizza Google Mobile Services e ha installato l’app Google Play Store
- Ha una connessione stabile a Internet
- Esegue il sistema operativo fornito dal produttore non modificato
- L’applicazione utilizza l’SDK Tap to Pay versione 2.20.0 o successiva
- Le opzioni sviluppatore sono disabilitate per la versione non simulata del lettore Tap to Pay

Se l’applicazione viene eseguita su un dispositivo che non soddisfa i requisiti sopra menzionati, il callback `onFailure` restituisce una `TerminalException` che contiene un [TerminalErrorCode](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/index.html) e ulteriore contesto. Gli errori in questa fase non sono risolvibili dall’utente finale. L’utente finale può intervenire su alcuni dei [motivi di errore](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/index.html). Ad esempio:

- `STRIPE_API_CONNECTION_ERROR`: l’utente può connettersi a una connessione Internet stabile.
- `TAP_TO_PAY_UNSUPPORTED_ANDROID_VERSION`: l’utente può eseguire l’upgrade del sistema operativo, se è disponibile un aggiornamento dal produttore del dispositivo.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tal scopo, durante la connessione, crea e utilizza una `TapToPayConnectionConfiguration` con `locationId` impostato sull’ID posizione pertinente.

#### Kotlin

```kotlin
val tapToPayReaderListener = yourTapToPayReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val config = TapToPayConnectionConfiguration(
  ""{{LOCATION_ID}}"",
  autoReconnectOnUnexpectedDisconnect,
  tapToPayReaderListener
),
Terminal.getInstance().connectReader(
  firstReader,
  config,
  object : ReaderCallback {
      override fun onSuccess(reader: Reader) {
          // Placeholder for handling successful operation
      }

      override fun onFailure(e: TerminalException) {
          // Placeholder for handling exception
      }
  }
)
```

## Gestisci le disconnessioni impreviste

- [TapToPayReaderListener (Android)](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-tap-to-pay-reader-listener/index.html)

Potrebbero verificarsi disconnessioni impreviste tra l’app e il lettore. Ad esempio, il lettore Tap to Pay potrebbe disconnettersi inaspettatamente per i seguenti motivi:

- Il sistema operativo Android termina il servizio del lettore Tap to Pay a causa di limiti di memoria.
- Il dispositivo perde la connettività a Internet.

Sono disponibili due modi per gestire la situazione:

#### Tentare automaticamente la riconnessione

Puoi impostare `autoReconnectOnUnexpectedDisconnect` su `true` per abilitare l’SDK a tentare automaticamente la riconnessione quando si verifica una disconnessione imprevista. L’SDK imposta questo comportamento per impostazione predefinita se ometti questa impostazione. Facoltativamente, puoi anche implementare `TapToPayReaderListener` per i callback di riconnessione automatica nella tua app.

#### Kotlin

```kotlin
val tapToPayReaderListener = yourTapToPayReaderListener
val autoReconnectOnUnexpectedDisconnect = true

Terminal.getInstance().connectReader(
    reader,
    TapToPayConnectionConfiguration(
        ""{{LOCATION_ID}}"",
        autoReconnectOnUnexpectedDisconnect,
        tapToPayReaderListener
    ),
    readerCallback,
)
```

Quando l’SDK tenta di eseguire automaticamente la riconnessione, si verifica quanto segue:

1. Quando si verifica una disconnessione, l’SDK tenta automaticamente di riconnettersi e invia una notifica tramite `onReaderReconnectStarted`. Assicurati che l’app annunci che la connessione è stata persa e che è in corso una riconnessione.
   - Puoi utilizzare l’oggetto `Cancelable` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Se l’SDK si riconnette al lettore, Stripe ti invia una notifica tramite `onReaderReconnectSucceeded`. Assicurati che la tua app annunci che la connessione è stata ripristinata e che funzioni normalmente.
1. Se l’SDK non è in grado di riconnettersi al lettore, Stripe ti invia una notifica tramite `onReaderReconnectFailed` e `TapToPayReaderListener.onDisconnect`. Assicurati che la tua app annunci che si è verificata una disconnessione imprevista.

#### Kotlin

```kotlin
class CustomTapToPayReaderListener : TapToPayReaderListener {
    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}
```

#### Gestire manualmente la disconnessione

Per gestire autonomamente la disconnessione, devi:

1. Impostare `autoReconnectOnUnexpectedDisconnect` su `false` per disabilitare la riconnessione automatica predefinita.
1. Implementare `TapToPayReaderListener` per il callback `onDisconnect`.

Ciò consente alla tua app di riconnettersi al lettore Tap to Pay e, se necessario, comunicare all’utente cosa non ha funzionato e come abilitare l’accesso a Tap to Pay. Gli utenti finali possono risolvere determinati errori, come i problemi di connettività a Internet.

#### Kotlin

```kotlin
class ReaderActivity : AppCompatActivity(), TapToPayReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}
```

> Se gestisci la disconnessione manualmente senza disabilitare la riconnessione automatica, potrebbero verificarsi conflitti che interrompono la sessione del lettore.


# Tap to Pay su React Native

> This is a Tap to Pay su React Native for when terminal-sdk-platform is react-native and reader-type is tap-to-pay. View the full page at https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=react-native&reader-type=tap-to-pay.

Tap to Pay consente agli utenti di accettare pagamenti contactless di persona con [dispositivi Android compatibili dotati di NFC](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=android#supported-devices) o di [iPhone compatibili](https://docs.stripe.com/terminal/payments/setup-reader/tap-to-pay.md?platform=ios#supported-devices). Tap to Pay supporta carte contactless Visa, Mastercard e American Express e per wallet mobili basati su NFC (Apple Pay, Google Pay e Samsung Pay). Tap to Pay su iPhone e Android è un’estensione delle SDK Terminal e abilita i pagamenti direttamente nell’app per dispositivi mobili.

> Nella versione `0.0.1-beta.29` dell’SDK React Native, è possibile utilizzare il metodo [easyConnect](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#easyconnect) per unificare il rilevamento del lettore e la connessione in un’unica chiamata API in modo da semplificare l’integrazione.

Per connettere la tua app al lettore Tap to Pay su un dispositivo supportato, attieniti a questa procedura:

- [Inizializza l’SDK](https://docs.stripe.com/terminal/payments/connect-reader.md#initialize) per TTPA, se utilizzi l’SDK su un dispositivo Android.
- [Individua i lettori](https://docs.stripe.com/terminal/payments/connect-reader.md#discover-readers) utilizzando l’SDK per confermare la compatibilità del dispositivo.
- [Connettiti a un lettore](https://docs.stripe.com/terminal/payments/connect-reader.md#connect-reader) utilizzando l’SDK per accettare i pagamenti.
- [Gestisci le disconnessioni impreviste](https://docs.stripe.com/terminal/payments/connect-reader.md#handling-disconnects) per assicurarti che l’utente possa continuare ad accettare pagamenti se il lettore si disconnette inaspettatamente.

## Inizializzare l'SDK

Tap to Pay su Android opera in un processo dedicato per rendere le transazioni più sicure. In questo processo, viene creata una seconda istanza della tua `Application`. Per evitare errori imprevisti causati dall’esecuzione del codice su un dispositivo Android, puoi saltare l’inizializzazione nella tua `Application` in questo processo selezionando `TapToPay.isInTapToPayProcess()`.

```kotlin
class MainApplication : Application(), ReactApplication {
    override fun onCreate() {
        super.onCreate()

        // Skip initialization if running in the TTPA process.
        if (TapToPay.isInTapToPayProcess()) return

        // For example, this will be skipped.
        TerminalApplicationDelegate.onCreate(this)
    }
}
```

## Rilevare i lettori

- [discoverReaders (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#discoverReaders)

Utilizza il metodo `discoverReaders` per determinare l’hardware supportato per Tap to Pay sul tuo dispositivo.

Se l’applicazione viene eseguita su un dispositivo che non soddisfa i requisiti di cui sopra, il metodo `discoverReaders` restituisce un errore.

```js
export default function DiscoverReadersScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // The `readers` variable will contain an array of all the discovered readers.
      },
    });

  useEffect(() => {
    const { error } = await discoverReaders({
      discoveryMethod: 'tapToPay',
    });
  }, [discoverReaders]);

  return <View />;
}
```

## Connettere un lettore

- [connectReader (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/interfaces/StripeTerminalSdkType.html#connectreader-1)

Per accettare pagamenti Tap to Pay, fornisci il lettore individuato nel passaggio precedente al metodo `connectReader`.

Devi [registrare il lettore](https://docs.stripe.com/terminal/fleet/locations-and-zones.md) in una [posizione](https://docs.stripe.com/api/terminal/locations.md) al momento della connessione. A tal scopo, devi specificare l’ID posizione pertinente in `connectReader`.

Quando si utilizzano gli [addebiti indiretti con on_behalf_of](https://docs.stripe.com/terminal/features/connect.md?connect-charge-type=destination) su iPhone, è necessario specificare anche l’ID account connesso.

```js
const { reader, error } = await connectReader({
    discoveryMethod: 'tapToPay',
    reader: selectedReader,
    locationId: "{{LOCATION_ID}}",
});

if (error) {
  console.log('connectTapToPayReader error:', error);
  return;
}

console.log('Reader connected successfully', reader);
```

### Collegamento di account e termini e condizioni Apple

La prima volta che ti connetti al lettore, vengono visualizzati i termini e le condizioni di Tap to Pay su iPhone di Apple. Per registrarti con Apple, devi specificare un ID Apple valido che rappresenti la tua attività prima di accettare i termini presentati da Apple. Devi eseguire questa operazione una sola volta per account Stripe. L’account non deve ripetere questa procedura nelle connessioni successive, anche su altri dispositivi mobili.

Ogni account connesso deve accettare i Termini e le Condizioni quando:

- Un utente Connect crea addebiti diretti
- Un utente Connect crea un addebito indiretto e specifica un account `on_behalf_of`
![Processo in tre fasi che mostra l'accesso con l'ID Apple, l'accettazione dei termini e la conferma dell'avvenuta registrazione per Tap to Pay su iPhone.](https://b.stripecdn.com/docs-statics-srv/assets/ttpoi-account-linking-steps.56bc5c0bb037a98f788a7e8d43d0c87e.png)

Collega il tuo account Apple ID per accettare pagamenti Tap to Pay

Se chiami `connectReader` per Tap to Pay su iPhone, tutti gli iPhone possono utilizzare fino a tre account Stripe univoci sulle app per 24 ore. Se utilizzi altri account per il dispositivo nello stesso periodo di 24 ore, il metodo di chiamata `connectReader` genera un errore [SCPErrorTapToPayReaderMerchantBlocked](https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPError.html#/c:@E@SCPError@SCPErrorTapToPayReaderMerchantBlocked).

Ulteriori informazioni sul collegamento dell’account nella sezione Tap to Pay su iPhone - Informazioni sull’attività nelle [Domande Frequenti su Tap to Pay su iPhone](https://register.apple.com/tap-to-pay-on-iphone/faq.html).

## Gestisci le disconnessioni impreviste

- [UserCallbacks (React Native)](https://stripe.dev/stripe-terminal-react-native/api-reference/index.html#REPORT_UNEXPECTED_READER_DISCONNECT)

Potrebbero verificarsi disconnessioni impreviste tra l’app e il lettore. Ad esempio, il lettore Tap to Pay potrebbe disconnettersi inaspettatamente se il dispositivo perde la connettività a Internet e il sistema operativo Android termina il servizio del lettore a causa di limiti di memoria.

Durante il test, puoi simulare una disconnessione imprevista disabilitando l’accesso a Internet sul tuo dispositivo.

#### Tentare automaticamente la riconnessione

Puoi impostare `autoReconnectOnUnexpectedDisconnect` su `true` per consentire all’SDK di tentare automaticamente la riconnessione quando si verifica una disconnessione imprevista. Se ometti questa impostazione, l’SDK imposta questo comportamento per impostazione predefinita.

```js
const { reader, error } = await connectReader({
    discoveryMethod: 'tapToPay',
    reader,
    autoReconnectOnUnexpectedDisconnect: true, // default setting
});

if (error) {
  console.log('connectReader error:', error);
  return;
}

console.log('Reader connected successfully', reader);
```

Quando l’SDK tenta di eseguire automaticamente la riconnessione, si verifica quanto segue:

1. L’SDK invia una notifica tramite `onDidStartReaderReconnect`. Assicurati che l’app annunci che la connessione è stata persa e che è in corso una riconnessione.
   - Puoi utilizzare il metodo `cancelReaderReconnection` per interrompere il tentativo di riconnessione in qualsiasi momento.
1. Se l’SDK si riconnette al lettore, Stripe ti invia una notifica tramite `onDidSucceedReaderReconnect`. Assicurati che la tua app segnali che la connessione è stata ripristinata e che è possibile continuare le normali operazioni.
1. Se l’SDK non è in grado di riconnettersi al lettore, Stripe ti invia una notifica tramite `onDidFailReaderReconnect` e `onDidDisconnect`. Assicurati che la tua app annunci che si è verificata una disconnessione imprevista.

```js
const { discoverReaders, connectedReader, discoveredReaders } =
    useStripeTerminal({
      onDidStartReaderReconnect: (disconnectReason) => {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
      },
      onDidSucceedReaderReconnect: () => {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
      },
      onDidFailReaderReconnect: () => {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
      }
    });
```

#### Gestire manualmente la disconnessione

Per gestire autonomamente la disconnessione, devi:

1. Impostare `autoReconnectOnUnexpectedDisconnect` su `false` per disabilitare la riconnessione automatica predefinita.
1. Implementare il callback `onDidReportUnexpectedReaderDisconnect`.

Ciò consente alla tua app di riconnettersi al lettore Tap to Pay e, se necessario, comunicare all’utente cosa non ha funzionato e come abilitare l’accesso a Tap to Pay. Gli utenti finali possono risolvere determinati errori, come i problemi di connettività a Internet.

```js
const { discoverReaders, connectedReader, discoveredReaders } =
    useStripeTerminal({
      onDidReportUnexpectedReaderDisconnect: (readers) => {
        // Consider displaying a UI to notify the user and start rediscovering readers
      },
    });
```

> Se gestisci la disconnessione manualmente senza disabilitare la riconnessione automatica, potrebbero verificarsi conflitti che interrompono la sessione del lettore.


## Passaggi successivi

Hai connesso la tua applicazione al lettore. Poi [riscuoti il tuo primo pagamento Stripe Terminal](https://docs.stripe.com/terminal/payments/collect-card-payment.md).

Il nome e il logo BBPOS e Chipper™ sono marchi commerciali o marchi registrati di BBPOS Limited negli Stati Uniti o in altri paesi. Il nome e il logo Verifone® sono marchi commerciali o marchi registrati di Verifone negli Stati Uniti e/o in altri paesi. L’uso dei marchi commerciali non implica alcuna approvazione da parte di BBPOS o Verifone.