Chiavi API
Utilizza le chiavi API per autenticare le richieste 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 generare chiavi API. Per accedere alle chiavi API v1, seleziona la scheda Chiavi API sulla tua Dashboard.
Confronto tra la modalità di test e la modalità live
Tutte le richieste API di Stripe vengono eseguite in modalità di test o in modalità live. Utilizza la modalità di test per accedere ai dati di test e la modalità live per accedere ai dati effettivi dell’account. Ogni modalità ha una propria serie di chiavi API. Gli oggetti in una modalità non sono accessibili nell’altra. Ad esempio, un in modalità di test oggetto product non può far parte di un pagamento in modalità live.
Accesso alla chiave in modalità live
Puoi rivelare una chiave API privata o con limitazioni in modalità live solo una volta. Se la perdi, non puoi recuperarla dalla Dashboard. In tal caso, generala o eliminala e creane una nuova.
| Tipo | Quando si usano | Oggetti | Come si usano | Considerazioni |
|---|---|---|---|---|
| modalità di test | Utilizza la modalità di test, e le chiavi API di test associate, mentre crei la tua integrazione. In modalità di test, i circuiti delle carte di credito e i fornitori di servizi di pagamento non elaborano i pagamenti. | Le chiamate API restituiscono oggetti simulati. Ad esempio, puoi recuperare e utilizzare gli oggetti test account, payment, customer, charge, refund, transfer, balance e subscription. | Use test credit cards and accounts. You can’t accept real payment methods or work with real accounts. | Identity doesn’t perform any verification checks. Also, Connect account objects don’t return sensitive fields. |
| modalità live | Utilizza la modalità live, e le chiavi API live associate, quando sarà tutto pronto per lanciare l’integrazione e accettare denaro reale. In modalità live, i circuiti delle carte di credito e i fornitori di servizi di pagamento elaborano i pagamenti. | Le chiamate API restituiscono oggetti reali. Ad esempio, puoi recuperare e utilizzare gli oggetti reali account, payment, customer, charge, refund, transfer, balance e subscription. | Accetta carte di credito reali e lavora con gli account dei clienti. Puoi accettare autorizzazioni di pagamento, addebiti e acquisizioni reali per carte di credito e account. | Disputes have a more nuanced flow and a simpler testing process. Also, some payment methods have a more nuanced flow and require more steps. |
Chiavi private e pubblicabili
Tutti gli account hanno un totale di quattro chiavi API per impostazione predefinita, due per la modalità di test e due per la modalità live:
- Chiave privata per la modalità di test: utilizza questa chiave per autenticare le richieste sul server in modalità di test. Per impostazione predefinita, puoi utilizzare questa chiave per eseguire qualsiasi richiesta API senza limitazioni.
- Chiave pubblicabile per la modalità di test: utilizza questa chiave per eseguire dei test a livello di codice lato client della tua app web o per dispositivi mobili.
- Chiave privata per la modalità live: utilizza questa chiave per autenticare le richieste sul server in modalità live. Per impostazione predefinita, puoi utilizzare questa chiave per eseguire qualsiasi richiesta API senza limitazioni.
- Chiave pubblicabile per la modalità live: utilizza questa chiave, quando sarai pronto a lanciare l’app, nel codice lato client della tua app web o per dispositivi mobili.
Test e sviluppo
Usa solo le tue chiavi API di test per i test e le attività di sviluppo. In questo modo, non rischi di modificare accidentalmente i clienti o gli addebiti live.
You can find your secret and publishable keys in API keys. When you’re logged in, Stripe’s documentation automatically populates code examples with your test mode API keys (only you can see these values). If you’re not logged in, our code examples include randomly generated API keys. You can replace them with your own test keys or log in to see the code examples populated with your test API keys. If you can’t view your API keys, ask the owner of your Stripe account to add you to their team, with the proper permissions.
La tabella seguente mostra esempi generati casualmente di chiavi API private di prova e pubblicabili:
Chiavi API riservate
The Dashboard can also generate restricted API keys, enabling customizable and limited access to the API. However, Stripe doesn’t offer any restricted keys by default.
| Tipo | Valore | Quando utilizzarla |
|---|---|---|
| Privata | sk_ | Lato server: deve essere privata e conservata in tutta sicurezza nel codice lato server della tua app web o per dispositivi mobili (come in un sistema di gestione delle credenziali e delle variabili di un ambiente) per chiamare le API Stripe. Non esporre questa chiave su un sito web e non incorporarla in un’applicazione per dispositivi mobili. |
| Pubblicabile | pk_ | On the client side: Can be publicly accessible in your web or mobile app’s client-side code (such as checkout.js) to securely collect payment information, such as with Stripe Elements. By default, Stripe Checkout securely collects payment information. |
| Con limitazioni | Una stringa che inizia con rk_ | Nei microservizi: deve essere privata e memorizzata in modo sicuro nel codice del microservizio per richiamare le API Stripe. Non esporre questa chiave su un sito web e non incorporarla in un’applicazione per dispositivi mobili. |
Proteggere le proprie chiavi
Chiunque può utilizzare la chiave API privata in modalità live per effettuare qualsiasi chiamata API per conto del proprio account, come la creazione di un addebito o l’esecuzione di un rimborso. Tieni le chiavi al sicuro seguendo queste pratiche ottimali per le chiavi API private.
Personalizzare l’accesso alle API con le chiavi API con limitazioni
Per fornire un accesso limitato alle chiavi API, crea API con limitazioni. Puoi configurare una chiave API con limitazioni per consentire l’accesso in lettura o scrittura a risorse dell’API specifiche. Quando utilizzi microservizi che interagiscono con l’API per tuo conto, definisci chiavi con limitazioni che consentano solo l’accesso minimo richiesto da tali microservizi. Ad esempio, se utilizzi un servizio di monitoraggio delle contestazioni, crea una chiave con limitazioni che fornisca solo l’accesso in lettura alle risorse relative alle contestazioni. Questa chiave consente al servizio di recuperare i dati di cui ha bisogno, ma non gli consente di apportare modifiche o accedere ad altri dati.
Le chiavi con limitazioni non possono interagire con molte parti dell’API Stripe , poiché sono destinate solo a ridurre il rischio durante l’utilizzo o la creazione di microservizi. Non utilizzare chiavi con limitazioni come alternativa alle chiavi API pubblicabili o private del tuo account durante lo sviluppo dell’integrazione Stripe.
Errori di autorizzazione
Se utilizzi una chiave API con limitazioni in una chiamata a cui non può accedere, Stripe genera un errore di autorizzazione.
Limitare gli indirizzi IP che possono inviare richieste API
Per aumentare la sicurezza di una chiave privata o con limitazioni, limita gli indirizzi IP che possono utilizzarla per inviare richieste API. Puoi inoltre limitare una chiave a uno o più indirizzi IP o a un intervallo di indirizzi IP..
Rivelare una chiave API privata per la modalità di test
In modalità di test, puoi rivelare una chiave API privata tutte le volte che vuoi.
Per rivelare una chiave privata in modalità di test:
- Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
- Nell’elenco Chiavi standard, nella riga Chiave privata, fai clic su Rivela chiave di test.
- Copia il valore della chiave facendo clic su di esso.
- Salva il valore della chiave.
- Fai clic su Nascondi chiave di test.
Rivelare una chiave API privata o con limitazioni per la modalità live
Per motivi di sicurezza, in modalità live Stripe mostra solo una volta una chiave API privata o con limitazioni. Conserva la chiave in un luogo sicuro dove non la perderai. Per ricordarti dove l’hai memorizzata, puoi lasciare una nota sulla chiave nella Dashboard. Se perdi la chiave, puoi generarla o eliminarla e crearne un’altra.
Non puoi rivelare una chiave privata in modalità live che hai creato
Dopo aver creato una chiave API privata o con limitazioni in modalità live, viene visualizzato prima che lo salvi. Devi copiare il valore prima di procedere al salvataggio, poiché non potrai rivelarlo in un secondo momento. Puoi rivelare solo una chiave privata predefinita o una chiave generata mediante revoca programmata.
Per rivelare una chiave privata o con limitazioni in modalità live e allegare una nota:
Nota
Il link API keys si apre in modalità live.
- Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
- Nell’elenco **Standard ** o Chiavi con limitazioni, nella riga relativa alla chiave che vuoi rivelare, fai clic su Rivela chiave live.
- Copia il valore della chiave facendo clic su di esso.
- Salva il valore della chiave.
- Fai clic su Nascondi chiave di test.
- Fai clic sul menu extra () accanto alla chiave, poi seleziona Modifica chiave….
- Nel campo Nota inserisci la posizione in cui hai salvato la chiave, poi fai clic su Salva.
- Se hai creato la chiave prima che Stripe introducesse questa funzionalità, fai clic su Nascondi chiave attiva.
Nota
Le chiavi create prima dell’introduzione di questa funzionalità di Stripe non vengono nascoste automaticamente una volta rivelate. Devi nasconderle manualmente.
Revocare una chiave API
La revoca della chiave comporta la generazione di una chiave sostitutiva. È possibile revocare una chiave immediatamente o programmare la revoca dopo un certo periodo di tempo. Procedi alla revoca di una chiave negli scenari di esempio descritti di seguito:
- Se sei in modalità live e perdi una chiave privata o una chiave con limitazioni, non puoi recuperarla dalla Dashboard e devi sostituirla.
- Se una chiave privata o con limitazioni è compromessa, devi revocarla per bloccare eventuali richieste API potenzialmente dannose che potrebbero utilizzarla.
- La tua politica richiede la rotazione delle chiavi a determinati intervalli.
Per generare una chiave API:
- Apri la pagina delle chiavi API.
- Nella riga relativa alla chiave da revocare, fai clic sul menu extra ), quindi seleziona Revoca chiave….
- Scegli una data di scadenza dal menu discesa Scadenza.
- Fai clic su Revoca chiave API.
- La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
- Salva il valore della chiave. Non potrai più recuperarlo.
- Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fine o Salva.
Se hai scelto Ora per Scadenza, la chiave precedente viene eliminata. Se hai selezionato un’ora diversa, sotto il nome puoi visualizzare il tempo rimanente alla scadenza della chiave.
Indipendentemente dal tempo di scadenza della chiave precedente, la nuova chiave è pronta per l’uso immediatamente.
Quando generi una chiave pubblicabile, il nome della chiave sostitutiva è sempre Publishable key. Quando generi una chiave privata, il nome della chiave sostitutiva è sempre Secret key. Quando generi una chiave con limitazioni, il nome della chiave sostitutiva è lo stesso della chiave generata. Puoi rinominare una chiave privata o con limitazioni facendo clic sul relativo menu extra e selezionando Modifica chiave….
Eliminare una chiave API privata o con limitazioni
Se elimini una chiave, qualsiasi codice che utilizza tale chiave non può più effettuare chiamate API. Crea una nuova chiave e aggiorna il codice per usarla.
Nota
Non puoi eliminare una chiave pubblicabile.
Per eliminare una chiave:
- Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
- Individua la chiave che vuoi eliminare nell’elenco Chiavi standard o Chiavi con limitazioni. Nella riga di quella chiave, fai clic sul menu extra () e seleziona Elimina chiave….
- Nella finestra di dialogo Elimina chiave API, se vuoi davvero procedere all’eliminazione della chiave, fai clic su Elimina chiave. Altrimenti, fai clic su Annulla.
Creare una chiave API privata
Per creare una chiave API privata:
- Apri la pagina delle chiavi API.
- Fai clic su Crea chiave privata.
- Stripe invia un codice di verifica al tuo indirizzo email o in un SMS. Come per qualsiasi email o SMS, potrebbe non arrivare immediatamente. Inserisci il codice nella finestra di dialogo. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
- Inserisci un nome nel campo Nome chiave.
- Fai clic su Crea.
- La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
- Salva il valore della chiave. Non potrai più recuperarlo.
- Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fatto.
Creare una chiave API con limitazioni
Una chiave API con limitazioni consente solo il livello di accesso specificato.
Per creare una chiave API con limitazioni:
- Apri la pagina delle chiavi API.
- Puoi creare una chiave con limitazioni da zero o iniziare clonando una chiave con limitazioni esistente.
- Per creare da zero una chiave con limitazioni, fare clic su Crea chiave con limitazioni. In questo caso, il valore predefinito per tutte le autorizzazioni è Nessuna.
- Per clonare una chiave esistente, nella riga della chiave che vuoi clonare, fai clic sul menu extra (), poi seleziona Duplica chiave…. In questo caso, il valore predefinito per ogni autorizzazione è il relativo valore nella chiave clonata.
- Nel campo ** Nome chiave **, inserisci un nome. Se è stata clonata una chiave esistente, il nome predefinito corrisponde al nome della chiave clonata.
- Per ogni risorsa a cui vuoi concedere l’accesso alla nuova chiave, seleziona l’autorizzazione di accesso per quella chiave. Se utilizzi Connect, puoi selezionare anche l’autorizzazione per questa chiave per l’accesso agli account connessi. Le autorizzazioni disponibili sono Nessuna, Lettura o Scrittura.
- Fai clic su Crea chiave.
- Stripe invia un codice di verifica al tuo indirizzo email o in un SMS. Come per qualsiasi email o SMS, potrebbe non arrivare immediatamente. Inserisci il codice nella finestra di dialogo. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
- La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
- Salva il valore della chiave. Non potrai più recuperarlo.
- Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fatto.
Limitare le chiavi private o con limitazioni a un elenco o a un intervallo di indirizzi IP
Per limitare le richieste API che utilizzano una chiave a uno o più indirizzi IP specifici o a un intervallo di indirizzi IP:
Intervalli di indirizzi IP validi
Puoi specificare qualsiasi intervallo CIDR valido. Ad esempio, un intervallo valido potrebbe essere 100., specificato come 100.. Tutti gli indirizzi nell’intervallo devono iniziare con 100..
- Apri la pagina delle chiavi API.
- Nell’elenco Chiavi standard o Chiavi con limitazioni, nella riga relativa alla chiave che desideri rivelare, fai clic sul menu extra (), quindi seleziona Gestisci limitazioni IP….
- Fai clic su Limita l’uso a una serie di indirizzi IP.
- Inserisci un indirizzo IP o un intervallo di indirizzi IP:
- Inserisci ogni singolo indirizzo nel campo Indirizzo IP.
- Per un intervallo di indirizzi IP, inserisci l’intervallo nella notazione CIDR (Classless Inter-Domain Routing). Nel campo Indirizzo IP inserisci il primo indirizzo nell’intervallo. Nel campo CDR inserisci la dimensione del prefisso di rete.
- Puoi anche selezionare la scheda Gestisci in blocco e inserire indirizzi IP singoli e intervalli, separati da spazi. Le modifiche apportate in una scheda vengono visualizzate nell’altra scheda.
- Per aggiungere un altro indirizzo o intervallo, fai clic su + Aggiungi.
- Fai clic su Salva.
Modificare il nome o la nota di una chiave API privata o con limitazioni
Per modificare il nome o il testo della nota di una chiave privata o con limitazioni:
- Apri la pagina delle chiavi API.
- Nella riga relativa alla chiave che vuoi modificare, fai clic sul menu di overflow (), poi seleziona Modifica chiave….
- Se vuoi modificare il nome, inserisci il nuovo nome in ** Nome chiave**.
- Se vuoi modificare il testo della nota, inserisci il nuovo testo in Nota.
- Fai clic su Salva.
Visualizzare i log delle richieste API
Per aprire i log di richieste API, fai clic sul menu extra () per qualsiasi chiave, poi seleziona Visualizza log richieste. Quando apri i log, vieni reindirizzato alla Dashboard Stripe principale.