Chiavi API

Stripe autentica le richieste API utilizzando le chiavi API del tuo account. Se una richiesta non include una chiave valida, Stripe restituisce un errore di richiesta non valida. Se una richiesta include una chiave eliminata o scaduta, Stripe restituisce un errore di autenticazione.

Utilizza la Dashboard per sviluppatori per creare, rivelare, eliminare e ruotare le chiavi API. Puoi accedere alle chiavi API v1 nella scheda Chiavi API.

Tipi di chiave

Per impostazione predefinita, tutti gli account dispongono di un totale di quattro chiavi API:

Le chiavi private e le chiavi pubblicabili si trovano nella scheda Chiavi API nella Dashboard. Se non riesci a visualizzare le tue chiavi API, ti invitiamo a contattare il titolare del tuo account Stripe per richiedere di essere aggiunto al team con le autorizzazioni appropriate.

Se hai effettuato l’accesso a Stripe, la nostra documentazione inserisce esempi di codice con le tue chiavi API di prova. Solo tu puoi visualizzare questi valori. Se non hai effettuato l’accesso, i nostri esempi di codice includono chiavi API generate in modo casuale che puoi sostituire con le tue chiavi di prova. In alternativa, puoi effettuare l’accesso per visualizzare gli esempi di codice inseriti con le tue chiavi API di prova.

Esempi di chiavi API

La tabella di seguito mostra esempi, generati casualmente, di chiavi private e chiavi pubblicabili:

Proteggi le tue chiavi

Chiunque può utilizzare la tua chiave privata in modalità live per effettuare qualsiasi chiamata API per conto del tuo account, ad esempio per creare un addebito o eseguire un rimborso. Proteggi le tue chiavi seguendo queste best practice:

• Conserva le chiavi segrete in un archivio segreto o in variabili ambientali crittografate. Non conservare le chiavi nel codice sorgente o nei file di configurazione sottoposti a controllo di versione.
• Usa chiavi API con limitazioni anziché chiavi private quando possibile. Le chiavi con limitazioni limitano l’accesso solo alle risorse sull’API specifiche di cui la tua integrazione ha bisogno, riducendo l’impatto di una chiave compromessa.
• Limita le chiavi a indirizzi IP specifici in modo che possano essere utilizzate solo dai tuoi server noti.
• Sostituisci le chiavi quando i membri del team che hanno accesso alle chiavi lasciano la tua organizzazione.
• Non condividere le chiavi via email, chat o altri canali non crittografati.

Per ulteriori dettagli, consulta le best practice per la gestione delle chiavi API private.

Sandbox e modalità live a confronto

Tutte le richieste API di Stripe vengono eseguite in sandbox o in modalità live. Puoi utilizzare una sandbox per accedere ai dati di prova e la modalità live per accedere ai dati effettivi dell’account. Ciascuna modalità dispone di una propria serie di chiavi API e gli oggetti di una modalità non sono accessibili dall’altra. Ad esempio, un oggetto di prodotto sandbox non può far parte di un pagamento in modalità live

Passa alla modalità live

Quando è tutto pronto per accettare pagamenti reali, sostituisci le chiavi API della sandbox (test) con quelle della modalità live. Si tratta della stessa pagina delle chiavi nella Dashboard: puoi passare dalla modalità Test alla modalità Live utilizzando il pulsante nell’angolo in alto a destra della Dashboard per sviluppatori.

1. Nella Dashboard per sviluppatori, disabilita la modalità di test attivando l’interruttore della modalità nell’angolo in alto a destra. La pagina ora mostra le chiavi API in modalità live.
2. Copia la tua chiave pubblicabile in modalità live (inizia con pk_live_) e sostituisci la chiave pk_test_ nel codice lato client.
3. Rivela e copia la tua chiave privata in modalità live (inizia con sk_live_) e sostituisci la chiave sk_test_ nel codice lato server. Conservala in modo sicuro: puoi visualizzarla solo una volta.
4. Se utilizzi i webhook, aggiorna l’URL di ciascun endpoint webhook e copia la nuova chiave privata di firma dalla sezione Webhook della Dashboard.

Chiavi API dell’organizzazione

Se hai più account business Stripe in un’organizzazione, puoi configurare una singola chiave API a livello di organizzazione. Le chiavi API a livello di organizzazione offrono le seguenti funzionalità:

