# 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();`. Agenti di programmazione: [installa la CLI di Stripe](https://docs.stripe.com/cli/install) utilizzando lo script di installazione per il tuo sistema operativo. Apri un nuovo terminale ed esegui `stripe sandbox create --help` per creare una sandbox Stripe anonima con chiavi API funzionanti. Non è necessario registrare 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 Android ![](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.471eaf89a760f5b6a757fd96b6bb9b60.png) Integra l’interfaccia utente per i pagamenti preintegrata di Stripe nella procedura di pagamento della tua app Android con la classe [PaymentSheet](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html). In alternativa, inizia dalla [guida rapida al codice](https://docs.stripe.com/payments/mobile/quickstart.md?platform=android) 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 Android di Stripe](https://github.com/stripe/stripe-android) è open source e [completamente documentato](https://stripe.dev/stripe-android/). Per installare l’SDK, aggiungi `stripe-android` al blocco `dependencies` del tuo file [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.26.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.26.0") } ``` > Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Releases](https://github.com/stripe/stripe-android/releases) su GitHub. Per ricevere una notifica quando viene pubblicata una nuova versione, [imposta il controllo delle versioni per il repository](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-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 <>: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" # Create a CustomerSession for the Customer curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -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 <>: \ -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 <>: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" # Create a CustomerSession for the Customer curl https://api.stripe.com/v1/customer_sessions \ -u <>: \ -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 <>: \ -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] Prima di visualizzare Payment Element per dispositivi mobili, la tua pagina di pagamento dovrebbe: - Mostrare i prodotti acquistati e l’importo totale - Raccogliere tutti i dati di spedizione richiesti utilizzando [Address Element](https://docs.stripe.com/elements/address-element.md?platform=android) - Includere un pulsante di pagamento per visualizzare l’interfaccia utente di Stripe #### Jetpack Componi [Inizializza](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-builder/index.html) un’istanza di `PaymentSheet` in `onCreate` dell’Attività di pagamento, specificando un metodo per gestire il risultato. ```kotlin import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import com.stripe.android.paymentsheet.PaymentSheet import com.stripe.android.paymentsheet.PaymentSheetResult @Composable fun App() { val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult).build() } } private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { // implemented in the next steps } ``` Quindi, recupera la chiave privata client del PaymentIntent, la chiave privata client Customer Session, l’ID cliente e la chiave pubblicabile dall’endpoint creato nel passaggio precedente. Imposta la chiave pubblicabile utilizzando `PaymentConfiguration` e memorizza le altre per usarle quando visualizzi l’istanza di PaymentSheet. ```kotlin import androidx.compose.runtime.Composable import androidx.compose.runtime.remember import androidx.compose.runtime.LaunchedEffect import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.setValue import androidx.compose.ui.platform.LocalContext import com.stripe.android.PaymentConfiguration import com.stripe.android.paymentsheet.PaymentSheet import com.stripe.android.paymentsheet.PaymentSheetResult @Composable fun App() { val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build() val context = LocalContext.current var customerConfig by remember { mutableStateOf(null) } varpaymentIntentClientSecret by remember { mutableStateOf(null) } LaunchedEffect(context) { // Make a request to your own server and retrieve payment configurations val networkResult = ... if (networkResult.isSuccess) { paymentIntentClientSecret = networkResult.paymentIntent customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession( id = networkResult.customer, clientSecret = networkResult.customerSessionClientSecret ) PaymentConfiguration.init(context, networkResult.publishableKey) } } } private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { // implemented in the next steps } ``` Quando il cliente tocca il pulsante di pagamento, chiama [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) per aprire la scheda di pagamento. Non appena il cliente completa il pagamento, la scheda si chiude e [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) viene chiamata con un [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html). ```kotlin import androidx.compose.material.Button import androidx.compose.material.Text import androidx.compose.runtime.Composable import androidx.compose.runtime.LaunchedEffect import androidx.compose.runtime.getValue import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember import androidx.compose.runtime.setValue import androidx.compose.ui.platform.LocalContext import com.stripe.android.PaymentConfiguration import com.stripe.android.paymentsheet.PaymentSheet import com.stripe.android.paymentsheet.PaymentSheetResult @Composable fun App() { val paymentSheet = remember { PaymentSheet.Builder(::onPaymentSheetResult) }.build() val context = LocalContext.current var customerConfig by remember { mutableStateOf(null) } var paymentIntentClientSecret by remember { mutableStateOf(null) } LaunchedEffect(context) { // Make a request to your own server and retrieve payment configurations val networkResult = ... if (networkResult.isSuccess) { paymentIntentClientSecret = networkResult.paymentIntent customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession( id = networkResult.customer, clientSecret = networkResult.customerSessionClientSecret ) PaymentConfiguration.init(context, networkResult.publishableKey) } } Button( onClick = { val currentConfig = customerConfig val currentClientSecret =paymentIntentClientSecret if (currentConfig != null && currentClientSecret != null) { presentPaymentSheet(paymentSheet, currentConfig, currentClientSecret) } } ) { Text("Checkout") } } private fun presentPaymentSheet( paymentSheet: PaymentSheet, customerConfig: PaymentSheet.CustomerConfiguration, paymentIntentClientSecret: String ) { paymentSheet.presentWithPaymentIntent( paymentIntentClientSecret, PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name") .customer(customerConfig) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. .allowsDelayedPaymentMethods(true) .build() ) } private fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { when(paymentSheetResult) { is PaymentSheetResult.Canceled -> { print("Canceled") } is PaymentSheetResult.Failed -> { print("Error: ${paymentSheetResult.error}") } is PaymentSheetResult.Completed -> { // Display for example, an order confirmation screen print("Completed") } } } ``` #### Viste (classiche) [Inizializza](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#-394860221%2FConstructors%2F2002900378) un’istanza di `PaymentSheet` in `onCreate` dell’Activity del pagamento, specificando un metodo per gestire il risultato. #### Kotlin ```kotlin import com.stripe.android.paymentsheet.PaymentSheet class CheckoutActivity : AppCompatActivity() { lateinit var paymentSheet: PaymentSheet override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this) } fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { // implemented in the next steps } } ``` Quindi, recupera la chiave privata client del PaymentIntent, la chiave privata client Customer Session, l’ID cliente e la chiave pubblicabile dall’endpoint creato nel passaggio precedente. Imposta la chiave pubblicabile utilizzando `PaymentConfiguration` e memorizza le altre per usarle quando visualizzi l’istanza di PaymentSheet. #### Kotlin ```kotlin import com.stripe.android.paymentsheet.PaymentSheet class CheckoutActivity : AppCompatActivity() { lateinit var paymentSheet: PaymentSheet lateinit var customerConfig: PaymentSheet.CustomerConfiguration lateinit varpaymentIntentClientSecret: String override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) paymentSheet = PaymentSheet.Builder(::onPaymentSheetResult).build(this) lifecycleScope.launch { // Make a request to your own server and retrieve payment configurations val networkResult = MyBackend.getPaymentConfig() if (networkResult.isSuccess) { paymentIntentClientSecret = networkResult.paymentIntent customerConfig = PaymentSheet.CustomerConfiguration.createWithCustomerSession( id = networkResult.customer, clientSecret = networkResult.customerSessionClientSecret ) PaymentConfiguration.init(context, networkResult.publishableKey) } } } fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { // implemented in the next steps } } ``` Quando il cliente tocca il pulsante di pagamento, chiama [presentWithPaymentIntent](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/index.html#1814490530%2FFunctions%2F2002900378) per aprire la scheda di pagamento. Non appena il cliente completa il pagamento, la scheda si chiude e [PaymentSheetResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html) viene chiamata con un [PaymentSheetResult](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result/index.html). #### Kotlin ```kotlin // ... class CheckoutActivity : AppCompatActivity() { lateinit var paymentSheet: PaymentSheet lateinit var customerConfig: PaymentSheet.CustomerConfiguration lateinit var paymentIntentClientSecret: String // ... fun presentPaymentSheet() { paymentSheet.presentWithPaymentIntent( paymentIntentClientSecret, PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name") .customer(customerConfig) // Set `allowsDelayedPaymentMethods` to true if your business handles // delayed notification payment methods like US bank accounts. .allowsDelayedPaymentMethods(true) .build() ) } fun onPaymentSheetResult(paymentSheetResult: PaymentSheetResult) { when(paymentSheetResult) { is PaymentSheetResult.Canceled -> { print("Canceled") } is PaymentSheetResult.Failed -> { print("Error: ${paymentSheetResult.error}") } is PaymentSheetResult.Completed -> { // Display for example, an order confirmation screen print("Completed") } } } } ``` 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. ## 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 PaymentIntent 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 durante l’inizializzazione di `PaymentSheet.Configuration`. #### Kotlin ```kotlin val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Example, Inc.") .defaultBillingDetails( PaymentSheet.BillingDetails( name = "Jenny Rosen", email = "jenny.rosen@example.com", phone = "888-888-8888" ) ) .build() ``` ### 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. #### Kotlin ```kotlin class MyActivity: Activity { fun onLogoutButtonClicked() { PaymentSheet.resetCustomer(this) // Other logout logic required by your app } } ``` ## Optional: Abilitare Google Pay ### Configura la tua integrazione Per usare Google Pay, prima di tutto abilita l’API di Google Pay aggiungendo quanto segue al tag `` del tuo **AndroidManifest.xml**: ```xml ... ``` Per ulteriori informazioni, consulta la pagina [Set up Google Pay API](https://developers.google.com/pay/api/android/guides/setup) (Configurazione dell’API di Google Pay) di Google Pay per Android. ### Aggiungi Google Pay Per aggiungere Google Pay alla tua integrazione, specifica una [PaymentSheet.GooglePayConfiguration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-google-pay-configuration/index.html) con il tuo ambiente Google Pay (produzione o test) e il [codice paese della tua azienda](https://dashboard.stripe.com/settings/account) all’inizializzazione di [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html). #### Kotlin ```kotlin val googlePayConfiguration = PaymentSheet.GooglePayConfiguration( environment = PaymentSheet.GooglePayConfiguration.Environment.Test, countryCode = "US", currencyCode = "USD" // Required for Setup Intents, optional for Payment Intents ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "My merchant name") .googlePay(googlePayConfiguration) .build() ``` ### Testare Google Pay Google consente di effettuare pagamenti di test tramite la sua [suite di carte di test](https://developers.google.com/pay/api/android/guides/resources/test-card-suite). La suite di test supporta l’utilizzo di [carte di test](https://docs.stripe.com/testing.md) Stripe. Devi testare Google Pay utilizzando un dispositivo Android fisico anziché un dispositivo simulato in un Paese in cui è supportato Google Pay. Accedi a un account Google sul tuo dispositivo di test con una carta reale salvata su Google Wallet. ## Optional: Abilitare la scansione delle carte Per abilitare l’assistenza alla scansione delle carte, [richiedi l’accesso di produzione](https://developers.google.com/pay/api/android/guides/test-and-deploy/request-prod-access) all’API Google Pay dalla [Console Google Pay & Wallet](https://pay.google.com/business/console?utm_source=devsite&utm_medium=devsite&utm_campaign=devsite). - Se hai abilitato Google Pay, la funzione di scansione delle carte è automaticamente disponibile nella nostra interfaccia utente sui dispositivi idonei. Per ulteriori informazioni sui dispositivi idonei, consulta le [limitazioni dell’API Google Pay](https://developers.google.com/android/reference/com/google/android/gms/wallet/PaymentsClient#getPaymentCardRecognitionIntent%28com.google.android.gms.wallet.PaymentCardRecognitionIntentRequest%29). - **Importante:** la funzione di scansione della carta è disponibile solo nelle build firmate con la stessa chiave di firma registrata nella [Console Google Pay & Wallet](https://pay.google.com/business/console). Le build di test o debug che utilizzano chiavi di firma diverse (ad esempio, le build distribuite tramite Firebase App Tester) non mostreranno l’opzione **Scansiona carta**. Per testare la scansione della carta nelle build pre-release, è necessario: - Firmare le build di test con la tua chiave di firma di produzione - Aggiungere l’impronta della chiave di firma di test alla Console Google Pay e Wallet Se la tua app non supporta Google Pay, puoi utilizzare lo scanner di carte Stripe. > Lo scanner di carte Stripe è in anteprima pubblica. Per abilitare il supporto alla scansione delle carte, aggiungi `stripecardscan` al blocco delle `dependencies` del file [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Groovy ```groovy implementation 'com.stripe:stripecardscan:23.26.0' ``` ## Optional: Abilita i pagamenti ACH Per abilitare i pagamenti con addebito ACH, includi Financial Connections come dipendenza per la tua app. L’[SDK per Android di Stripe](https://github.com/stripe/stripe-android) è open source e [completamente documentato](https://stripe.dev/stripe-android/). Per installare l’SDK, aggiungi `financial-connections` al blocco `dependencies` del tuo file [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Financial Connections Android SDK implementation("com.stripe:financial-connections:23.26.0") } ``` > Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Releases](https://github.com/stripe/stripe-android/releases) su GitHub. Per ricevere una notifica quando viene pubblicata una nuova versione, [imposta il controllo delle versioni per il repository](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). ## Optional: Personalizzare la scheda Tutte le personalizzazioni vengono configurate utilizzando l’oggetto [PaymentSheet.Configuration](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html). ### Aspetto Personalizza i colori, i caratteri e molto altro in base all’aspetto della tua app utilizzando l’[API Appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android). ### Layout del metodo di pagamento Configura il layout dei metodi di pagamento nel foglio utilizzando [paymentMethodLayout](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/-builder/index.html#2123253356%2FFunctions%2F2002900378). Puoi visualizzarli orizzontalmente, verticalmente o lasciare che Stripe ne ottimizzi il layout automaticamente. ![](https://b.stripecdn.com/docs-statics-srv/assets/android-mpe-payment-method-layouts.3bcfe828ceaad1a94e0572a22d91733f.png) #### Kotlin ```kotlin PaymentSheet.Configuration.Builder("Example, Inc.") .paymentMethodLayout(PaymentSheet.PaymentMethodLayout.Automatic) .build() ``` ### 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=android). ### Nome attività da visualizzare Specifica un nome dell’attività per il cliente impostando [merchantDisplayName](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html#-191101533%2FProperties%2F2002900378). Per impostazione predefinita, viene utilizzato il nome della tua app. #### Kotlin ```kotlin PaymentSheet.Configuration.Builder( merchantDisplayName = "My app, Inc." ).build() ``` ### Modalità scura Per impostazione predefinita, il `PaymentSheet` si adatta automaticamente alle impostazioni di visualizzazione del sistema dell’utente (modalità chiara o scura). Puoi modificare questa impostazione configurando la modalità chiara o scura nella tua app: #### Kotlin ```kotlin // force dark AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES) // force light AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO) ``` ### 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. #### Kotlin ```kotlin val address = PaymentSheet.Address(country = "US") val billingDetails = PaymentSheet.BillingDetails( address = address, email = "foo@bar.com" ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .build() ``` ### Configura la raccolta dei dati di fatturazione Usa `BillingDetailsCollectionConfiguration` per specificare come vuoi raccogliere i dettagli di addebito in PaymentSheet. 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 associare i dati di fatturazione predefiniti all’oggetto PaymentMethod anche quando tali campi non sono raccolti nell’interfaccia utente, imposta `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` su `true`. #### Kotlin ```kotlin val billingDetails = PaymentSheet.BillingDetails( email = "foo@bar.com" ) val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration( attachDefaultsToPaymentMethod = true, name = BillingDetailsCollectionConfiguration.CollectionMode.Always, email = BillingDetailsCollectionConfiguration.CollectionMode.Never, address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full, ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration) .build() ``` > 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 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 la raccolta dei dati di pagamento. ![](https://b.stripecdn.com/docs-statics-srv/assets/android-multi-step.84d8a0a44b1baa596bda491322b6d9fd.png) > Un esempio di integrazione è [disponibile sul nostro GitHub](https://github.com/stripe/stripe-android/blob/master/paymentsheet-example/src/main/java/com/stripe/android/paymentsheet/example/samples/ui/paymentsheet/custom_flow/CustomFlowActivity.kt). 1. Innanzitutto, inizializza [PaymentSheet.FlowController](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html) invece di `PaymentSheet` usando uno dei metodi di [Builder](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/-builder/index.html). #### Android (Kotlin) ```kotlin class CheckoutActivity : AppCompatActivity() { private lateinit var flowController: PaymentSheet.FlowController override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val flowController = PaymentSheet.FlowController.Builder( resultCallback = ::onPaymentSheetResult, paymentOptionResultCallback = ::onPaymentOption, ).build(this) } } ``` 1. Successivamente, chiama `configureWithPaymentIntent` con le chiavi degli oggetti Stripe recuperate dal back-end e aggiorna l’interfaccia utente nella funzione di callback utilizzando [getPaymentOption()](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-2091462043%2FFunctions%2F2002900378). Questa contiene un’immagine e un’etichetta che rappresentano il metodo di pagamento attualmente selezionato dal cliente. #### Android (Kotlin) ```kotlin flowController.configureWithPaymentIntent( paymentIntentClientSecret = paymentIntentClientSecret, configuration = PaymentSheet.Configuration.Builder("Example, Inc.") .customer(PaymentSheet.CustomerConfiguration( id = customerId, ephemeralKeySecret = ephemeralKeySecret )) .build() ) { isReady, error -> if (isReady) { // Update your UI using `flowController.getPaymentOption()` } else { // handle FlowController configuration failure } } ``` 1. Poi chiama [presentPaymentOptions](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#449924733%2FFunctions%2F2002900378) per raccogliere i dati del pagamento. Quando il cliente termina l’operazione, la scheda si chiude e viene chiamata la [paymentOptionCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-option-callback/index.html) specificata in precedenza in `create`. Esegui questo metodo per aggiornare la tua interfaccia utente con la `paymentOption` restituita. #### Android (Kotlin) ```kotlin // ... flowController.presentPaymentOptions() // ... private fun onPaymentOption(paymentOptionResult: PaymentOptionResult) { val paymentOption = paymentOptionResult.paymentOption if (paymentOption != null) { paymentMethodButton.text = paymentOption.label paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds( paymentOption.drawableResourceId, 0, 0, 0 ) } else { paymentMethodButton.text = "Select" paymentMethodButton.setCompoundDrawablesRelativeWithIntrinsicBounds( null, null, null, null ) } } ``` 1. Infine, chiama [confirm](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-flow-controller/index.html#-479056656%2FFunctions%2F2002900378) per completare il pagamento. Quando il cliente termina l’operazione, la scheda si chiude e viene chiamata la [paymentResultCallback](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet-result-callback/index.html#237248767%2FFunctions%2F2002900378) specificata in precedenza in `create`. #### Android (Kotlin) ```kotlin // ... flowController.confirmPayment() // ... private fun onPaymentSheetResult( paymentSheetResult: PaymentSheetResult ) { when (paymentSheetResult) { is PaymentSheetResult.Canceled -> { // Payment canceled } is PaymentSheetResult.Failed -> { // Payment Failed. See logcat for details or inspect paymentSheetResult.error } is PaymentSheetResult.Completed -> { // Payment Complete } } } ``` 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 <>: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" # Create an Ephemeral Key for the Customer curl https://api.stripe.com/v1/ephemeral_keys \ -u <>: \ -H "Stripe-Version: 2026-10-28.endive" \ -H "Stripe-Account: 2026-10-28.endive" \ -X "POST" \ -d "customer"="{{CUSTOMER_ID}}" \ # Create a PaymentIntent curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -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 \ ```