Evadere gli ordini

Crea una funzione sul tuo server per evadere correttamente i pagamenti. I webhook attivano questa funzione e viene chiamata quando i clienti vengono indirizzati al tuo sito web dopo aver completato il pagamento. Questa guida definisce questa funzione come fulfill_checkout, ma è possibile assegnare alla funzione il nome desiderato.

La funzione fulfill_checkout deve:

1. Gestisci correttamente le chiamate ripetute con lo stesso ID sessione di Checkout.
2. Accetta un ID della sessione di Checkout come argomento.
3. Recupera la sessione di Checkout dalla API con la proprietà line_items espansa.
4. Controlla la proprietà payment_status per determinare se necessita dell’evasione degli ordini.
5. Esegui l’evasione delle voci riga.
6. Registra lo stato di evasione per la sessione di Checkout specificata.

Utilizza il codice riportato di seguito come punto di partenza per la funzione fulfill_checkout. I commenti TODO indicano le funzione che devi implementare.

def fulfill_checkout(session_id)
  # Set your secret key. Remember to switch to your live secret key in production.
  # See your keys here: https://dashboard.stripe.com/apikeys
  Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

  puts "Fullfilling Checkout Session #{session_id}"

  # TODO: Make this function safe to run multiple times,
  # even concurrently, with the same session ID

  # TODO: Make sure fulfillment hasn't already been
  # performed for this Checkout Session

  # Retrieve the Checkout Session from the API with line_items expanded
  checkout_session = Stripe::Checkout::Session.retrieve({
    id: session_id,
    expand: ['line_items'],
  })

  # Check the Checkout Session's payment_status property
  # to determine if fulfillment should be performed
  if checkout_session.payment_status != 'unpaid'
    # TODO: Perform fulfillment of the line items

    # TODO: Record/save fulfillment status for this
    # Checkout Session
  end
end

A seconda dei metodi di pagamento che accetti e delle esigenze della tua attività, potrebbe essere utile che la funzione fulfill_checkout esegua le seguenti operazioni:

• Fornire l’accesso ai servizi.
• Avvia la spedizione della merce.
• Salva una copia dei dati di pagamento e delle voci riga nel tuo database.
• Invia al cliente una ricevuta personalizzata via email se non hai abilitato le ricevute di Stripe.
• Riconcilia le voci riga e le quantità acquistate se consenti ai clienti di rettificare le quantità in Checkout.
• Aggiorna i registri dell’inventario o delle scorte.

Per attivare l’evasione degli ordini, crea un gestore eventi webhook per ascoltare gli eventi di pagamento e attivare la funzione fulfill_checkout.

Quando qualcuno ti paga, viene creato un evento checkout.session.completed. Configura un endpoint sul tuo server per accettare, elaborare e confermare la ricezione di questi eventi.

Confronto fra metodi di pagamento immediato e differito

Alcuni metodi di pagamento non sono istantanei, quali l’addebito diretto ACH e altri bonifici bancari. Ciò significa che i fondi non saranno immediatamente disponibili una volta completata la procedura di pagamento. I metodi di pagamento ritardato generano un evento checkout.session.async_payment_succeeded quando il pagamento viene completato in seguito. Lo stato dell’oggetto è in elaborazione fino a quando lo stato del pagamento non ha esito positivo o negativo.

require 'sinatra'

# Use the secret provided by Stripe CLI for local testing
# or your webhook endpoint's secret.
endpoint_secret = 'whsec_...'

post '/webhook' do
  event = nil

  # Verify webhook signature and extract the event
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    payload = request.body.read
    event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
  rescue JSON::ParserError => e
    # Invalid payload
    return status 400
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    return status 400
  end

  if event['type'] == 'checkout.session.completed' ||
  event['type'] == 'checkout.session.async_payment_succeeded'
    fulfill_checkout(event['data']['object']['id'])
  end

  status 200
end

Potresti anche voler ascoltare e gestire gli eventi checkout.session.async_payment_failed. Ad esempio, puoi inviare un’email al tuo cliente quando un pagamento ritardato non va a buon fine.

Il modo più veloce per sviluppare e verificare il gestore eventi webhook è la CLI di Stripe. Se non disponi della CLI di Stripe, segui la guida all’installazione per iniziare.

Una volta installata la CLI di Stripe, puoi verificare il gestore eventi localmente. Esegui il tuo server (ad esempio, su localhost:4242), quindi esegui il comando stripe listen per fare in modo che la CLI di Stripe inoltri gli eventi al tuo server locale:

stripe listen --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)

Aggiungi la chiave privata del webhook (whsec_...) al codice di gestione eventi, quindi verifica l’evasione degli ordini accedendo a Checkout come cliente:

• Premi il pulsante di pagamento che ti reindirizza a Checkout o visita il tuo link di pagamento
• Fornisci i seguenti dati di test in Checkout:
  • Inserisci 4242 4242 4242 4242 come numero della carta
  • Inserisci una data di scadenza futura per la carta
  • Inserisci un numero di 3 cifre per il CVV
  • Inserisci qualsiasi CAP di addebito (90210)
• Premi il pulsante Paga

Una volta completato il pagamento, verifica quanto segue:

• Nella riga di comando, dove è in esecuzione stripe listen, viene visualizzato un evento checkout.session.completed inoltrato al tuo server locale.
• I log del server mostrano l’output previsto dalla funzione fulfill_checkout.

Dopo aver eseguito il test in locale, attiva il gestore eventi webhook sul tuo server. Poi crea un endpoint del webhook per inviare gli eventi checkout.session.completed al tuo server, infine verifica di nuovo il flusso di pagamento.

Configura Checkout per indirizzare il cliente a una pagina del tuo sito web una volta che ha completato la procedura di pagamento. Includi il placeholder {CHECKOUT_SESSION_ID} nell’URL della pagina, che viene sostituito con l’ID della sessione di Checkout quando il cliente viene reindirizzato da checkout.

Procedura di pagamento in hosting

Per le sessioni di Checkout con la ui_mode predefinita hosted, imposta success_url.

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 \
  --data-urlencode success_url="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

Payment Links

Per i link di pagamento che con l’API, imposta after_completion.redirect.url.

curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "after_completion[type]"=redirect \
  --data-urlencode "after_completion[redirect][url]"="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

Per i link di pagamento che crei nella Dashboard:

1. Vai alla scheda Dopo il pagamento.
2. Seleziona Non mostrare la pagina di conferma.
3. Fornisci l’URL della pagina di destinazione con il segnaposto {CHECKOUT_SESSION_ID} (ad esempio, https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID})

L’ascolto dei webhook è obbligatorio per garantire che venga sempre attivata l’evasione per ogni pagamento, ma i webhook a volte possono subire ritardi. Per ottimizzare il flusso di pagamento e garantire l’evasione immediata degli ordini in presenza del cliente, attiva l’evasione degli ordini anche dalla tua pagina di destinazione.

Utilizza l’ID della sessione di Checkout dall’URL specificato nel passaggio precedente per effettuare le seguenti operazioni:

1. Quando il tuo server riceve una richiesta per la tua pagina di destinazione di Checkout, estrai l’ID della sessione di Checkout dall’URL.
2. Esegui la funzione fulfill_checkout con l’ID fornito.
3. Visualizza la pagina al termine del tentativo di evasione degli ordini.

Quando visualizzi la pagina di destinazione, puoi mostrare quanto segue:

• Dettagli della procedura di evasione ordini.
• Link o informazioni sui servizi a cui il cliente ha ora accesso.
• Dati logistici o di spedizione per merci fisiche.