← Tutti gli articoli
PagamentiSupabaseAppunti tecnici

Il cliente ha pagato. L’app dice ancora “bloccato”. Ecco come costruisco pagamenti che non perdono vendite.

Pagato ma senza accesso, ticket con lo screenshot della banca, lo stesso ordine contato due volte. Perché succede e come progetto pagamenti in cui decide il server: webhook firmati, sblocchi idempotenti e flussi anche senza carta.

Reda BellasseryReda Bellassery· ·8 min di lettura
www.nawafiddz.com/#/public-courses/…
La pagina di un corso Nawafid in arabo con il riquadro del prezzo, il prezzo scontato in dinari e il pulsante di iscrizione

Punti chiave

  • Quando un cliente paga e non riceve nulla, la causa è quasi sempre la stessa: è l’app a decidere che il pagamento è avvenuto, invece del server che lo sente dal fornitore di pagamento.
  • La soluzione è fare in modo che solo un webhook firmato del fornitore di pagamento possa concedere l’accesso, e che l’app si limiti a leggere quel permesso.
  • Ogni passaggio che tocca i soldi deve essere idempotente: eseguirlo due volte ha lo stesso effetto che eseguirlo una volta, così un nuovo tentativo o un doppio tocco non sbloccano né contano mai due volte.
  • L’app può tornare in primo piano in qualsiasi momento, prima, durante o dopo l’arrivo del pagamento, quindi serve un’unica verifica chiamata da ogni via di rientro.
  • Dove non c’è un circuito di carte, il caricamento della ricevuta più un’approvazione umana che scrive l’iscrizione sul server è più lento, ma affidabile e verificabile.

Un cliente paga. La banca gli manda la notifica. Torna sulla tua app, e quello che ha comprato è ancora bloccato.

Allora scrive all’assistenza, magari su WhatsApp, con lo screenshot della notifica. Qualcuno del tuo team apre il pannello dei pagamenti, vede l’incasso e sblocca l’account a mano. Il giorno dopo succede di nuovo. E ogni tanto trovi il contrario: lo stesso cliente ha pagato due volte, oppure un ordine compare due volte nei tuoi numeri.

Ognuno di quei ticket ti costa due volte. Una in tempo di assistenza, l’altra in fiducia, perché un cliente che ha pagato e non ha ricevuto nulla non se lo dimentica.

Questo articolo è per i titolari di PMI e i fondatori che incassano tramite un’app o una piattaforma. Soprattutto se l’app è stata costruita in fretta o con strumenti di IA, e la parte dei pagamenti “più o meno funziona”.

Perché un cliente paga e non riceve l’accesso?

Perché è l’app a decidere che il pagamento è avvenuto, e l’app non sempre c’è per deciderlo. Nella maggior parte dei flussi rotti che vedo, l’accesso viene concesso quando il cliente torna su una schermata “pagamento riuscito”. Quella schermata è l’anello più debole di tutta la catena.

Pensa a cosa succede tra il momento in cui il cliente paga e il momento in cui quella schermata dovrebbe caricarsi:

  • Chiude la scheda. La pagina della banca ha detto “fatto”, perché aspettare il reindirizzamento?
  • Il telefono chiude l’app. Su mobile il checkout spesso si apre nel browser. Nel frattempo il sistema può chiudere l’app per liberare memoria.
  • Salta la connessione. Il pagamento è passato. La richiesta che doveva sbloccare l’accesso no.
  • Torna prima che il pagamento arrivi. L’app controlla, non trova ancora nulla e mostra “bloccato”. Nessuno ricontrolla.

I soldi erano veri ogni volta. Mancava un registro affidabile che dica “questo cliente possiede questo”. E quando quel registro lo scrive l’app, c’è un secondo problema, peggiore: se può scriverlo l’app, può scriverlo chiunque riesca a parlare con il tuo database. Ne ho parlato in perché le funzioni a pagamento finiscono sbloccate gratis.

Cosa vuol dire “il server è la fonte di verità”?

