# Accettare un pagamento

Accettare pagamenti online in modo sicuro

Stripe consiglia di utilizzare l’API Checkout Sessions con Payment Element anziché Payment Intents per la maggior parte delle integrazioni. Checkout Sessions copre casi d’uso simili a quelli di Payment Intents (raccolta di pagamenti di base utilizzando `price_data` o creazione di un checkout completo con voci riga, imposte e così via). Alcune funzioni, come Adaptive Pricing, sono disponibili solo con Checkout Sessions. Non utilizzare l’API Payment Intent a meno che l’utente non lo richieda esplicitamente, poiché richiede una quantità di codice significativamente maggiore. Ulteriori informazioni sugli elementi con l’API Checkout Sessions: https://docs.stripe.com/payments/quickstart. con Checkout Sessions (`ui_mode: "elements"`) e Payment Element, `client_secret` inizializza Checkout stesso (`stripe.initCheckoutElementsSdk`, oppure utilizza CheckoutElementsProvider con React) e tu confermi il pagamento sul lato client in modo diverso. Se utilizzi React, assicurati di importare da `@stripe/react-stripe-js/checkout`, utilizza `CheckoutElementsProvider` con la chiave privata client e conferma utilizzando `checkout.confirm`. Se utilizzi HTML, assicurati di utilizzare `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` e conferma con `loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();`.

Gli agenti di programmazione dovrebbero installare Stripe CLI (`npm i -g @stripe/cli`) ed eseguire il comando `stripe sandbox create --help` per predisporre una sandbox Stripe anonima con chiavi API funzionanti. Non è richiesta la registrazione di un account.

Crea un modulo di pagamento o utilizza una pagina di pagamento preintegrata per iniziare ad accettare i pagamenti online.

# Integrazione in-app per iOS

![](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.9e0d68d009dc005f73a6f5df69e00458.png)

