Pratiche ottimali di utilizzo di SourcesObsoleto

La flessibilità dell’API Sources ti consente di ridurre al minimo le modifiche necessarie per accettare modalità di pagamento aggiuntive.

Flusso tipico dei pagamenti con carta

In un flusso tipico di pagamento per le transazioni con carta (eccetto 3D Secure), la tua integrazione acquisisce i dati della carta e crea un oggetto Source, che usa poi per effettuare una richiesta di addebito. Dato che nessuna ulteriore azione è richiesta da parte del cliente e che i pagamenti con carta forniscono conferma sincrona, possiamo immediatamente confermare se il pagamento è andato a buon fine e che i fondi sono garantiti, senza dover usare i webhook.

Quando è necessario usare i webhook

Con altre modalità di pagamento può essere necessario che il cliente compia un’azione aggiuntiva prima che un oggetto Source diventi chargeable e possa essere usato per effettuare una richiesta di addebito (ad esempio, iDEAL). Questa transizione avviene solitamente in modo asincrono e, in alcuni casi, può avvenire quando il cliente ha già lasciato il sito web. La tua integrazione deve quindi basarsi sui webhook per stabilire quando un oggetto Source è passato in uno stato addebitabile prima di creare un addebito.

Stripe invia i seguenti eventi webhook per notificarti le modifiche di stato dell’oggetto Source:

Allo stesso modo, quando crei un addebito, determinate modalità di pagamento di tipo asincrono possono richiedere giorni perché i fondi siano confermati e l’addebito abbia esito positivo, rendendo necessari i webhook per sapere quando confermare ed eventualmente evadere gli ordini.

Stripe invia i seguenti eventi webhook per notificarti le modifiche di stato di un addebito:

Creare un’integrazione flessibile

Per garantire che la tua procedura di pagamento sia flessibile e predisposta ad accettare più modalità di pagamento, consigliamo l’approccio seguente:

Creazione di un oggetto Source

Quando crei un oggetto Source, registrane l’ID nella rappresentazione interna dell’ordine in modo da poter recuperare l’ordine quando ricevi ed elabori i webhook source.chargeable. Per una ricerca efficiente, assicurati di indicizzare gli oggetti Ordine in base a questo attributo source.

Creazione di un oggetto Charge

La consegna del webhook source.chargeable comporta l’addebito dell’importo sull’oggetto Source. Alla ricezione del webhook, recupera la rappresentazione interna dell’ordine con una ricerca basata sull’ID dell’oggetto Source e verifica che l’ordine sia in attesa di un pagamento.

Quando effettui una richiesta di addebito, usa l’ID interno dell’ordine come chiave di idempotenza per evitare qualsiasi possibile race condition. Inoltre, se l’oggetto Source è riutilizzabile e vuoi riutilizzarlo, assicurati di associarlo a un oggetto Customer prima di effettuare l’addebito. Per ulteriori informazioni su come gestire oggetti Source monouso o riutilizzabili e sulla loro interazione con oggetti Customer, consulta le nostre guide Monouso o riutilizzabili e Oggetti Source e Customer.

Come nella creazione di un oggetto Source, devi registrare l’ID dell’addebito nella rappresentazione interna dell’ordine in modo da poter recuperare l’ordine quando ricevi ed elabori i webhook charge.succeeded.

Pagina di conferma

Dopo che il cliente ha eseguito le azioni necessarie per autorizzare un pagamento (ad esempio, ha seguito un reindirizzamento), devi presentare la pagina di conferma che mostra lo stato dell’ordine. Puoi farlo tramite il polling interno dell’ordine.

Dato che la latenza di recapito dei webhook non è garantita, se vuoi semplificare ulteriormente la tua pagina di conferma, puoi eseguire il polling dello stato dell’oggetto Source associato nel tuo codice lato client. Quando rilevi che il tuo oggetto Source è diventato chargeable, puoi avviare la creazione di un oggetto Charge che usa quello Source senza attendere che arrivi il webhook source.chargeable.

Tieni presente che alcuni tipi di oggetti Sources impiegano minuti (o addirittura giorni) per diventare chargeable. Se decidi di eseguire il polling dell’oggetto Source, ti consigliamo di inserire un time out a un certo punto e avvertire il cliente che il suo ordine è giacente in attesa di conferma del pagamento, e di inviargli quindi una email per la conferma del pagamento in modo asincrono. Puoi vedere la messaggistica per il cliente consigliata per ogni stato dell’oggetto Source nella tabella riportata di seguito.

Se il cliente lascia la tua pagina, il polling lato client si arresta. Questo significa che la tua integrazione deve anche gestire il webhook source.chargeable per garantire che non venga persa traccia dell’ordine del cliente.

Se usi Stripe.js, puoi utilizzare il metodo stripe.retrieveSource() per implementare il tuo polling:

// In order-confirmation-page.js

const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// After some amount of time, we should stop trying to resolve the order synchronously:
const MAX_POLL_COUNT = 10;
let pollCount = 0;

const pollForSourceStatus = async () => {
  const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET})
  if (source.status === 'chargeable') {
    // Make a request to your server to charge the Source.
    // Depending on the Charge status, show your customer the relevant message.
  } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) {
    // Try again in a second, if the Source is still `pending`:
    pollCount += 1;
    setTimeout(pollForSourceStatus, 1000);
  } else {
    // Depending on the Source status, show your customer the relevant message.
  }
};

pollForSourceStatus();

Nella tabella seguente sono riportati i possibili messaggi consigliati per il cliente che puoi visualizzare in base allo stato dell’oggetto Source.

Dopo la creazione di un oggetto Charge (e se l’utente è ancora sulla tua pagina di conferma), puoi visualizzare i seguenti messaggi in base allo stato dell’oggetto Charge:

Conferma dell’ordine

Conferma l’ordine solo dopo la ricezione del webhook charge.succeeded (che può avvenire istantaneamente oppure no). A questo punto invia una email al cliente, perché la conferma dei pagamenti asincroni può richiedere giorni.

Annullamenti ed esiti negativi

Resta in ascolto dei webhook source.canceled e source.failed e assicurati di annullare l’ordine associato all’oggetto Source corrispondente. Seguendo le pratiche ottimali sopra descritte, non dovresti mai ricevere il webhook source.canceled per gli oggetti Source che si trovavano in stato chargeable (dato che il tuo gestore del webhook source.chargeable dovrebbe aver creato immediatamente un addebito, evitando l’annullamento dell’oggetto Source). Se ricevi comunque dei webhook source.canceled per oggetti Source che non sono mai passati nello stato chargeable ma sono rimasti nello stato pending, solitamente significa che il cliente ha lasciato il flusso di pagamento troppo presto. Puoi anche ricevere un webhook source.failed se il cliente ha rifiutato il pagamento oppure si è verificato un problema tecnico a livello di schema del pagamento.

Devi anche restare in ascolto dei webhook charge.failed per assicurarti di annullare l’ordine associato all’addebito ricevuto.

Per ciascuno di questi eventi, si consiglia di notificare al cliente che il suo ordine non è andato a buon fine e di invitarlo a tornare al flusso di pagamento, se lo desidera.