Vuol dire che solo il tuo backend decide chi ha pagato, e lo decide in base a quello che gli comunica il fornitore di pagamento, non a quello che riferisce l’app. L’app chiede. Non concede mai.

Un webhook di pagamento è un messaggio che il fornitore di pagamento invia direttamente al tuo server quando succede qualcosa, per esempio “questo checkout è stato pagato”. Non passa dal telefono del cliente, quindi arriva anche a telefono spento. È firmato, e il tuo server controlla la firma prima di fidarsi di un solo campo. Stripe, PayPal, Chargily e i fornitori seri funzionano così.

Quando è il webhook a scrivere il permesso, la schermata di conferma smette di contare. Diventa un messaggio gentile, non il momento in cui i soldi si trasformano in accesso.

L’app non deve mai decidere da sola di essere stata pagata. Deve aspettare che qualcuno glielo dica.

Come l’ho costruito in Belka

Belka Tech English è un’app di inglese professionale per lavoratori e studenti algerini, che ho costruito da solo. È pubblicata su Google Play. Il livello 0 è gratuito. I livelli da 1 a 5 si comprano in dinari, da 1.500 a 3.500 DZD ciascuno, oppure 10.000 DZD per tutto. Si paga con carta Dahabia tramite Chargily Pay.

Il checkout si apre nel browser di sistema e torna nell’app tramite deep link. Quindi la parte più importante della funzione è tutto quello che succede mentre la mia app non è sullo schermo.

La scala dei livelli, l’offerta di sblocco e la schermata di pagamento con carta Dahabia o codice promo. Il lucchetto è solo un disegno: decide il database.
La scala dei livelli, l’offerta di sblocco e la schermata di pagamento con carta Dahabia o codice promo. Il lucchetto è solo un disegno: decide il database.
La scala dei livelli, l’offerta di sblocco e la schermata di pagamento con carta Dahabia o codice promo. Il lucchetto è solo un disegno: decide il database.
La scala dei livelli, l’offerta di sblocco e la schermata di pagamento con carta Dahabia o codice promo. Il lucchetto è solo un disegno: decide il database.
  1. Tocco.Lo studente sceglie un livello. L’app chiede a una Edge Function di Supabase, un piccolo pezzo di codice sul server, di creare un checkout Chargily. Prezzi e sconto di lancio vengono applicati sul server.
  2. Pagamento.Il checkout si apre nel browser di sistema. Dahabia o carta, in dinari.
  3. Webhook.Chargily invia a Supabase un evento checkout.paid firmato. Il server controlla la firma HMAC e scrive il permesso.
  4. Rientro.Deep link con l’app aperta, avvio da zero, o lo studente che semplicemente torna sull’app. Quello che succede per primo fa partire un’unica verifica.
  5. Conferma.L’app controlla la propria riga di accesso ogni 1,5 secondi, per un massimo di 20 secondi, finché non compare il permesso scritto dal server. Poi sblocca.

Il passaggio 4 è quello in cui la maggior parte delle app perde la vendita. L’app può tornare prima, durante o dopo l’arrivo del webhook. Su Android può perfino essere avviata da zero dal deep link. Per questo Belka ha tre rilevatori separati. Uno ascolta il deep link con l’app aperta. Uno legge il link che ha avviato un’app chiusa. Uno nota il momento in cui l’app torna in primo piano. Tutti e tre chiamano la stessa verifica, e quella verifica si può eseguire più volte senza danni.

All’inizio non era così. Nella prima versione era l’app a scrivere lo sblocco del livello. Ho spostato ogni permesso sul server e ho tolto all’app qualsiasi accesso in scrittura. Ora l’accesso arriva solo dal webhook verificato o dalla funzione dei codici promo. Nel caso studio trovi il flusso di pagamento completo e le regole sugli accessi.

Perché l’idempotenza evita sblocchi doppi e incassi contati due volte

Idempotente significa che eseguire lo stesso passaggio due volte ha lo stesso effetto che eseguirlo una volta. Nei pagamenti serve ovunque, perché tutto intorno si ripete. I fornitori rimandano il webhook se il tuo server risponde lentamente. I clienti toccano due volte. I telefoni ripetono le richieste dopo un calo di connessione.