• Accesso a qualsiasi account: utilizza le chiavi API dell’organizzazione per accedere alle risorse di qualsiasi account all’interno dell’organizzazione.

• Autorizzazioni granulari: limita le chiavi API dell’organizzazione per concedere l’autorizzazione di lettura o scrittura solo a risorse specifiche.
• Gestione centralizzata: crea e gestisci le chiavi API dell’organizzazione nella scheda Chiavi API della Dashboard dell’organizzazione.

Comportamento

Le chiavi API dell’organizzazione si comportano in modo diverso dalle chiavi API a livello di account, ad esempio:

• Non dispongono di una chiave pubblicabile. Tratta tutte le chiavi API dell’organizzazione come chiavi private.
• Hanno tutti lo stesso prefisso sk_org, indipendentemente dai loro livelli di autorizzazione.
• Tutte le richieste API effettuate con una chiave API dell’organizzazione devono includere l’intestazione Stripe-Context per identificare l’account interessato.
• tutte le richieste API effettuate con una chiave API dell’organizzazione devono includere l’intestazione Stripe-Version per garantire coerenza e prevedibilità tra le integrazioni dell’organizzazione.

Utilizzare le chiavi API dell’organizzazione

Quando utilizzi una chiave API dell’organizzazione, devi anche rispettare le condizioni seguenti:

• Specifica una versione dell’API includendo un’intestazione Stripe-Version. Quando usi un SDK Stripe, l’SDK imposta automaticamente la versione dell’API.
• Identifica l’account interessato dalla richiesta API includendo l’intestazione Stripe-Context.

Ad esempio, data la seguente struttura dell’organizzazione:

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

Puoi utilizzare la chiave API dell’organizzazione per accedere al saldo dell’account indipendente. Puoi utilizzare la stessa chiave anche per effettuare la stessa chiamata per l’account connesso della piattaforma.

curl https://api.stripe.com/v1/balance \
  -u {{ORG_SECRET_KEY}}: \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

Nell’esempio di codice precedente, sostituisci {{CONTEXT}} con il valore pertinente:

• Per l’account indipendente, utilizza acct_1aTnTtAAB0hHJ26p.
• Per l’account connesso, utilizza un percorso che identifichi sia la piattaforma che l’account connesso, seguendo il formato acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

È necessario specificare l’account pertinente utilizzando il contesto e la versione API in qualsiasi richiesta API che utilizza una chiave dell’organizzazione.

Le organizzazioni non dispongono di chiavi API pubblicabili perché non possono accettare pagamenti. Puoi utilizzare la chiave API dell’organizzazione per creare un PaymentIntent per qualsiasi account dell’organizzazione, ma devi utilizzare chiavi pubblicabili specifiche dell’account esistente per le operazioni lato client.

Chiavi API gestite

Alcune piattaforme di terze parti, come Vercel, possono creare e gestire chiavi API per tuo conto quando installi la loro integrazione. Queste chiavi sono chiamate chiavi API gestite e la piattaforma le crea tramite codice anziché manualmente nella Dashboard.

Le chiavi API gestite vengono visualizzate insieme alle altre chiavi nella scheda Chiavi API, con il nome della piattaforma di gestione.

La tabella seguente riassume le differenze tra chiavi non gestite e chiavi gestite.

Revoca l’accesso alla chiave gestita

Puoi revocare una chiave API gestita in qualsiasi momento effettuando una delle seguenti operazioni:

• Scadenza della chiave: nella scheda chiavi API, fai clic sul menu extra () della chiave gestita e fai clic su di essa per farla scadere. In questo modo viene revocato immediatamente l’accesso alla piattaforma senza rimuovere l’integrazione.
• Disinstalla l’integrazione: disinstalla l’app della piattaforma dal tuo account Stripe. Quando disinstalli un’app, puoi scegliere di far scadere immediatamente le chiavi gestite o di mantenerle attive.

Chiavi private e con limitazioni

Usa la Dashboard per creare, rivelare, modificare, eliminare e ruotare chiavi private e con limitazioni.

Creare una chiave API

Puoi creare una chiave API privata o una chiave API con limitazioni. Una chiave API con limitazioni consente solo il livello di accesso specificato.

Per creare una chiave API privata

