> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Stripe
> Accetta pagamenti nel tuo progetto Macaly
L'integrazione Stripe di Macaly ti permette di accettare pagamenti una tantum e ricorrenti (abbonamenti) direttamente nel tuo progetto. Un ambiente di test completamente funzionante viene predisposto automaticamente, così puoi iniziare a creare e testare senza un account Stripe. Quando sei pronto ad andare online, colleghi il tuo account Stripe e passi alla modalità Live.
Disponibile nei [**piani Pro e Agenzie**](/docs/it/welcome/pricing)
## Aggiungere i pagamenti al tuo progetto
Descrivi all'agente nella chat le tue esigenze di pagamento. Per esempio:
```
Voglio vendere online i miei prodotti per la cura della pelle. Mi serve
un negozio con catalogo e checkout così i clienti possono pagare con carta.
```
```
Ho scritto un e-book e voglio venderlo a 19 $. Crea una pagina
in cui le persone possono pagarlo e scaricarlo subito.
```
```
Sto lanciando un corso di yoga online mensile a 29 $ al mese. Crea una
landing page in cui gli iscritti possono registrarsi e attivare l'abbonamento.
```
L'agente crea il tuo progetto con un flusso di pagamento completo e predispone in background un ambiente di test Stripe.
Per aggiungere i pagamenti puoi anche partire dalla scheda **Pagamenti** nella barra di navigazione in alto.
Puoi iniziare a testare subito usando la carta di test mostrata nella scheda Pagamenti:
| Campo | Valore |
| - | - |
| Numero della carta | 4242 4242 4242 4242 |
| Scadenza | Qualsiasi data futura (es. 01/30) |
| CVC | Qualsiasi numero di 3 cifre (es. 111) |
| CAP | Qualsiasi valore (es. 11000) |
Vai al tuo progetto, completa un acquisto di prova e verifica l'esperienza di checkout.
Puoi anche testare scenari di errore come carte rifiutate o dati di pagamento non validi usando le carte di test dedicate di Stripe. Consulta la [documentazione di test di Stripe](https://docs.stripe.com/testing#declined-payments) per l'elenco completo dei numeri di carta di test e degli errori che simulano.
## Attivare la tua area di test sicura
Quando Macaly crea il tuo ambiente di test, predispone una sandbox Stripe. Questa sandbox funziona subito e ti permette di testare i pagamenti, ma non è collegata ad alcun account Stripe. Le sandbox non richieste scadono dopo 60 giorni.
Richiedere la sandbox la collega al tuo account Stripe. Una volta richiesta, la sandbox è tua e puoi gestirla direttamente nella Stripe Dashboard.
Puoi richiedere la sandbox in due modi: dalla scheda **Pagamenti** nel tuo progetto oppure tramite l'email che Stripe ti invia dopo la creazione dell'ambiente di test.
Richiederla è anche il primo passo verso l'accettazione di pagamenti reali. Per andare online dovrai richiedere la sandbox, far verificare la tua attività da Stripe e inserire le tue chiavi API Live.
Apri la scheda **Pagamenti** nel tuo progetto. Sotto "Attiva la tua area di test sicura" vedrai il pulsante **Richiedi la tua sandbox Stripe**.
Stripe si apre in una nuova scheda con la pagina **Claim your sandbox**.
Se hai già un account Stripe, selezionalo dall'elenco. Altrimenti fai clic su **+ Create new account** per crearne uno gratuitamente.
Fai clic su **Continue** per proseguire.
Stripe ti chiederà alcune informazioni di base:
1. **Nome e sede dell'attività.** Inserisci il nome della tua attività e seleziona il paese. Fai clic su **Continue**.
2. **Sito web e descrizione dell'attività.** Indica la URL del tuo sito e una breve descrizione dei tuoi prodotti o servizi. Questo passaggio si può saltare facendo clic su **Skip**.
3. **Uso previsto di Stripe.** Seleziona i tipi di pagamento rilevanti per la tua attività (es. pagamenti una tantum o ricorrenti). Anche questo passaggio si può saltare.
Nella schermata finale Stripe presenta un riepilogo dei passaggi successivi: completare la configurazione, passare alla modalità Live e iniziare ad accettare pagamenti. Fai clic su **Go to sandbox** per concludere.
Torna su Macaly. La scheda Pagamenti dovrebbe ora mostrare **I pagamenti sono in modalità Test** in arancione, a conferma che la richiesta è andata a buon fine.
Gli aggiornamenti di stato possono richiedere qualche istante per sincronizzarsi. Se il pulsante di richiesta è ancora visibile, ricarica la pagina.
## Passare alla modalità Live
Quando sei pronto ad accettare pagamenti reali, devi attivare il tuo account Stripe e collegare le tue chiavi API Live a Macaly.
Sei responsabile di tutti gli obblighi legali e fiscali relativi ai pagamenti che accetti attraverso il tuo progetto. Consulta un consulente fiscale se hai dubbi sui tuoi obblighi.
### Attiva il tuo account Stripe
Prima di poter accedere alle chiavi API Live, Stripe richiede la verifica della tua attività. È un processo di onboarding standard che avviene interamente sul lato Stripe.
Vai su [dashboard.stripe.com](https://dashboard.stripe.com) e accedi con l'account che hai usato per richiedere la sandbox.
Stripe ti inviterà a completare la configurazione dell'account. Di solito include:
* Dati dell'attività (denominazione legale, indirizzo, tipo di attività)
* Verifica dell'identità personale
* Conto bancario o dati di pagamento per ricevere i fondi
Segui la guida alla configurazione di Stripe finché tutti i passaggi non risultano completati.
Stripe controlla le tue informazioni e attiva il tuo account. Di solito è immediato, ma può richiedere fino a qualche giorno a seconda del paese e del tipo di attività.
Una volta verificato, il tuo account è attivo e le tue chiavi API Live diventano disponibili nella Dashboard.
Puoi continuare a creare e testare il tuo progetto in modalità test mentre attendi che Stripe verifichi il tuo account.
### Inserisci le tue chiavi API Live
Una volta verificato il tuo account Stripe, copia le tue chiavi Live in Macaly.
Nella Stripe Dashboard, le tue chiavi API sono visualizzate nella scheda **API keys** sul lato destro della homepage. Le trovi anche in **Developers → API keys** in fondo alla barra laterale.
Vedrai due chiavi:
* **Publishable key** inizia con `pk_live_`.
* **Secret key** inizia con `sk_live_`.
Copia entrambe le chiavi.
La tua chiave segreta dà accesso completo al tuo account Stripe. Non condividerla mai e non incollarla nella chat.
Nella scheda **Pagamenti**, fai clic su **Aggiungi connessione Stripe**. Incolla ogni chiave nel campo corrispondente e fai clic su **Salva le chiavi API**. Assicurati di usare le chiavi Live (che iniziano con `pk_live_` e `sk_live_`) e non quelle di test (`pk_test_` e `sk_test_`).
Fai clic su **Passa alla modalità Live**. Macaly riconfigura il tuo progetto per usare il tuo account Stripe Live. Lo stato si aggiorna su **I pagamenti sono in modalità Live** in verde.
Pubblica il tuo progetto per applicare le modifiche. I pagamenti Live vengono elaborati solo sul sito pubblicato, non nell'anteprima.
## Gestire la tua integrazione
Tutte le impostazioni dei pagamenti sono accessibili dalla scheda **Pagamenti**:
* **Apri Stripe** apre la Stripe Dashboard, dove puoi controllare le transazioni, emettere rimborsi e seguire i pagamenti in uscita.
* **Passa alla modalità Live / Passa alla modalità test** ti permette di alternare gli ambienti in qualsiasi momento senza toccare il codice del tuo progetto.
* **Gestisci connessione Stripe** ti permette di aggiornare le tue chiavi API Live dopo la configurazione iniziale.
* **Testa i pagamenti** mostra i dati della carta di test come riferimento mentre sei in modalità test.
## Risoluzione dei problemi
Una sandbox è un ambiente di test temporaneo che Macaly crea per te. Ha le proprie chiavi API di test e ti permette di simulare i pagamenti senza toccare denaro reale. **Non** è il tuo account Stripe. Quando richiedi la sandbox, la colleghi al tuo vero account Stripe. Finché non la richiedi, la sandbox è anonima e scade dopo 60 giorni.
Assicurati di usare il numero della carta di test **4242 4242 4242 4242** con una data di scadenza futura qualsiasi, un CVC di 3 cifre qualsiasi e un CAP qualsiasi. Se il problema persiste, controlla nella chat i dettagli dell'errore oppure chiedi all'agente di analizzare il flusso di pagamento.
La **modalità Test** usa l'ambiente sandbox con chiavi di test. Tutti i pagamenti sono simulati e non è coinvolto denaro reale. La **modalità Live** usa il tuo account Stripe verificato con chiavi Live. Viene addebitato denaro reale che viene versato sul tuo conto bancario. Puoi passare da una modalità all'altra in qualsiasi momento nella scheda Pagamenti. Cambiare modalità non tocca il codice del tuo progetto, ma solo quali chiavi Stripe sono attive.
Richiedere la sandbox e verificare il tuo account Stripe sono due passaggi distinti. La richiesta collega la sandbox al tuo account, ma devi comunque completare la verifica dell'attività su Stripe (identità, dati dell'attività, conto bancario) prima che le chiavi Live vengano generate. Apri la Stripe Dashboard e segui la guida alla configurazione per completare la verifica. Se vedi solo chiavi di test (che iniziano con `pk_test_` e `sk_test_`), il tuo account non è ancora stato verificato del tutto.
Verificare il tuo account Stripe non fa passare automaticamente Macaly alla modalità Live. Devi inserire manualmente le tue chiavi API Live nella scheda Pagamenti e poi fare clic su **Passa alla modalità Live**. Macaly ti mantiene in modalità test finché non passi esplicitamente all'altra.
Controlla tre cose in quest'ordine:
1. **Hai pubblicato il tuo progetto?** I pagamenti Live vengono elaborati solo sul sito pubblicato, non nell'anteprima.
2. **Le tue chiavi sono corrette?** Verifica di aver inserito la **Publishable key** (che inizia con `pk_live_`) e la **Secret key** (che inizia con `sk_live_`). Se hai incollato per errore le chiavi di test, fai clic su **Gestisci connessione Stripe** e aggiornale.
3. **Il tuo account Stripe è verificato del tutto?** Apri la Stripe Dashboard e controlla se ci sono passaggi in sospeso nella guida alla configurazione. Stripe potrebbe richiedere documenti aggiuntivi prima di elaborare pagamenti Live.
Le sandbox non richieste scadono dopo 60 giorni. Apri la scheda Pagamenti e fai clic su **Configura una nuova sandbox** per predisporre un nuovo ambiente. Il codice di pagamento esistente resta invariato. Se avevi già richiesto la sandbox e verificato il tuo account Stripe, dovrai reinserire le chiavi Live dopo aver predisposto la nuova sandbox.
## Buono a sapersi
* **Si applicano le commissioni di Stripe.** Macaly non addebita costi aggiuntivi sui pagamenti. A ogni transazione si applicano le commissioni di elaborazione standard di Stripe (vedi [stripe.com/pricing](https://stripe.com/pricing)).
* **Scadenza della sandbox.** Gli ambienti di test non richiesti scadono dopo 60 giorni. Se succede, apri la scheda Pagamenti e fai clic su **Configura una nuova sandbox** per predisporne uno nuovo.
* **I webhook sono gestiti automaticamente.** Macaly configura e mantiene tutti gli endpoint webhook. Non serve alcuna configurazione manuale nella Stripe Dashboard.
* **Gli ambienti di test e Live sono isolati.** Le transazioni di test non compaiono nel tuo account Stripe Live e non viene addebitato nulla di reale.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.