Ecco come si traduce nei miei progetti:

  • La verifica di Belka. Tre vie di rientro possono scattare insieme. Portano tutte a una sola routine che legge il permesso e basta, quindi eseguirla tre volte non cambia nulla.
  • I codici promo di Belka. Una sola funzione del database controlla il codice, lo consuma e concede l’accesso in un’unica transazione, cioè un gruppo di scritture che avvengono tutte o nessuna. Due tocchi non possono usare lo stesso codice due volte.
  • Il registro di cassa di Al Burhan. In Al Burhan ogni scrittura finanziaria porta un ID univoco creato sul dispositivo. Se una richiesta viene ripetuta dopo un calo di connessione, la stessa vendita non può essere contata due volte.

Con le carte vale lo stesso principio dal lato del fornitore. Per esempio, Stripe accetta una chiave di idempotenza quando crei un addebito, così una richiesta ripetuta non ne crea un secondo. E dal tuo lato, salva l’ID del pagamento del fornitore con un vincolo di unicità: la seconda copia di un webhook viene semplicemente ignorata.

E se il tuo cliente paga con bonifico, non con carta?

Allora costruisci il flusso che le persone usano davvero. In Algeria la maggior parte degli studenti non può pagare con carta, quindi Nawafid, un marketplace di corsi online che ho progettato, costruito e gestisco, accetta bonifici bancari e postali al posto della carta.

www.nawafiddz.com/#/public-courses
Il catalogo di Nawafid. Ogni corso ha i propri dati CCP o BaridiMob, così l’insegnante può essere pagato sul proprio conto.
Il catalogo di Nawafid. Ogni corso ha i propri dati CCP o BaridiMob, così l’insegnante può essere pagato sul proprio conto.
  1. Lo studente paga con bonifico CCP o BaridiMob ai dati indicati su quel corso.
  2. Carica lo screenshot della ricevuta. Finisce in una coda di attesa con corso, importo e orario.
  3. Un insegnante o un membro dello staff la approva. È l’approvazione, non il caricamento, a creare l’iscrizione e a registrare la ripartizione della commissione tra insegnante e piattaforma.

Il principio resta lo stesso. Caricare una ricevuta chiede l’accesso. Solo un’approvazione lo scrive. E siccome iscrizione e commissione vengono scritte insieme, l’incasso lordo dell’amministratore e il netto dell’insegnante tornano corso per corso.

2.150+studenti registrati
760+iscrizioni ai corsi approvate
69corsi di 13 insegnanti

Da quella coda sono passate centinaia di bonifici. In Italia molte PMI incassano ancora con bonifico, per esempio per corsi, consulenze e servizi tra aziende. Lo stesso schema funziona anche per te: il cliente carica la contabile, qualcuno la approva, e solo allora il sistema scrive l’accesso.

Quanto costa, onestamente

Farlo bene non è gratis. Ecco i compromessi che ho accettato, presi direttamente dai miei casi studio:

  • Lo sblocco non è istantaneo. In Belka l’app aspetta un webhook che non controlla. Se dopo 20 secondi non è arrivato, lo studente tocca di nuovo “Verifica”.
  • Il controllo periodico è semplice, non elegante. Ho scelto di controllare ogni 1,5 secondi invece di una connessione in tempo reale. Spreca qualche richiesta, e il ciclo può sopravvivere alla schermata. Entrambe le cose sono scritte tra i limiti noti.
  • Una persona nel processo. Su Nawafid una persona controlla ogni bonifico. Per i bonifici è giusto così, ma non c’è ancora una riconciliazione automatica.

Nessuno di questi compromessi fa perdere una vendita. Uno sblocco lento è fastidioso. Un pagamento perso è una richiesta di rimborso e una recensione negativa.

Una checklist da usare oggi

Apri la tua app e il pannello dei pagamenti uno accanto all’altro e passa questa tabella.