1. Nella scheda Chiavi API, fai clic su Crea chiave privata.
2. Nella finestra di dialogo inserisci il codice di verifica che Stripe ti invia via email o SMS. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
3. Inserisci un nome nel campo Nome chiave, quindi fai clic su Crea.
4. Fai clic sul valore chiave per copiarlo.
5. Salva il valore della chiave. Non potrai più recuperarlo.
6. Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fine.

Per creare una chiave API con limitazioni

1. Nella scheda Chiavi API, esegui una delle seguenti operazioni:
   • Per creare una nuova chiave con limitazioni, fai clic su Crea chiave con limitazioni. Il valore predefinito per tutte le autorizzazioni è Nessuna.
   • Per clonare una chiave esistente, fai clic sul menu di overflow (), quindi seleziona Duplica chiave per la chiave che vuoi clonare. Il valore predefinito per ogni autorizzazione è il relativo valore nella chiave clonata.
2. Nel campo Nome chiave, inserisci un nome. Se è stata clonata una chiave esistente, il nome predefinito corrisponde al nome della chiave clonata.
3. Per ogni risorsa a cui desideri che la nuova chiave abbia accesso, seleziona l’autorizzazione appropriata: Nessuna, Lettura o Scrittura. Se utilizzi Connect, puoi anche selezionare l’autorizzazione da consentire a questa chiave quando accedi agli account connessi.
4. Fai clic su Crea chiave.
5. Nella finestra di dialogo inserisci il codice di verifica che Stripe ti invia via email o SMS. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
6. Fai clic sul valore chiave per copiarlo.
7. Salva il valore della chiave. Non potrai più recuperarlo.
8. Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fine.

Rivelare una chiave API

Puoi rivelare una chiave API privata o una chiave API con limitazioni in una sandbox o in modalità live.

In modalità live, Stripe mostra la chiave API solo una volta (per motivi di sicurezza). Conserva la chiave in un luogo sicuro. Per ricordarti dove l’hai salvata, puoi aggiungere una nota sulla chiave nella Dashboard. Se perdi la chiave, puoi ruotarla o eliminarla e crearne un’altra.

Per rivelare una chiave API privata in una sandbox

1. Nella scheda Chiavi API, nell’elenco Chiavi Standard, fai clic su Rivela chiave di test nella riga Chiave privata. Puoi rivelare la chiave API privata tutte le volte che vuoi.
2. Fai clic sul valore chiave per copiarlo.
3. Salva il valore della chiave.
4. Fai clic su Nascondi chiave di test.

Rivelare una chiave API privata o con limitazioni in modalità live

1. Nella scheda Chiavi API in modalità live, nell’elenco Chiavi standard o Chiavi con limitazioni, fai clic su Rivela chiave live per la chiave che desideri rivelare.
2. Fai clic sul valore chiave per copiarlo.
3. Salva il valore della chiave.
4. Fai clic su Nascondi chiave di test.
5. Clicca sul menu di overflow (), quindi seleziona Modifica chiave per la chiave a cui desideri aggiungere una nota.
6. Nel campo Nota inserisci la posizione in cui hai salvato la chiave, poi fai clic su Salva.

Limitare una chiave API a determinati indirizzi IP

Puoi limitare una chiave API privata o una chiave API con limitazioni a un intervallo di indirizzi IP o a uno o più indirizzi IP specifici. Stripe consiglia di abilitare le limitazioni IP su tutte le chiavi in modalità live per impedire l’uso da posizioni non autorizzate. Se applicabile, utilizza elenchi di consenso IP separati per chiavi separate (ad esempio, per distinguere tra ambienti di staging e di produzione).

Gli indirizzi IP devono utilizzare il protocollo IPv4 e puoi specificare qualsiasi intervallo CIDR valido. Ad esempio,puoi specificare l’intervallo 100.10.38.0 - 100.10.38.255 come 100.10.38.0/24. Tutti gli indirizzi IP nell’intervallo devono iniziare con 100.10.38.

1. Nella scheda Chiavi API, nell’elenco Chiavi Standard o Chiavi con limitazioni, fai clic sul menu di overflow () e seleziona la chiave che vuoi rivelare.

2. Seleziona Gestisci limitazioni IP > Limita l’uso a una serie di indirizzi IP.

