Passa al contenuto
Crea account o Accedi
Il logo della documentazione Stripe
/
Crea un accountAccedi
PanoramicaEseguire l'upgrade dell'integrazione
Pagamenti online
PanoramicaTrovare il caso d'uso più adattoUsa Managed Payments
Pagamenti di persona
Metodi di pagamento
Scenari di pagamento
Oltre i pagamenti

Accettare un pagamento

Accettare pagamenti online in modo sicuro

Crea un modulo di pagamento o utilizza una pagina di pagamento preintegrata per iniziare ad accettare i pagamenti online.

Crea una pagina di pagamento sul tuo sito web utilizzando Stripe Elements e Checkout Sessions, un’integrazione front-end che gestisce imposte, sconti, costi di spedizione e molto altro ancora.

Paese del cliente
Formato
Tema
Layout
Questa demo mostra Google Pay o Apple Pay solo se disponi di una carta attiva con uno dei due wallet.

Configurare il server
Lato server

Prima di iniziare, devi registrarti per creare un account Stripe.

Utilizza le librerie ufficiali di Stripe per accedere all’API dalla tua applicazione.

Command Line
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
npm install stripe@18.0.0 --save

Imposta l’SDK in modo che utilizzi almeno la versione dell’API 2025-03-31.basil.

TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-03-31.basil' as any,
});

Creare una sessione di Checkout
Lato server

Aggiungi sul server un endpoint che crei una sessione di Checkout e restituisca la sua chiave privata client al tuo front-end. Una sessione di Checkout rappresenta la sessione in cui il cliente completa acquisti una tantum o sottoscrive abbonamenti. Le sessioni di Checkout scadono 24 ore dopo la creazione.

server.ts
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
import express, {Express} from 'express';

const app: Express = express();

app.post('/create-checkout-session', async (req: Express.Request, res: Express.Response) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 2000,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'custom',
    // The URL of your payment completion page
    return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
  });

  res.json({checkoutSessionClientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});

Configurare il front-end
Lato client

Includi lo script Stripe.js nella tua pagina di pagamento aggiungendolo all’oggetto head del tuo file HTML. Carica sempre Stripe.js direttamente da js.stripe.com per mantenere la conformità alle norme PCI. Non includere lo script in un pacchetto e non ospitarne una copia personale.

Ensure you’re on the latest Stripe.js version by including the following script tag <script src=“https://js.stripe.com/clover/stripe.js”></script>. Learn more about Stripe.js versioning.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Nota

Stripe fornisce un pacchetto npm che puoi utilizzare per caricare Stripe.js come modulo. Consulta il progetto su GitHub. È necessaria la versione 7.0.0 o successiva.

Inizializza stripe.js.

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
,
);

Inizializzare Checkout
Lato client

Crea una promessa clientSecret che si risolve con la chiave privata client o impostala direttamente come chiave privata . Chiama initCheckout, specificando la chiave clientSecret. initCheckout restituisce una promessa che si risolve in un’istanza di Checkout instance.

L’oggetto completamento della transazione funge da base della pagina di completamento della transazione e contiene i dati della sessione di completamento della transazione e i metodi per aggiornare la sessione.

L’oggetto restituito da actions.getSession() contiene le informazioni sui prezzi. Si consiglia di leggere e visualizzare totale lineItems della sessione nell’interfaccia utente.

In questo modo è possibile attivare nuove funzioni modificando minimamente il codice. Ad esempio, l’aggiunta di manuale di prezzi in valuta non richiede modifiche dell’interfaccia utente se visualizzi il totale.

checkout.js
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.checkoutSessionClientSecret);
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
  const checkoutContainer = document.getElementById('checkout-container');
  checkoutContainer.append(JSON.stringify(session.lineItems, null, 2));
  checkoutContainer.append(document.createElement('br'));
  checkoutContainer.append(`Total: ${session.total.total.amount}`);
}
index.html
<div id="checkout-container"></div>

Raccogliere l'indirizzo email del cliente
Lato client