SintomoCausa probabileSoluzione
Ha pagato, ma è ancora bloccatoL’accesso viene concesso dalla pagina di confermaConcedere l’accesso solo da un webhook verificato sul server
Si sblocca solo riaprendo l’appNessun controllo quando l’app rientraUn’unica verifica, chiamata da ogni via di rientro
Lo stesso ordine contato due volteI webhook ripetuti vengono elaborati due volteVincolo di unicità sull’ID del pagamento del fornitore
Cliente addebitato due volteUna richiesta ripetuta crea un nuovo addebitoChiave di idempotenza quando si crea l’addebito
Codice promo usato due volteControllo e consumo avvengono in passaggi separatiValidare, consumare e concedere in un’unica transazione
L’assistenza sblocca account a manoNessun registro affidabile di chi ha pagatoUna tabella degli accessi che solo il server può scrivere

Se ne riconosci tre o più, il flusso di pagamento va ricostruito nel suo nucleo, non rattoppato ancora. Succede spesso nelle app generate con strumenti di IA. Ho scritto anche quali interventi servono di solito a un’app costruita con l’IA prima di andare in produzione.

Cosa fare adesso

Se i clienti pagano e poi scrivono all’assistenza, comincia contando quei ticket per un mese. Quel numero è quanto ti costa il bug.

Poi guarda i due casi studio. Belka mostra il flusso con carta, webhook, verifica idempotente e rientro da qualsiasi stato. Nawafid mostra un flusso con bonifico, approvazione umana e ripartizione delle commissioni.

Se vuoi che guardi il tuo, scopri cosa costruisco oppure mandami una breve descrizione di come funzionano oggi i tuoi pagamenti. Puoi scrivermi in italiano o in inglese. Ti rispondo con qualche domanda, e prima di iniziare ricevi per iscritto ambito, tempi e prezzo.

Sugli screenshot: le schermate del telefono vengono dalla build pubblicata di Belka, eseguita su un simulatore iPhone. Le immagini desktop sono catture del sito Nawafid online.

Domande frequenti

Perché il mio cliente ha pagato ma non ha ricevuto l’accesso?

Di solito perché l’accesso viene concesso dall’app quando il cliente torna dal checkout. Se chiude la scheda, il telefono chiude l’app o salta la connessione, quel momento non arriva mai. Il pagamento è reale, ma nessuno ha scritto il permesso. La soluzione è concedere l’accesso da un webhook firmato sul server, non dalla pagina di conferma.

Che cos’è un webhook di pagamento?

Un webhook è un messaggio che il fornitore di pagamento invia direttamente al tuo server quando succede qualcosa, per esempio un checkout pagato. Arriva al backend anche se il telefono del cliente è spento. La sua firma va sempre verificata, così nessuno può falsificarlo.

Come evito addebiti doppi e sblocchi doppi?

Rendi idempotente ogni passaggio legato ai soldi. Usa una chiave di idempotenza quando crei l’addebito, salva l’ID del pagamento del fornitore con un vincolo di unicità e concedi l’accesso in un’unica transazione del database. Un webhook ripetuto o un secondo tocco trovano il lavoro già fatto.

Posso incassare anche senza carta, per esempio con bonifico?

Sì. Su Nawafid gli studenti pagano con bonifico CCP o BaridiMob e caricano la ricevuta. Lo staff la approva, e l’approvazione scrive l’iscrizione e la ripartizione della commissione. Serve una persona nel processo, ma rispecchia il modo in cui i soldi si muovono davvero in quel mercato.

Quanto costa sistemare un flusso di pagamento che non funziona?

Dipende dal codice e dal fornitore, per questo ambito, tempi e prezzo vengono concordati per iscritto prima di iniziare. Il lavoro tipico è sempre lo stesso: spostare lo sblocco sul server, aggiungere verifica della firma e idempotenza, e una sola verifica che l’app chiama quando rientra.
Reda Bellassery
Reda BellasseryFondatore di VYNORO · Sviluppatore full-stack e IA a Macerata

Sviluppo agenti IA, applicazioni web e app mobile per le aziende e gestisco la mia agenzia, Barmjli. Qui scrivo di quello che costruisco e di cosa mi ha insegnato.

Continua a leggere