Passa al contenuto
Crea account o Accedi
Il logo della documentazione Stripe
/
Crea un accountAccedi
Panoramica
Controllo delle versioni
Aggiorna la tua versione API
Essentials
Strumenti
Stripe per Visual Studio Code
Funzionalità
Avvisi sullo stato di StripeCaricamenti file
Soluzioni di IA
Protocollo del contesto del modelloCreare flussi di lavoro di fatturazione SaaS con IA agentica
Sicurezza e privacy
Crawler web di Stripebot
Estendi Stripe
Partner
Certificazione di partner

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 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:

TipoDescrizione
Chiave privata sandboxAutentica le richieste sul tuo server quando esegui test in un ambiente sandbox. Per impostazione predefinita, puoi usare questa chiave per eseguire qualsiasi richiesta API senza limitazioni. Riserva questa chiave ai test e allo sviluppo, per assicurarti di non modificare accidentalmente clienti o addebiti attivi
Chiave pubblicabile sandboxTesta le richieste nel codice lato client della tua app web o per dispositivo mobile. Riserva questa chiave ai test e allo sviluppo, per assicurarti di non modificare accidentalmente clienti o addebiti attivi.
Chiave privata in modalità liveAutentica le richieste sul tuo server quando sei in modalità live. Per impostazione predefinita, puoi utilizzare questa chiave per eseguire qualsiasi richiesta API senza limitazioni.
Chiave pubblicabile in modalità liveQuando è tutto pronto per avviare la tua app, usa questa chiave nel codice lato client della tua app web o per dispositivo mobile.

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.

Chiavi API riservate

Puoi generare chiavi API con limitazioni nella Dashboard per abilitare l’accesso personalizzabile e limitato all’API. Tuttavia, Stripe non offre chiavi con limitazioni per impostazione predefinita.

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:

TipoValoreQuando utilizzarla
Privatask_test_BQokikJOvBiI2HlWgH4olfQ2Lato 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.
Pubblicabilepk_test_TYooMQauvdEDq54NiTphI7jxLato client: può essere accessibile pubblicamente nel codice lato client della tua app web o per dispositivo mobile (ad esempio, checkout.js) per raccogliere in modo sicuro le informazioni di pagamento (ad esempio tramite Stripe Elements). Per impostazione predefinita, Stripe Checkout raccoglie in modo sicuro le informazioni di pagamento.
Con limitazioniUna stringa che inizia con rk_test_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.

Proteggi le tue chiavi

Chiunque può utilizzare la tua chiave privata in modalità live per effettuare una chiamata API per conto del tuo account, ad esempio, per creare un addebito o eseguire un rimborso. Segui queste best practice per mantenere al sicuro le tue chiavi API segrete.

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

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, devi ruotarla o eliminala e quindi creane una nuova.

TipoQuando si usanoOggettiCome si usanoConsiderazioni
SandboxUtilizza una sandbox e le chiavi API di test associate mentre crei la tua integrazione. In una sandbox, 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.Utilizza account e carte di credito di test. Non puoi accettare metodi di pagamento reali né lavorare con account reali.Identy non effettua alcuna verifica. Inoltre, gli oggetti Account di Connect non restituiscono campi sensibili.
Modalità liveUtilizza 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.Il flusso delle contestazioni è più dettagliato e la relativa procedura di test è più semplice. Inoltre, alcuni metodi di pagamento hanno un flusso più dettagliato e richiedono un maggior numero di passaggi.

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.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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 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.

Rivelare chiavi private in modalità live

Quando crei una chiave API privata o con limitazioni in modalità live, viene visualizzata prima che la salvi. Devi copiare la chiave prima di salvarla perché potrai copiarla in un secondo momento. Puoi rivelare solo una chiave privata predefinita o una chiave generata tramite rotazione programmata.

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.

Nota

Le chiavi create prima che Stripe introducesse questa funzione non vengono nascoste automaticamente quando vengono rivelate. È necessario nasconderle manualmente facendo clic su Nascondi chiave attiva.

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.

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.

Eliminare una chiave API

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

Nota

Non puoi eliminare una chiave pubblicabile.

  1. Nella scheda Chiavi API, nell’elenco Chiavi Standard o Chiavi con limitazioni, fai clic sul menu di overflow () della chiave che desideri eliminare.
  2. Seleziona Elimina 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 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.

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.

Guide correlate
Testare l'integrazione
Test dei casi d'uso