3. Esegui una delle seguenti operazioni:

   • Inserisci un indirizzo IP singolo nel campo Indirizzo IP.
   • Per un intervallo di indirizzi IP, inserire il primo indirizzo dell’intervallo (utilizzando la notazione CIDR, routing interdominio senza classi) nel campo Indirizzo IP. Inserisci la dimensione del prefisso di rete nel campo CIDR.

   Puoi anche inserire singoli indirizzi IP e intervalli (separati da spazi) nella scheda Gestione collettiva. Le modifiche apportate in una scheda vengono visualizzate anche nell’altra scheda.

4. Per aggiungere un altro indirizzo IP o intervallo, fai clic su + Aggiungi.

5. Fai clic su Salva.

Modificare il nome o la nota di una chiave API

1. Nella scheda delle chiavi API, fai clic sul menu di overflow () della chiave che vuoi modificare.
2. Seleziona Modifica chiave.
3. Procedi come segue:
   • Per modificare il nome, inserisci un nuovo nome nel campo Nome chiave.
   • Per modificare il testo della nota, inserisci il nuovo testo nel campo Nota.
4. Fai clic su Salva.

Fai scadere una chiave API

Se elimini una chiave API privata o una chiave API con limitazioni, devi crearne una nuova e aggiornare tutti i codici che utilizzano la chiave scaduta. Ogni codice che utilizza la chiave scaduta non potrà più effettuare chiamate API.

1. Nella scheda Chiavi API, nell’elenco Chiavi Standard o Chiavi con limitazioni, fai clic sul menu di overflow () della chiave che desideri far scadere.
2. Seleziona Scadenza chiave.
3. Nella finestra di dialogo, fai clic su Elimina chiave. Se non vuoi più eliminarla, fai clic su Annulla.

Ruotare una chiave API

La rotazione di una chiave API la revoca e genera una chiave sostitutiva pronta da usare subito. Puoi anche possibile programmare la rotazione di una chiave API dopo un determinato periodo di tempo. La chiave sostitutiva viene denominata come segue:

• Il nome della chiave pubblicabile sostitutiva è sempre Publishable key.
• Il nome chiave privata sostitutiva è sempre Secret key.
• La chiave con limitazioni sostitutiva ha lo stesso nome della chiave ruotata.

Puoi rinominare una chiave API privata, o con limitazioni, modificandola.

Ruota la chiave API in scenari come:

• Se perdi una chiave API privata, o con limitazioni, in modalità live e non puoi recuperarla dalla Dashboard.
• Se una chiave API privata o con limitazioni viene compromessa, è necessario revocarla per bloccare eventuali richieste API potenzialmente dannose che potrebbero utilizzare la chiave.
• Se un membro del team con accesso alla chiave lascia la tua organizzazione o cambia ruolo.
• Se la tua policy richiede la rotazione delle chiavi a determinati intervalli.

Per ruotare una chiave API:

1. Nella scheda delle chiavi API, fai clic sul menu extra () della chiave che vuoi ruotare.
2. Seleziona Ruota chiave.
3. Seleziona una data di scadenza dal menu a discesa Scadenza. Se selezioni Ora, la chiave precedente viene eliminata. Se specifichi un’ora, sotto il nome della chiave viene mostrato il tempo rimanente fino alla scadenza della chiave.
4. Fai clic su Ruota chiave API.
5. Fai clic sul valore chiave per copiarlo.
6. Salva il valore della chiave. Non potrai più recuperarlo.
7. Nel campo Aggiungi una nota inserisci la posizione in cui hai salvato la chiave, quindi fai clic su Salva o Fine.

Ripristina l’accesso a una chiave API

Una chiave API può avere un accesso limitato se non è stato utilizzato per creare trasferimenti, bonifici o aggiornare destinazioni di bonifico per oltre 180 giorni. Non è possibile utilizzare una chiave con accesso limitato per creare bonifici e trasferimenti o per creare destinazioni di bonifico. È possibile ripristinare l’accesso per utilizzare il codice normalmente o per eseguire un’azione bloccata.

Per ripristinare l’accesso per una chiave API

1. Nella scheda delle chiavi API, fai clic sul menu extra () della chiave che vuoi ripristinare.
2. Seleziona Ripristina accesso.
3. Fai clic su Ripristina.

Visualizzare log di richieste API

Per aprire i log di richieste API, fai clic sul menu di overflow () di qualsiasi chiave, quindi seleziona Visualizza log richieste. L’apertura dei registri reindirizza alla Dashboard Stripe.