Crea un campo di inserimento per raccogliere l’indirizzo email del cliente. Chiama updateEmail quando il cliente termina l’inserimento per convalidare e salvare l’indirizzo email.

A seconda del design del tuo modulo di pagamento, puoi chiamare updateEmail nei seguenti modi:

  • Immediatamente prima di inviare il pagamento. Puoi anche chiamare updateEmail per eseguire la convalida prima, ad esempio quando l’utente fa clic al di fuori del campo di inserimento.
  • Prima di passare alla fase successiva, ad esempio facendo clic sul pulsante Salva, se il tuo modulo prevede più passaggi.
index.html
<input type="text" id="email" />
<div id="email-errors"></div>
checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}

Raccogliere i dati di pagamento
Lato client

Raccogli i dati di pagamento sul client con Payment Element. Payment Element è un componente di interfaccia utente preintegrato che semplifica la raccolta dei dati di pagamento per vari metodi di pagamento.

Innanzitutto, crea un elemento DOM del contenitore per montare Payment Element. Poi crea un’istanza di Payment Element utilizzando checkout.createPaymentElement e montala chiamando element.mount, fornendo un selettore CSS o l’elemento DOM del contenitore.

index.html
<div id="payment-element"></div>
checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

Consulta la documentazione Stripe.js per visualizzare le opzioni supportate.

Puoi personalizzare l’aspetto di tutti gli elementi specificando elementsOptions.appearance durante l’inizializzazione di Checkout nel front-end.

Inviare il pagamento
Lato client

Renderizza un pulsante Paga che richiama confirm dall’istanza di completamento della transazione per inviare il pagamento.

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>
checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    actions.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
}

Testare l'integrazione

  1. Vai alla pagina di pagamento.
  2. Compila i dati di pagamento con un dei metodi di pagamento indicati nella tabella di seguito. Per i pagamenti con carta:
    • Inserisci una data di scadenza futura per la carta.
    • Inserisci un numero di 3 cifre per il CVC.
    • Inserisci un qualsiasi codice postale.
  3. Invia il pagamento a Stripe.
  4. Vai alla Dashboard e cerca il pagamento nella pagina Transazioni. Se il pagamento è andato a buon fine, lo vedrai nell’elenco.
  5. Fai clic sul pagamento per visualizzare ulteriori dettagli, come i dati di addebito e l’elenco degli articoli acquistati. Puoi utilizzare queste informazioni per evadere l’ordine.
Numero di cartaScenarioCome eseguire il test
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.
Il pagamento con carta richiede l’autenticazione.Compila il modulo della carta di credito utilizzando il numero di carta di credito con scadenza, CVC e codice postale.
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.
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.

Per ulteriori informazioni su come testare la tua integrazione, consulta la sezione Test.

FacoltativoCreare prodotti e prezzi

Prima di creare una sessione di Checkout, puoi creare prodotti e prezzi in anticipo. Utilizza i prodotti per rappresentare diversi beni fisici o livelli di servizio e prezzi per rappresentare il prezzo di ciascun prodotto.

Ad esempio, puoi creare una T-shirt come prodotto con un prezzo di 20 USD. In questo modo puoi aggiornare e aggiungere prezzi senza dover modificare le informazioni dei prodotti sottostanti. Puoi creare prodotti e prezzi con la Dashboard o l’API di Stripe. Ulteriori informazioni su come funzionano prodotti e prezzi.

L’API richiede solo un name per creare un prodotto. Checkout mostra name, description e images del prodotto che fornisci.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name=T-shirt

Poi crea un oggetto Price per definire quanto far pagare il prodotto, comprensivo sia del costo del prodotto sia della valuta da utilizzare.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d product=
"{{PRODUCT_ID}}"
 \
  -d unit_amount=2000 \
  -d currency=usd