Integra l’interfaccia utente per i pagamenti preintegrata di Stripe nella procedura di pagamento della tua app iOS con la classe [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html). Consulta il nostro esempio di integrazione [su GitHub](https://github.com/stripe/stripe-ios/tree/master/Example/PaymentSheet%20Example).

In alternativa, inizia dalla [guida rapida al codice](https://docs.stripe.com/payments/mobile/quickstart.md?platform=ios) per creare o scaricare un esempio eseguibile.

> #### Assistenza API Accounts v2
> 
> Payment Sheet non fornisce assistenza per gli *account configurati dal cliente* (Account configurations represent role-based functionality that you can enable for accounts, such as merchant, customer, or recipient). Supporta solo oggetti `Customer`.

## Configurare Stripe [Lato server] [Lato client]

Innanzitutto, devi creare un account Stripe. [Registrati ora](https://dashboard.stripe.com/register).

### Lato server

Per questa integrazione sono necessari endpoint sul server che comunicano con l’API Stripe. Utilizza le nostre librerie ufficiali per accedere all’API Stripe dal tuo server:

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

### Lato client

L’[SDK per iOS di Stripe](https://github.com/stripe/stripe-ios) è open source, [completamente documentato](https://stripe.dev/stripe-ios/index.html) e compatibile con le app che supportano iOS 13 o versioni successive.

#### Swift Package Manager

Per installare l’SDK, segui questi passaggi:

1. In Xcode, seleziona **File** > **Aggiungi dipendenze pacchetto…** e inserisci `https://github.com/stripe/stripe-ios-spm` come URL repository.
2. Seleziona il numero dell’ultima versione dalla nostra [pagina delle release](https://github.com/stripe/stripe-ios/releases).
3. Aggiungi il prodotto **StripePaymentSheet** al [target della tua app](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### Carthage

1. Se non l’hai ancora fatto, installa la versione più recente di [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
2. Aggiungi questa riga al tuo `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
3. Segui le [istruzioni per l’installazione di Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Assicurati di integrare tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
4. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, esegui il seguente comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Framework manuale

1. Vai alla [pagina delle versioni di GitHub](https://github.com/stripe/stripe-ios/releases/latest) e scarica e decomprimi **Stripe.xcframework.zip**.
2. Trascina **StripePaymentSheet.xcframework** nella sezione **Embedded Binaries** (File binari incorporati) delle impostazioni **General** (Generali) nel tuo progetto Xcode. Assicurati che sia selezionato **Copy items if needed** (Copia elementi se necessario).
3. Ripeti il passaggio 2 per tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking).
4. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, ripeti i passaggi 1-3.

> Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Versioni](https://github.com/stripe/stripe-ios/releases) su GitHub. Per ricevere notifiche quando viene pubblicata una nuova versione, [guarda le versioni](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) del repository.

## Abilitare modalità di pagamento

Visualizza le [impostazioni delle modalità di pagamento](https://dashboard.stripe.com/settings/payment_methods) e abilita le modalità di pagamento che vuoi accettare. Per creare un *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) è necessario che sia abilitata almeno una modalità di pagamento.

Per impostazione predefinita, Stripe abilita le carte e altri metodi di pagamento tra i più utilizzati per aiutarti a raggiungere più clienti. Detto ciò, ti consigliamo di attivare ulteriori metodi pertinenti per la tua attività e i tuoi clienti. Per ulteriori informazioni sul supporto di prodotti e metodi di pagamento, consulta la sezione [Supporto per il metodo di pagamento](https://docs.stripe.com/payments/payment-methods/payment-method-support.md). Per le commissioni consulta la nostra [pagina delle tariffe](https://stripe.com/pricing/local-payment-methods).

## Aggiungere un endpoint [Lato server]

> #### Nota
> 
> Per visualizzare il PaymentSheet prima di creare un PaymentIntent, consulta [Raccogliere i dati di pagamento prima di creare un intento](https://docs.stripe.com/payments/accept-a-payment-deferred.md?type=payment).

Questa integrazione utilizza tre oggetti dell’API Stripe:

1. [PaymentIntent](https://docs.stripe.com/api/payment_intents.md): Stripe lo utilizza per rappresentare la tua intenzione di riscuotere un pagamento da un cliente, monitorando i tentativi di addebito e le modifiche dello stato del pagamento durante la procedura.
2. (Facoltativo) [Customer](https://docs.stripe.com/api/customers.md): per configurare un metodo di pagamento per pagamenti futuri, devi collegarlo a un cliente. Crea un oggetto che rappresenti il tuo cliente quando crea un account con la tua attività. Se il tuo cliente effettua un pagamento come ospite, puoi creare un oggetto `Customer` prima del pagamento e associarlo in seguito alla tua rappresentazione interna dell’account del cliente.
3. (Facoltativo) [CustomerSession](https://docs.stripe.com/api/customer_sessions.md): le informazioni sull’oggetto che rappresenta il tuo cliente sono sensibili e non possono essere recuperate direttamente da un’app. Una `CustomerSession` concede all’SDK l’accesso temporaneo con ambito limitato a `Customer` e fornisce ulteriori [opzioni di configurazione](https://docs.stripe.com/api/customer_sessions/create.md#create_customer_session-components).

> Se non salvi mai le carte per i clienti, puoi omettere l’oggetto `Customer` e l’oggetto `CustomerSession` dalla tua integrazione.

Per motivi di sicurezza, la tua app non può creare questi oggetti. Aggiungi invece un endpoint sul tuo server per:

1. Recupera l’oggetto `Customer` o ne crea uno nuovo.
2. Crea [CustomerSession](https://docs.stripe.com/api/customer_sessions.md) per `Customer`.
3. Crea un `PaymentIntent` con l’[importo](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-amount), la [valuta](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-currency), e il [cliente](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer).
4. Restituisce alla tua app la *chiave privata client* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) del `PaymentIntent`, il `client_secret` di `CustomerSession`, l’ID di `Customer` e la tua [chiave pubblica](https://dashboard.stripe.com/apikeys).

Imposta sul `PaymentIntent` lo stesso `Customer` che hai impostato su `CustomerSession`.

I metodi di pagamento mostrati ai clienti durante il completamento della transazione sono inclusi anche nel PaymentIntent. Puoi consentire a Stripe di acquisire i metodi di pagamento dalle impostazioni della Dashboard oppure puoi elencarli manualmente. Indipendentemente dall’opzione che sceglierai, ricorda che la valuta specificata nel PaymentIntent filtra il metodo di pagamento mostrato al cliente. Ad esempio, se specifichi `eur` nel PaymentIntent e hai abilitato OXXO nella Dashboard, il cliente non vedrà OXXO perché questo metodo non supporta i pagamenti in `eur`.

A meno che la tua integrazione non richieda un’opzione con codice per offrire i metodi di pagamento, Stripe consiglia l’opzione automatica. Ciò è dovuto al fatto che Stripe valuta le limitazioni dei metodi di pagamento, la valuta e altri parametri per determinare l’elenco dei metodi di pagamento accettati. I metodi di pagamento che migliorano la conversione e che sono più pertinenti alla valuta e alla posizione del cliente hanno la priorità.

#### Gestire i metodi di pagamento dalla Dashboard

Puoi gestire i metodi di pagamento dalla [Dashboard](https://dashboard.stripe.com/settings/payment_methods). Stripe crea il `PaymentIntent` utilizzando i metodi di pagamento idonei che hai configurato, in base a fattori quali l’importo della transazione, la valuta e il flusso di pagamento. Se non vuoi utilizzare la Dashboard, o se vuoi specificare manualmente i metodi di pagamento consentiti, puoi utilizzare il parametro `allowed_payment_method_types`.

#### curl

```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create a CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \

  -d "automatic_payment_methods[enabled]"=true \
```

#### Elencare manualmente i metodi di pagamento

#### curl

```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create a CustomerSession for the Customer
curl https://api.stripe.com/v1/customer_sessions \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "components[mobile_payment_element][enabled]"=true \
  -d "components[mobile_payment_element][features][payment_method_save]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_redisplay]"=enabled \
  -d "components[mobile_payment_element][features][payment_method_remove]"=enabled

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "allowed_payment_method_types[]"="bancontact" \
  -d "allowed_payment_method_types[]"="card" \
  -d "allowed_payment_method_types[]"="ideal" \
  -d "allowed_payment_method_types[]"="klarna" \
  -d "allowed_payment_method_types[]"="sepa_debit" \
```

> Ogni metodo di pagamento deve accettare la valuta specificata nel PaymentIntent e la tua attività deve avere la sede in uno dei Paesi accettati dal metodo di pagamento. Per ulteriori informazioni sulle funzionalità supportate, consulta la pagina dedicata alle [opzioni di integrazione dei metodi di pagamento](https://docs.stripe.com/payments/payment-methods/integration-options.md).

## Acquisire i dati di pagamento [Lato client]

Per visualizzare Payment Element per dispositivo mobile nella schermata di pagamento:

- Mostrare i prodotti che il cliente sta acquistando insieme all’importo totale
- Utilizza [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios) per raccogliere dal cliente tutti i dati di spedizione richiesti
- Aggiungere un pulsante di pagamento per visualizzare l’interfaccia utente di Stripe

#### UIKit

Nella schermata di checkout della tua app, recupera la chiave privata client PaymentIntent, la chiave privata client `CustomerSession`, l’ID `Customer` e la chiave pubblicabile dall’endpoint creato nel passaggio precedente. Utilizza `STPAPIClient.shared` per impostare la tua chiave pubblicabile e inizializzare [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

#### iOS (Swift)

```swift
import UIKit
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet

class CheckoutViewController: UIViewController {
  @IBOutlet weak var checkoutButton: UIButton!
  var paymentSheet: PaymentSheet?
  let backendCheckoutUrl = URL(string: "Your backend endpoint/payment-sheet")! // Your backend endpoint

  override func viewDidLoad() {
    super.viewDidLoad()

    checkoutButton.addTarget(self, action: #selector(didTapCheckoutButton), for: .touchUpInside)
    checkoutButton.isEnabled = false

    // MARK: Fetch the PaymentIntent client secret, CustomerSession client secret, Customer ID, and publishable key
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true
      self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)

      DispatchQueue.main.async {
        self.checkoutButton.isEnabled = true
      }
    })
    task.resume()
  }

}
```

Quando il cliente tocca il pulsante **Checkout**, chiama `present` per aprire il PaymentSheet. Dopo che il cliente ha completato il pagamento, Stripe chiude il PaymentSheet e chiama il blocco di completamento con [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

#### iOS (Swift)

```swift
@objc
func didTapCheckoutButton() {
  // MARK: Start the checkout process
  paymentSheet?.present(from: self) { paymentResult in
    // MARK: Handle the payment result
    switch paymentResult {
    case .completed:
      print("Your order is confirmed")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print("Payment failed: \(error)")
    }
  }
}
```

#### SwiftUI

Crea un modello `ObservableObject` per la tua schermata di pagamento. Questo modello pubblica un [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html) e un [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?
}
```

Recupera il segreto client PaymentIntent, la chiave privata client CustomerSession, l’ID `Customer` e la chiave pubblicabile dall’endpoint creato nel passaggio precedente. Utilizza `STPAPIClient.shared` per impostare la chiave pubblicabile e inizializzare [PaymentSheet](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet.html).

```swift

@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?

  func preparePaymentSheet() {
    // MARK: Fetch thePaymentIntent and Customer information from the back end
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            letpaymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business handles
      // delayed notification payment methods like US bank accounts.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret:paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }
}

struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {
      if model.paymentSheet != nil {
        Text("Ready to pay.")
      } else {
        Text("Loading…")
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Aggiungi un [PaymentSheet.PaymentButton](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/PaymentButton.html) alla tua `View`. Si comporta in modo simile a un `Button` di SwiftUI, che ti consente di personalizzarlo aggiungendo una `View`. Quando tocchi il pulsante, viene visualizzato il PaymentSheet. Una volta completato il pagamento, Stripe chiude il PaymentSheet e chiama il gestore `onCompletion` con un oggetto [PaymentSheetResult](https://stripe.dev/stripe-ios/stripe-paymentsheet/Enums/PaymentSheetResult.html).

```swift
@_spi(CustomerSessionBetaAccess) import StripePaymentSheet
import SwiftUI

class CheckoutViewModel: ObservableObject {
  let backendCheckoutUrl = URL(string: "Your back-end endpoint/payment-sheet")! // Your back-end endpoint
  @Published var paymentSheet: PaymentSheet?
  @Published var paymentResult: PaymentSheetResult?

  func preparePaymentSheet() {
    // MARK: Fetch the PaymentIntent and Customer information from the back end
    var request = URLRequest(url: backendCheckoutUrl)
    request.httpMethod = "POST"
    let task = URLSession.shared.dataTask(with: request, completionHandler: { [weak self] (data, response, error) in
      guard let data = data,
            let json = try? JSONSerialization.jsonObject(with: data, options: []) as? [String : Any],
            let customerId = json["customer"] as? String,
            let customerSessionClientSecret = json["customerSessionClientSecret"] as? String,
            let paymentIntentClientSecret = json["paymentIntent"] as? String,
            let publishableKey = json["publishableKey"] as? String,
            let self = self else {
        // Handle error
        return
      }

      STPAPIClient.shared.publishableKey = publishableKey
      // MARK: Create a PaymentSheet instance
      var configuration = PaymentSheet.Configuration()
      configuration.merchantDisplayName = "Example, Inc."
      configuration.customer = .init(id: customerId, customerSessionClientSecret: customerSessionClientSecret)
      // Set `allowsDelayedPaymentMethods` to true if your business can handle payment methods
      // that complete payment after a delay, like SEPA Debit and Sofort.
      configuration.allowsDelayedPaymentMethods = true

      DispatchQueue.main.async {
        self.paymentSheet = PaymentSheet(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration)
      }
    })
    task.resume()
  }

  func onPaymentCompletion(result: PaymentSheetResult) {
    self.paymentResult = result
  }
}

struct CheckoutView: View {
  @ObservedObject var model = CheckoutViewModel()

  var body: some View {
    VStack {
      if let paymentSheet = model.paymentSheet {
        PaymentSheet.PaymentButton(
          paymentSheet: paymentSheet,
          onCompletion: model.onPaymentCompletion
        ) {
          Text("Buy")
        }
      } else {
        Text("Loading…")
      }
      if let result = model.paymentResult {
        switch result {
        case .completed:
          Text("Payment complete")
        case .failed(let error):
          Text("Payment failed: \(error.localizedDescription)")
        case .canceled:
          Text("Payment canceled.")
        }
      }
    }.onAppear { model.preparePaymentSheet() }
  }
}
```

Se `PaymentSheetResult` è `.completed`, informa il cliente (ad esempio, mostrando una scherma di conferma dell’ordine).

Impostare `allowsDelayedPaymentMethods` su true consente di utilizzare i metodi di pagamento con [notifica differita](https://docs.stripe.com/payments/payment-methods.md#payment-notification) come i conti bancari degli Stati Uniti. Per questi metodi di pagamento, lo stato finale del pagamento non è noto al completamento di `PaymentSheet`, in quanto va a buon fine o meno in un secondo momento. Se supporti questi tipi di metodi di pagamento, informa il cliente che il suo ordine è confermato e procedi all’evasione (ad esempio alla spedizione del prodotto), spedisci il suo prodotto) solo quando avrai ricevuto il pagamento.

## Configurare un URL di ritorno [Lato client]

Il cliente potrebbe uscire dalla tua app per autenticarsi (ad es. in Safari o nell’app della banca). Per consentirgli di tornare automaticamente alla tua app dopo l’autenticazione, devi [configurare uno schema URL personalizzato](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) e impostare la classe AppDelegate per l’inoltro di URL all’SDK Stripe. Stripe non supporta i [link universali](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content).

#### SceneDelegate

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (!stripeHandled) {
        // This was not a Stripe url – handle the URL normally as you would
    }
}

```

#### AppDelegate

#### Swift

```swift
// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    let stripeHandled = StripeAPI.handleURLCallback(with: url)
    if (stripeHandled) {
        return true
    } else {
        // This was not a Stripe url – handle the URL normally as you would
    }
    return false
}
```

#### SwiftUI

#### Swift

```swift

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      Text("Hello, world!")
        .onOpenURL { incomingURL in
          let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL)
          if (!stripeHandled) {
            // This was not a Stripe url – handle the URL normally as you would
          }
        }
    }
  }
}
```

Devi inoltre impostare il [returnURL](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV9returnURLSSSgvp) nel tuo oggetto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html) sull’URL della tua app.

```swift
var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"
```

## Gestire gli eventi successivi al pagamento [Lato server]

Stripe invia un evento [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) quando il pagamento viene completato. Utilizza lo [strumento webhook Dashboard](https://dashboard.stripe.com/webhooks) o segui la [guida ai webhook](https://docs.stripe.com/webhooks/quickstart.md) per ricevere questi eventi ed eseguire azioni come l’invio di una email per la conferma di un ordine al cliente, la registrazione della vendita in un database o l’avvio del flusso di lavoro per una spedizione.

Ascolta questi eventi invece di attendere una chiamata di ritorno dal client. Sul client, il cliente potrebbe chiudere la finestra del browser o uscire dall’app prima dell’esecuzione della chiamata di ritorno e i client malintenzionati potrebbero manipolare la risposta. La configurazione dell’integrazione per l’ascolto di eventi asincroni ti consente di accettare [diversi tipi di modalità di pagamento](https://stripe.com/payments/payment-methods-guide) con una sola integrazione.

Oltre alla gestione dell’evento `payment_intent.succeeded`, è consigliabile gestire altri eventi durante la riscossione di pagamenti tramite Payment Element:

| Evento                                                                                                                          | Descrizione                                                                                                                                                                                                                                                                                        | Azione                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | Inviato quando un cliente ha disposto un pagamento con esito positivo.                                                                                                                                                                                                                             | Invia al cliente la conferma di un ordine ed *evade* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected) l’ordine. |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | Inviato quando un cliente ha correttamente disposto un pagamento che non è stato ancora completato. Questo evento viene di solito inviato quando il cliente dispone un addebito bancario. Sarà poi seguito da un evento `payment_intent.succeeded` o da un evento `payment_intent.payment_failed`. | Invia al cliente la conferma di un ordine che indica il pagamento in sospeso. Per i beni digitali, potresti voler evadere l’ordine senza attendere il completamento del pagamento.           |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | Inviato quando il cliente ha tentato un pagamento che non è andato a buon fine.                                                                                                                                                                                                                    | Se un pagamento passa da `processing` a `payment_failed`, offri al cliente un altro tentativo di pagamento.                                                                                  |

## Testare l'integrazione

#### Carte

| Numero di carta     | Scenario                                                                                                                                                                                                                                                                                              | Come eseguire il test                                                                                                  |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 4242424242424242    | Il pagamento con carta ha esito positivo e non richiede l’autenticazione.                                                                                                                                                                                                                             | Compila il modulo della carta di credito utilizzando il numero di carta di credito con scadenza, CVC e codice postale. |
| 4000002500003155    | Il pagamento con carta richiede l’*autenticazione* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase). | Compila il modulo della carta di credito utilizzando il numero di carta di credito con scadenza, CVC e codice postale. |
| 4000000000009995    | La carta viene rifiutata con un codice di rifiuto del tipo `insufficient_funds`.                                                                                                                                                                                                                      | Compila il modulo della carta di credito utilizzando il numero di carta di credito con scadenza, CVC e codice postale. |
| 6205500000000000004 | La carta UnionPay ha una lunghezza variabile di 13-19 cifre.                                                                                                                                                                                                                                          | Compila il modulo della carta di credito utilizzando il numero di carta di credito con scadenza, CVC e codice postale. |

#### Reindirizzamenti bancari

| Modalità di pagamento | Scenario                                                                                                                                                                                                                                                   | Come eseguire il test                                                                                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Bancontact, iDEAL     | Il cliente non riesce a eseguire l’autenticazione nella pagina di reindirizzamento per una modalità di pagamento con reindirizzamento e notifica immediata.                                                                                                | Scegli una qualsiasi modalità di pagamento con reindirizzamento, fornisci i dati richiesti e conferma il pagamento. Quindi fai clic su **Interrompi il pagamento di test** nella pagina di reindirizzamento. |
| Pay by Bank           | Il tuo cliente paga correttamente con un metodo di pagamento con reindirizzamento e [notifica differita](https://docs.stripe.com/payments/payment-methods.md#payment-notification).                                                                        | Scegli la modalità di pagamento, fornisci i dati richiesti e conferma il pagamento. Quindi fai clic su **Completa il pagamento di test** nella pagina di reindirizzamento.                                   |
| Pay by Bank           | Il cliente non riesce a eseguire l’autenticazione nella pagina di reindirizzamento per una modalità di pagamento con reindirizzamento e notifica differita.                                                                                                | Scegli la modalità di pagamento, fornisci i dati richiesti e conferma il pagamento. Quindi fai clic su **Interrompi il pagamento di test** nella pagina di reindirizzamento.                                 |
| BLIK                  | I pagamenti BLIK non vanno a buon fine per vari motivi. In alcuni casi si tratta di errori immediati (ad esempio il codice è scaduto o non è valido), di errori ritardati (la banca rifiuta il pagamento) o di timeout (il cliente non risponde in tempo). | Utilizza i modelli di email per [simulare i diversi errori.](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures)                                                                    |

#### Addebiti bancari

| Modalità di pagamento | Scenario                                                                                       | Come eseguire il test                                                                                                                                                                                 |
| --------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Addebito diretto SEPA | Il tuo cliente paga correttamente con addebito diretto SEPA.                                   | Compila il modulo usando il numero di conto `AT321904300235473204`. Il PaymentIntent confermato passerà inizialmente allo stato in elaborazione e, tre minuti dopo, allo stato di pagamento riuscito. |
| Addebito diretto SEPA | Lo stato del Payment Intent del tuo cliente passa da `processing` a `requires_payment_method`. | Compila il modulo usando il numero di conto `AT861904300235473202`.                                                                                                                                   |

Per ulteriori informazioni su come testare la tua integrazione, consulta la sezione [Test](https://docs.stripe.com/testing.md).

## Optional: Enable Link

Abilita Link nelle [impostazioni dei metodi di pagamento](https://dashboard.stripe.com/settings/payment_methods) per consentire ai tuoi clienti di salvare e riutilizzare in modo sicuro i propri dati di pagamento tramite il pulsante di pagamento rapido con un solo clic di Link.

### Specificare l’indirizzo email del cliente in Mobile Payment Element

Link effettua l’autenticazione di un cliente utilizzando il suo indirizzo email. Stripe consiglia di precompilare il maggior numero possibile di informazioni per semplificare la procedura di pagamento.

Per precompilare il nome, l’indirizzo email e il numero di telefono del cliente, specifica una proprietà `defaultBillingDetails` con le informazioni del cliente dopo l’inizializzazione di `PaymentSheet.Configuration`.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.name = "Jenny Rosen"
configuration.defaultBillingDetails.email = "jenny.rosen@example.com"
configuration.defaultBillingDetails.phone = "888-888-8888"
```

### Gestisci la disconnessione dell’utente

`PaymentSheet` memorizza localmente alcune informazioni per ricordare se un utente ha utilizzato Link in un’app. Per cancellare lo stato interno di `PaymentSheet`, chiama il metodo `PaymentSheet.resetCustomer()` quando l’utente si disconnette.

```swift
import UIKit
import StripePaymentSheet

class MyViewController: UIViewController {

  @objc
  func didTapLogoutButton() {
    PaymentSheet.resetCustomer()
    // Other logout logic required by your app
  }

}
```

## Optional: Abilitare Apple Pay

> Se nella tua schermata di pagamento è presente un **pulsante Apple Pay** dedicato, segui le istruzioni indicate nella [guida di Apple Pay](https://docs.stripe.com/apple-pay.md#present-payment-sheet) e usa `ApplePayContext` per riscuotere il pagamento tramite il pulsante Apple Pay. Puoi usare `PaymentSheet` per gestire altri metodi di pagamento.

### Registra un nuovo ID esercente Apple

Ottieni un ID esercente Apple [effettuando la registrazione di un nuovo identificativo](https://developer.apple.com/account/resources/identifiers/add/merchant) sul sito web degli sviluppatori Apple.

Compila il modulo con una descrizione e un identificativo. La descrizione è un promemoria per te e potrai modificarla in futuro. Stripe consiglia di utilizzare il nome dell’app come identificativo (ad esempio, `merchant.com.{{YOUR_APP_NAME}}`).

### Crea un nuovo certificato di Apple Pay

Crea un certificato per la tua app per crittografare i dati di pagamento.

Vai su [Impostazioni certificato iOS](https://dashboard.stripe.com/settings/ios_certificates) nella Dashboard, fai clic su **Aggiungi nuova applicazione** e segui la guida.

Scarica un file con richiesta di firma certificato (CSR) per ottenere da Apple un certificato sicuro che ti consentirà di utilizzare Apple Pay.

Un file CSR deve essere utilizzato per emettere un solo certificato. Se cambi il tuo ID esercente Apple, devi andare su [Impostazioni certificato iOS](https://dashboard.stripe.com/settings/ios_certificates) nella Dashboard per ottenere un nuovo CSR e un nuovo certificato.

### Effettua l’integrazione con Xcode

Aggiungi la funzionalità Apple Pay alla tua app. In Xcode, apri le impostazioni di progetto, fai clic nella scheda **Signing & Capabilities** (Firma e funzionalità), poi aggiungi la funzionalità **Apple Pay**. A questo punto il sistema potrebbe chiederti di effettuare l’accesso al tuo account di sviluppatore. Seleziona l’ID esercente che hai creato e la tua app sarà pronta ad accettare Apple Pay.
![](https://b.stripecdn.com/docs-statics-srv/assets/xcode.a701d4c1922d19985e9c614a6f105bf1.png)

Abilita la funzionalità Apple Pay in Xcode

### Aggiungi Apple Pay

#### Pagamento una tantum

Per aggiungere Apple Pay a PaymentSheet, imposta [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) dopo l’inizializzazione di `PaymentSheet.Configuration` con il tuo ID esercente Apple e il [codice Paese della tua attività](https://dashboard.stripe.com/settings/account).

#### iOS (Swift)

```swift
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(
  merchantId: "merchant.com.your_app_name",
  merchantCountryCode: "US"
)
```

#### Pagamenti ricorrenti

Per aggiungere Apple Pay a PaymentSheet, imposta [applePay](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:6Stripe12PaymentSheetC13ConfigurationV8applePayAC05ApplefD0VSgvp) dopo l’inizializzazione di `PaymentSheet.Configuration` con il tuo ID esercente Apple e il [codice Paese della tua attività](https://dashboard.stripe.com/settings/account).

Secondo le [linee guida di Apple](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Supporting-subscriptions) per i pagamenti ricorrenti, devi impostare anche altri attributi in `PKPaymentRequest`. Aggiungi un gestore in [ApplePayConfiguration.paymentRequestHandlers](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/paymentrequesthandler) per configurare [PKPaymentRequest.paymentSummaryItems](https://developer.apple.com/documentation/passkit/pkpaymentrequest/1619231-paymentsummaryitems) con l’importo che intendi addebitare (ad esempio, 9,95 USD al mese).

Puoi anche adottare i [token dell’esercente](https://developer.apple.com/apple-pay/merchant-tokens/) impostando le proprietà `recurringPaymentRequest` o `automaticReloadPaymentRequest` su `PKPaymentRequest`.

Per ulteriori informazioni su come utilizzare i pagamenti ricorrenti con Apple Pay, consulta [la documentazione di PassKit di Apple](https://developer.apple.com/documentation/passkit/pkpaymentrequest).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    paymentRequestHandler: { request in
        // PKRecurringPaymentSummaryItem is available on iOS 15 or later
        if #available(iOS 15.0, *) {
            let billing = PKRecurringPaymentSummaryItem(label: "My Subscription", amount: NSDecimalNumber(string: "59.99"))

            // Payment starts today
            billing.startDate = Date()

            // Payment ends in one year
            billing.endDate = Date().addingTimeInterval(60 * 60 * 24 * 365)

            // Pay once a month.
            billing.intervalUnit = .month
            billing.intervalCount = 1

            // recurringPaymentRequest is only available on iOS 16 or later
            if #available(iOS 16.0, *) {
                request.recurringPaymentRequest = PKRecurringPaymentRequest(paymentDescription: "Recurring",
                                                                            regularBilling: billing,
                                                                            managementURL: URL(string: "https://my-backend.example.com/customer-portal")!)
                request.recurringPaymentRequest?.billingAgreement = "You'll be billed $59.99 every month for the next 12 months. To cancel at any time, go to Account and click 'Cancel Membership.'"
            }
            request.paymentSummaryItems = [billing]
            request.currencyCode = "USD"
        } else {
            // On older iOS versions, set alternative summary items.
            request.paymentSummaryItems = [PKPaymentSummaryItem(label: "Monthly plan starting July 1, 2022", amount: NSDecimalNumber(string: "59.99"), type: .final)]
        }
        return request
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                                merchantCountryCode: "US",
                                customHandlers: customHandlers)
```

### Monitoraggio degli ordini

Per aggiungere informazioni sulla [tracciabilità degli ordini](https://developer.apple.com/design/human-interface-guidelines/technologies/wallet/designing-order-tracking) in iOS 16 o versioni successive, configura un [authorizationResultHandler](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/applepayconfiguration/handlers/authorizationresulthandler) nel tuo `PaymentSheet.ApplePayConfiguration.Handlers`. Stripe chiama la tua implementazione dopo che il pagamento è stato completato, ma prima che iOS chiuda il foglio di Apple Pay.

Nell’implementazione dell’`authorizationResultHandler`, recupera i dettagli dell’ordine completato dal server. Aggiungi i dettagli al [PKPaymentAuthorizationResult](https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult) fornito e restituisci il risultato modificato.

Per ulteriori informazioni sul monitoraggio degli ordini, consulta la [Documentazione sugli ordini in Apple Wallet](https://developer.apple.com/documentation/walletorders).

#### iOS (Swift)

```swift
let customHandlers = PaymentSheet.ApplePayConfiguration.Handlers(
    authorizationResultHandler: { result in
      do {
        // Fetch the order details from your service
        let myOrderDetails = try await MyAPIClient.shared.fetchOrderDetails(orderID: orderID)
        result.orderDetails = PKPaymentOrderDetails(
          orderTypeIdentifier: myOrderDetails.orderTypeIdentifier, // "com.myapp.order"
          orderIdentifier: myOrderDetails.orderIdentifier, // "ABC123-AAAA-1111"
          webServiceURL: myOrderDetails.webServiceURL, // "https://my-backend.example.com/apple-order-tracking-backend"
          authenticationToken: myOrderDetails.authenticationToken) // "abc123"
        // Return your modified PKPaymentAuthorizationResult
        return result
      } catch {
        return PKPaymentAuthorizationResult(status: .failure, errors: [error])
      }
    }
)
var configuration = PaymentSheet.Configuration()
configuration.applePay = .init(merchantId: "merchant.com.your_app_name",
                               merchantCountryCode: "US",
                               customHandlers: customHandlers)
```

## Abilitare la scansione delle carte

Per abilitare il supporto alla scansione delle carte per iOS, imposta `NSCameraUsageDescription` (**Privacy - Descrizione dell’utilizzo della fotocamera**) nel file `Info.plist` della tua applicazione e fornisci un motivo per l’accesso alla fotocamera (ad esempio, “Per scansionare le carte”).

## Optional: Abilita i pagamenti ACH

Per abilitare i pagamenti con addebito ACH, includi `StripeFinancialConnections` come dipendenza per la tua app.

L’[SDK per iOS di Stripe](https://github.com/stripe/stripe-ios) è open source, [completamente documentato](https://stripe.dev/stripe-ios/index.html) e compatibile con le app che supportano iOS 13 o versioni successive.

#### Swift Package Manager

Per installare l’SDK, segui questi passaggi:

1. In Xcode, seleziona **File** > **Aggiungi dipendenze pacchetto…** e inserisci `https://github.com/stripe/stripe-ios-spm` come URL repository.
2. Seleziona il numero dell’ultima versione dalla nostra [pagina delle release](https://github.com/stripe/stripe-ios/releases).
3. Aggiungi il prodotto **StripeFinancialConnections** al [target della tua app](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app).

#### Carthage

1. Se non l’hai ancora fatto, installa la versione più recente di [Carthage](https://github.com/Carthage/Carthage#installing-carthage).
2. Aggiungi questa riga al tuo `Cartfile`:
   ```cartfile
   github "stripe/stripe-ios"
   ```
3. Segui le [istruzioni per l’installazione di Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Assicurati di integrare tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking).
4. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, esegui il seguente comando:
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### Framework manuale

1. Vai alla [pagina delle versioni di GitHub](https://github.com/stripe/stripe-ios/releases/latest) e scarica e decomprimi **Stripe.xcframework.zip**.
2. Trascina **StripeFinancialConnections.xcframework** nella sezione **Embedded Binaries** (File binari incorporati) delle impostazioni **General** (Generali) nel tuo progetto Xcode. Assicurati che sia selezionato **Copy items if needed** (Copia elementi se necessario).
3. Ripeti il passaggio 2 per tutti i framework necessari elencati [qui](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking).
4. In futuro, per eseguire l’aggiornamento alla versione più recente del nostro SDK, ripeti i passaggi 1-3.

> Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Versioni](https://github.com/stripe/stripe-ios/releases) su GitHub. Per ricevere notifiche quando viene pubblicata una nuova versione, [guarda le versioni](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository) del repository.

## Optional: Personalizzare la scheda

Tutte le personalizzazioni vengono configurate utilizzando l’oggetto [PaymentSheet.Configuration](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html).

### Aspetto

Personalizza i colori, i caratteri e molto altro ancora in base all’aspetto della tua app utilizzando l’[API Appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios).

### Layout del metodo di pagamento

Configura il layout dei metodi di pagamento nel foglio utilizzando [paymentMethodLayout](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/paymentmethodlayout). Puoi visualizzarli orizzontalmente, verticalmente o lasciare che Stripe ne ottimizzi il layout automaticamente.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-mpe-payment-method-layouts.9d0513e2fcec5660378ba1824d952054.png)

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.paymentMethodLayout = .automatic
```

### Acquisire gli indirizzi degli utenti

Acquisisci gli indirizzi di spedizione o fatturazione locali e internazionali dai tuoi clienti utilizzando il componente [Address Element](https://docs.stripe.com/elements/address-element.md?platform=ios).

### Nome visualizzato dell’esercente

Specifica un nome dell’attività per il cliente impostando [merchantDisplayName](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV19merchantDisplayNameSSvp). Per impostazione predefinita, viene utilizzato il nome della tua app.

#### Swift

```swift
var configuration = PaymentSheet.Configuration()
configuration.merchantDisplayName = "My app, Inc."
```

### Modalità scura

Il `PaymentSheet` si adatta automaticamente alle impostazioni di visualizzazione del sistema dell’utente (modalità chiara o scura). Se la tua app non supporta la modalità scura, puoi impostare lo [stile](https://stripe.dev/stripe-ios/stripe-paymentsheet/Classes/PaymentSheet/Configuration.html#/s:18StripePaymentSheet0bC0C13ConfigurationV5styleAC18UserInterfaceStyleOvp) sulla modalità `alwaysLight` o `alwaysDark`.

```swift
var configuration = PaymentSheet.Configuration()
configuration.style = .alwaysLight
```

### Dettagli di addebito predefiniti

Per impostare i valori predefiniti per i dettagli di addebito raccolti nella scheda di pagamento, configura la proprietà `defaultBillingDetails`. `PaymentSheet` precompila i campi della scheda con i valori che fornisci.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"
```

### Raccolta dei dati per gli addebiti

Usa `billingDetailsCollectionConfiguration` per specificare come vuoi raccogliere i dati di addebito in nel payment sheet.

Puoi acquisire il nome, l’indirizzo email, il numero di telefono e l’indirizzo del cliente.

La raccolta dell’indirizzo completo include il completamento automatico fornito da Stripe per i Paesi supportati, senza necessità di configurazioni aggiuntive.

> Utilizzando il completamento automatico, accetti di rispettare la [Politica sull’uso accettabile di Google Maps Platform](https://cloud.google.com/maps-platform/terms/aup). In caso di violazione di queste norme, Stripe potrebbe disabilitare il completamento automatico o adottare altre misure necessarie.

Se vuoi raccogliere solo i dati di addebito richiesti dal metodo di pagamento, imposta `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` su true. In tal caso, `configuration.defaultBillingDetails` vengono impostati come [dati di addebito](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details) del metodo di pagamento.

Se desideri raccogliere ulteriori dati di addebito che non sono necessariamente richiesti dal metodo di pagamento, imposta `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` su false. In tal caso, i dati di addebito raccolti tramite l’interfaccia utente vengono impostati come dati di addebito del metodo di pagamento.

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true
```

> Rivolgiti al tuo consulente legale per sapere quali sono le leggi applicabili alla raccolta di informazioni. Richiedi i numeri di telefono solo se necessari per la transazione.

## Optional: Completare il pagamento nell'interfaccia utente

Puoi visualizzare il Payment Sheet solo per raccogliere i dati relativi alla modalità di pagamento e chiamare una modalità `confirm` in un secondo momento per completare il pagamento nell’interfaccia utente dell’app. Questa opzione è utile se disponi di un pulsante personalizzato per l’acquisto o se occorrono passaggi aggiuntivi dopo che hai acquisito i dati di pagamento.
![](https://b.stripecdn.com/docs-statics-srv/assets/ios-multi-step.cd631ea4f1cd8cf3f39b6b9e1e92b6c5.png)

Completare il pagamento nell’interfaccia utente dell’app

#### UIKit

I seguenti passaggi ti illustrano come completare il pagamento nell’interfaccia utente della tua app. Consulta il nostro esempio di integrazione su [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleCustomCheckoutViewController.swift).

1. Innanzitutto, inizializza [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) invece di `PaymentSheet` e aggiorna la tua interfaccia utente con la sua proprietà `paymentOption`. Questa proprietà contiene un’immagine e un’etichetta che rappresentano la modalità di pagamento predefinita, inizialmente selezionata dal cliente.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Update your UI using paymentSheetFlowController.paymentOption
  }
}
```

1. Poi chiama `presentPaymentOptions` per raccogliere i dati relativi al pagamento. Al termine, aggiorna di nuovo la tua interfaccia utente con la proprietà `paymentOption`.

```swift
paymentSheetFlowController.presentPaymentOptions(from: self) {
  // Update your UI using paymentSheetFlowController.paymentOption
}
```

1. Infine, chiama `confirm`.

```swift
paymentSheetFlowController.confirm(from: self) { paymentResult in
  // MARK: Handle the payment result
  switch paymentResult {
  case .completed:
    print("Payment complete!")
  case .canceled:
    print("Canceled!")
  case .failed(let error):
    print(error)
  }
}
```

#### SwiftUI

I seguenti passaggi ti illustrano come completare il pagamento nell’interfaccia utente della tua app. Consulta il nostro esempio di integrazione su [GitHub](https://github.com/stripe/stripe-ios/blob/master/Example/PaymentSheet%20Example/PaymentSheet%20Example/ExampleSwiftUICustomPaymentFlow.swift).

1. Innanzitutto, inizializza [PaymentSheet.FlowController](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller) invece di `PaymentSheet`. La sua proprietà `paymentOption` contiene un’immagine e un’etichetta che rappresentano la modalità di pagamento attualmente selezionata dal cliente, che puoi utilizzare nella tua interfaccia utente.

```swift
PaymentSheet.FlowController.create(paymentIntentClientSecret: paymentIntentClientSecret, configuration: configuration) { [weak self] result in
  switch result {
  case .failure(let error):
    print(error)
  case .success(let paymentSheetFlowController):
    self?.paymentSheetFlowController = paymentSheetFlowController
    // Use the paymentSheetFlowController.paymentOption properties in your UI
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  }
}
```

1. Utilizza [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) per includere il pulsante che determina l’apertura della scheda per raccogliere i dati di pagamento. Quando `PaymentSheet.FlowController` chiama l’argomento `onSheetDismissed`, `paymentOption` per l’istanza `PaymentSheet.FlowController` indica il metodo di pagamento selezionato al momento.

```swift
PaymentSheet.FlowController.PaymentOptionsButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onSheetDismissed: {
    myPaymentMethodLabel = paymentSheetFlowController.paymentOption?.label ?? "Select a payment method"
    myPaymentMethodImage = paymentSheetFlowController.paymentOption?.image ?? UIImage(systemName: "square.and.pencil")!
  },
  content: {
    /* An example button */
    HStack {
      Text(myPaymentMethodLabel)
      Image(uiImage: myPaymentMethodImage)
    }
  }
)
```

1. Utilizza [PaymentSheet.FlowController.PaymentOptionsButton](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/flowcontroller/paymentoptionsbutton) per includere il pulsante che conferma il pagamento.

```swift
PaymentSheet.FlowController.ConfirmButton(
  paymentSheetFlowController: paymentSheetFlowController,
  onCompletion: { result in
    // MARK: Handle the payment result
    switch result {
    case .completed:
      print("Payment complete!")
    case .canceled:
      print("Canceled!")
    case .failed(let error):
      print(error)
    }
  },
  content: {
    /* An example button */
    Text("Pay")
  }
)
```

Impostare `allowsDelayedPaymentMethods` su true consente di utilizzare i metodi di pagamento con [notifica differita](https://docs.stripe.com/payments/payment-methods.md#payment-notification) come i conti bancari degli Stati Uniti. Per questi metodi di pagamento, lo stato finale del pagamento non è noto al completamento di `PaymentSheet`, in quanto va a buon fine o meno in un secondo momento. Se supporti questi tipi di metodi di pagamento, informa il cliente che il suo ordine è confermato e procedi all’evasione (ad esempio alla spedizione del prodotto), spedisci il suo prodotto) solo quando avrai ricevuto il pagamento.

## Optional: Abilita la nuova raccolta del CVC al momento della conferma

Le seguenti istruzioni per raccogliere nuovamente il CVC di una carta salvata durante la conferma del PaymentIntent presuppongono che l’integrazione includa quanto segue:

- Creare i PaymentIntent prima di raccogliere i dati di pagamento

### Aggiornare i parametri della creazione dell’intento

Per raccogliere nuovamente il CVC alla conferma del pagamento, includi `require_cvc_recollection` durante la creazione del PaymentIntent.

#### curl

```bash
# Create a Customer (use an existing Customer ID if this is a returning customer)
curl https://api.stripe.com/v1/customers \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

# Create an Ephemeral Key for the Customer
curl https://api.stripe.com/v1/ephemeral_keys \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-09-30.endive" \
  -H "Stripe-Account: 2026-09-30.endive" \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \

# Create a PaymentIntent
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_options[card][require_cvc_recollection]"=true \

  -d "automatic_payment_methods[enabled]"=true \
```