Ogni prezzo che crei ha un ID. Quando crei una sessione di completamento della transazione, fai riferimento all’ID del prezzo e alla quantità. Se vendi in più valute, imposta il tuo prezzo multi-currency. Il completamento della transazione determina la valuta locale del cliente in automatico e presenta quella valuta, se il prezzo la supporta.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d ui_mode=custom \
  -d mode=payment \
  -d "line_items[0][price]"={{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  --data-urlencode return_url="https://example.com/return?session_id={CHECKOUT_SESSION_ID}"

FacoltativoPrecompilare i dati dei clienti
Lato server

Se hai già raccolto l’indirizzo email del cliente e vuoi che venga precompilato nella sessione di Checkout, specifica customer_email durante la creazione di una sessione di Checkout.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode customer_email="customer@example.com" \
  -d ui_mode=custom \
  -d mode=payment \
  -d "line_items[0][price]"={{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  --data-urlencode return_url="https://example.com/return?session_id={CHECKOUT_SESSION_ID}"

FacoltativoSalvare i dati del metodo di pagamento

Come accettare un pagamento e salvare i dati di pagamento del cliente per acquisti futuri

FacoltativoAscoltare le modifiche alla sessione di Checkout

Ascoltare le modifiche alla sessione di Checkout

Puoi ascoltare le modifiche alla sessione di Checkout aggiungendo un listener di eventi sull’evento 'change con checkout.on.

checkout.js
checkout = stripe.initCheckout({
  clientSecret: promise,
  elementsOptions: { appearance },
});

checkout.on('change', (session) => {
  // Handle changes to the checkout session
});

FacoltativoRaccogliere gli indirizzi di fatturazione e di spedizione

Raccogliere un indirizzo di fatturazione

Per impostazione predefinita, una sessione di Checkout raccoglie i dati di fatturazione minimi necessari per il pagamento tramite Payment Element.

Utilizzo di Billing Address Element

Puoi raccogliere indirizzi di fatturazione completi utilizzando Billing Address Element.

Innanzitutto, specifica billing_address_collection=required quando crei la sessione di Checkout.

Crea un elemento DOM del contenitore per montare Billing Address Element. Quindi crea un’istanza di Billing Address Element utilizzando checkout.createBillingAddressElement e montala chiamando element.mount, fornendo un selettore CSS o l’elemento DOM del contenitore.

index.html
<div id="billing-address"></div>
checkout.js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');

Billing Address Element supporta le seguenti opzioni:

Utilizzo di un modulo personalizzato

Puoi creare un modulo personalizzato per raccogliere gli indirizzi di fatturazione.

  • Se la tua pagina di pagamento ha una fase di raccolta dell’indirizzo distinta prima della conferma, chiama updateBillingAddress quando il cliente invia l’indirizzo.
  • In alternativa, puoi inviare l’indirizzo quando il cliente fa clic sul pulsante di pagamento specificando billingAddress per confirm.

Raccogliere indirizzi di fatturazione parziali

Per raccogliere indirizzi di fatturazione parziali, ad esempio solo il Paese e il codice postale, specifica billing_address_collection=auto.

Quando si raccolgono indirizzi di fatturazione parziali, occorre raccogliere gli indirizzi manualmente. Per impostazione predefinita, Payment Element raccoglie automaticamente i dati di fatturazione minimi necessari per il pagamento. Per evitare la doppia raccolta dei dati di fatturazione, specifica fields.billingDetails=never durante la creazione del Payment Element. Se intendi raccogliere solo un sottoinsieme di dati di fatturazione (ad esempio il nome del cliente), specifica never solo per i campi che intendi raccogliere autonomamente.

Raccogliere un indirizzo di spedizione

Per raccogliere l’indirizzo di spedizione di un cliente, specifica il parametro shipping_address_collection quando crei la sessione di Checkout.

Quando raccogli un indirizzo di spedizione, devi anche specificare i Paesi autorizzati per la spedizione. Configura la proprietà allowed_countries con una matrice di codici Paese ISO di due lettere.

Come utilizzare Shipping Address Element

Puoi raccogliere indirizzi di spedizione completi con Shipping Address Element.

Crea un elemento DOM del contenitore per montare Shipping Address Element. Quindi crea un’istanza di Shipping Address Element utilizzando checkout.createShippingAddressElement e montala chiamando element.mount, fornendo un selettore CSS o l’elemento DOM del contenitore.

index.html
<div id="shipping-address"></div>
checkout.js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');

Shipping Address Element supporta le seguenti opzioni:

Ascoltare le modifiche alla sessione di Checkout

Puoi ascoltare le modifiche alla sessione di Checkout aggiungendo un listener di eventi per gestire le modifiche relative all’indirizzo.

Utilizza l’oggetto Session per visualizzare l’importo della spedizione nel modulo di pagamento.

index.html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="shipping" ></div>
  <div id="total" ></div>
</div>
checkout.js
const checkout = stripe.initCheckout({clientSecret});
const subtotal = document.getElementById('subtotal');
const shipping = document.getElementById('shipping');
const total = document.getElementById('total');

checkout.on('change', (session) => {
  subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`;
  shipping.textContent = `Shipping: ${session.total.shippingRate.amount}`;
  total.textContent = `Total: ${session.total.total.amount}`;
});

Usare un modulo personalizzato

Puoi creare un modulo personalizzato per raccogliere gli indirizzi di spedizione.

  • Se la tua pagina di pagamento ha una fase di raccolta dell’indirizzo ben definita prima della conferma, chiama updateShippingAddress quando il cliente invia l’indirizzo.
  • In alternativa, puoi inviare l’indirizzo quando il cliente fa clic sul pulsante di pagamento specificando shippingAddress per confirm.

FacoltativoSeparare l'autorizzazione dall'acquisizione
Lato server

Stripe supporta i pagamenti con carta in due passaggi in modo tale che tu possa prima autorizzare una carta e successivamente addebitare il pagamento. Quando Stripe autorizza un pagamento, la società emittente della carta garantisce l’importo e lo trattiene sulla carta del cliente. Hai quindi un certo periodo di tempo per acquisire i fondi, a seconda della carta). Se non acquisisci il pagamento prima della scadenza dell’autorizzazione, il pagamento viene annullato e la società emittente rilascia i fondi trattenuti.

La separazione dell’autorizzazione dall’acquisizione è utile se devi eseguire altre operazioni tra la conferma che il cliente è in grado di pagare e la riscossione del pagamento. Ad esempio, se vendi articoli con scorte limitate, potresti dover verificare che un articolo acquistato dal cliente utilizzando Checkout sia ancora disponibile prima di addebitare il pagamento ed evadere l’acquisto. A tal fine, utilizza il seguente flusso di lavoro:

  1. Conferma che Stripe abbia autorizzato il metodo di pagamento del cliente.
  2. Consulta il sistema di gestione delle scorte per verificare che l’articolo sia ancora disponibile.
  3. Aggiorna il sistema di gestione dell’inventario in modo che indichi che un cliente ha acquistato l’articolo.
  4. Acquisisci il pagamento del cliente.
  5. Fai sapere al cliente se l’acquisto è andato a buon fine nella pagina di conferma.

Per indicare che vuoi separare l’autorizzazione dall’addebito, devi impostare il valore di payment_intent_data.capture_method su manual durante la creazione della sessione di Checkout. In questo modo Stripe autorizza solo l’importo sulla carta del cliente.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"={{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d "payment_intent_data[capture_method]"=manual \
  -d return_url={{RETURN_URL}} \
  -d ui_mode=custom

Per riscuotere un pagamento non addebitato, puoi utilizzare la Dashboard o l’endpoint capture. Per acquisire i pagamenti a livello di codice, devi accedere al PaymentIntent creato durante la sessione di Checkout, che puoi ottenere dall’oggetto Session.

FacoltativoGestione degli account dei clienti
Nessun codice

Consenti ai tuoi clienti di gestire il loro account condividendo un link sul tuo portale cliente. Il portale cliente consente ai clienti di accedere con la propria email per gestire gli abbonamenti, aggiornare le modalità di pagamento e così via.

FacoltativoEvasione dell'ordine

Come ricevere una notifica a livello di codice quando un cliente effettua un pagamento

Vedi anche

Questa pagina è stata utile?
SìNo
Code quickstart
Guide correlate
API Elements Appearance
Altri scenari di pagamento
Come funzionano le carte