Integrare Payora in un sito PHP personalizzato

Come collegare Payora a un sito PHP personalizzato

Se il tuo sito è realizzato interamente in PHP, il processo è semplice: crei un pagamento, reindirizzi il cliente a Payora e poi riporti l’esito nel tuo sistema di ordini. Non serve WooCommerce. E nemmeno una giungla di plugin. Se ti stai chiedendo come integrare Payora in un sito PHP, questa guida ti accompagna attraverso i passaggi essenziali.

Questa guida spiega come collegare Payora a un sito PHP personalizzato senza trasformare il checkout in un progetto scientifico. Vedrai esattamente dove il codice PHP deve avviare il pagamento, dove deve ricevere la risposta e dove la tua app deve stabilire se l’ordine è pagato, in sospeso o non riuscito.

1. Scegli il modello di integrazione per un sito PHP personalizzato

Per prima cosa, decidi che cosa vuoi realizzare: un semplice link di pagamento, una richiesta di pagamento lato server o un flusso completo con tracciamento degli ordini. Non sono la stessa cosa. Un sito di donazioni composto da una sola pagina può cavarsela con un link di pagamento; un negozio con 20 prodotti, invece, di solito deve creare l’ordine lato server prima che il cliente lasci il sito.

Per un sito PHP personalizzato, il modello più lineare è spesso questo: crei l’ordine nel tuo sistema, crei il pagamento Payora tramite PHP, reindirizzi il cliente e poi gestisci il ritorno e la conferma del server. In questo modo hai una registrazione dell’ordine prima ancora che il denaro venga trasferito. Inoltre, il carrello e la logica delle fatture restano nella tua app, dove devono stare: un approccio pratico per gestire i pagamenti online con PHP personalizzato.

Se il checkout è molto semplice, potrebbe bastarti reindirizzare il cliente a una pagina di pagamento ospitata da Payora. Se invece hai bisogno di voci di dettaglio, note del cliente o ID degli ordini, il codice PHP dovrebbe inviare questi dati prima del reindirizzamento. Semplice, ma non semplicistico.

Un esempio pratico: un’agenzia digitale che vende un pacchetto di manutenzione in 3 fasi può creare l’ordine in PHP, aggiungere l’indirizzo email del cliente e inviarlo a Payora con il riferimento della fattura. Un progetto amatoriale che vende una sola chiave di licenza potrebbe aver bisogno soltanto del link di pagamento e di una pagina di ritorno. La differenza sta nella quantità di informazioni di stato da conservare, non nella quantità di codice.

2. Definisci pagine, endpoint e flusso delle sessioni

Prima di scrivere codice, elenca le pagine. Te ne servono almeno tre: una pagina di checkout, una pagina di ritorno e un endpoint server per confermare il pagamento. Se salti questa fase, finirai per indovinare quale richiesta ha modificato l’ordine. E gli errori di valutazione costano.

Usa una normale sessione PHP per gestire il flusso nel browser, ma non fidarti solo della sessione. I dati della sessione possono andare persi se il cliente cambia dispositivo, chiude la scheda o torna da Payora in un secondo momento. Conserva anche l’ID dell’ordine nel database: così il codice PHP potrà ritrovare la transazione anche se la sessione del browser non è più disponibile.

Un flusso tipico è questo:

• La pagina di checkout raccoglie prodotto, email e quantità.
• PHP crea un ordine locale con stato in sospeso.
• PHP reindirizza il cliente a Payora.
• Payora riporta il browser all’URL di ritorno.
• Il server verifica lo stato del pagamento prima di contrassegnare l’ordine come pagato.

Questo flusso tiene separati il ritorno del browser e la situazione reale lato server. Ed è giusto così. Il browser può dirti che cosa ha visto il cliente; spetta al server stabilire che cosa significa per l’ordine.

Una piccola accortezza può farti risparmiare ore di lavoro in seguito: salva il riferimento del pagamento Payora accanto all’ID dell’ordine non appena crei il pagamento. Se aspetti che il cliente venga reindirizzato, un errore di rete o un aggiornamento frettoloso della pagina potrebbero lasciarti con un ordine ma senza il riferimento Payora. A quel punto, in produzione, dovrai improvvisarti investigatore.

3. Prepara un livello PHP essenziale per le richieste di pagamento

Tieni il codice dei pagamenti fuori dai template. Basta una piccola classe PHP o una funzione di supporto: un metodo può creare il payload, un altro inviare la richiesta HTTP e un terzo analizzare la risposta. Questa separazione è importante, perché la logica dei pagamenti cambia più spesso del markup delle pagine.

Per esempio, la funzione di supporto può ricevere un array con amount, currency, order_id e return_url, poi aggiungere le credenziali Payora lette dalle variabili d’ambiente. La pagina di checkout non dovrebbe mai sapere dove si trova il token API: deve sapere solo quale pulsante è stato premuto.

Ecco la struttura della logica, non un’implementazione completa:

1. Leggi l’ordine dal database.
2. Prepara un array per la richiesta a Payora.
3. Invia la richiesta con cURL o un client HTTP simile.
4. Salva il riferimento del pagamento restituito da Payora.
5. Reindirizza il cliente all’URL di pagamento Payora.

Mantieni questa funzione di supporto semplice e lineare. Il codice essenziale è più facile da testare e ha meno probabilità di rompersi quando cambi il prezzo di un prodotto o aggiungi un secondo modulo di checkout il mese prossimo.

Se la tua app dispone già di un livello di astrazione per i pagamenti, usalo. Altrimenti, crea un file e dagli un nome chiaro, per esempio PayoraClient.php. Quel file dovrebbe contenere le credenziali, le chiamate API e l’analisi delle risposte. Nient’altro: niente HTML, niente CSS, niente messaggi di ringraziamento.

4. Reindirizza il cliente a Payora dal checkout personalizzato

Una volta creato l’ordine locale, invia la richiesta di pagamento a Payora e reindirizza il cliente alla relativa pagina di pagamento. Il passaggio deve avvenire solo dopo che il server ha salvato l’ordine, perché il cliente potrebbe chiudere la scheda non appena parte il reindirizzamento.

Invia solo i dettagli dell’ordine che ti servono davvero. Di solito sono l’ID dell’ordine, l’importo, la valuta e l’email del cliente. Puoi aggiungere metadati come il nome del prodotto o l’ID dell’account interno, ma non riversare nella richiesta ogni campo del database solo perché è disponibile. I dati superflui possono creare confusione quando il personale dell’assistenza confronta le registrazioni.

Un checkout personalizzato spesso usa un modulo POST con un pulsante «Paga ora». Il modulo invia i dati al tuo endpoint PHP, che crea il pagamento Payora e poi risponde con un reindirizzamento. Il cliente non vede la risposta dell’API: vede solo Payora.

Un’avvertenza: non fidarti degli importi calcolati sul client. Se la pagina del prodotto indica 49 $ ma il browser invia 39 $, il server deve rifiutare la discrepanza. La richiesta di pagamento deve basarsi sul totale dell’ordine calcolato lato server, non sul valore nascosto nel modulo. Questa regola è sempre importante.

Per una panoramica più ampia sui modelli di configurazione dei pagamenti, la guida ai gateway di pagamento in criptovalute per l’e-commerce offre un utile contesto senza ripetere qui i dettagli del flusso PHP.

5. Ricevi e verifica l’esito del pagamento nella tua app

L’URL di ritorno nel browser è utile, ma non è l’ultima parola. Può indicare che la pagina di pagamento è stata visitata e trasmettere uno stato, ma la tua app PHP dovrebbe considerare quell’esito provvisorio finché il server non lo conferma. In sospeso non significa pagato.

Progetta la pagina di ritorno in modo che gestisca tre casi: pagamento riuscito, in sospeso e non riuscito. Se Payora indica che il pagamento è riuscito, mostra una pagina di ringraziamento e informa l’utente che l’ordine è in fase di conferma. Se è in sospeso, dillo chiaramente. Se non è riuscito, invita il cliente a riprovare senza perdere la registrazione dell’ordine. Messaggi chiari riducono le richieste all’assistenza.

Una regola utile: la pagina di ritorno non dovrebbe mai creare da sola un ordine pagato. Dovrebbe limitarsi a mostrare lo stato attuale e, se serve, offrire un link alla pagina dell’ordine. Il database va aggiornato dopo la verifica, non dopo un reindirizzamento del browser. Questa distinzione protegge dagli aggiornamenti accidentali ripetuti.

Mantieni l’endpoint di ritorno abbastanza semplice da capire a colpo d’occhio. Se riceve un riferimento di pagamento Payora, cercalo. Se il riferimento manca, registra la richiesta nel log e fermati. Se l’ordine risulta già pagato, mostra un messaggio cordiale e non modificare nulla. È così che i flussi idempotenti gestiscono serenamente gli aggiornamenti ripetuti della pagina.

Per i team che vogliono confrontare anche le soluzioni di checkout, l’articolo su come accettare pagamenti in criptovalute offre indicazioni utili sulla fatturazione, soprattutto se vendi servizi con fatture ricorrenti o approvazioni manuali.

6. Verifica la transazione sul server prima di contrassegnare l’ordine come pagato

Questo è il passaggio più sicuro. La tua app PHP dovrebbe interrogare Payora dal server e confermare lo stato della transazione prima di impostare l’ordine come pagato. I reindirizzamenti del browser possono omettere informazioni; i controlli lato server non si preoccupano che il cliente abbia chiuso la scheda, aggiornato la pagina due volte o usato un secondo dispositivo.

Usa il riferimento del pagamento Payora che hai salvato in precedenza e richiedi lo stato aggiornato della transazione. Per verificare lo stato di un pagamento Payora, confronta lo stato restituito con quello richiesto per procedere all’evasione dell’ordine. Se la transazione è completata o confermata, aggiorna l’ordine. Se è in sospeso, lascialo in sospeso. Se non è riuscita o è stata annullata, non modificare l’ordine.

Una nota a margine: è proprio qui che molti siti PHP personalizzati si lasciano andare. Si fidano della pagina di ritorno perché è più rapida da implementare. Sì, è più veloce. Ma non più sicuro. Una verifica di 5 secondi vale sempre più di una lunga catena di email con l’assistenza.

Se Payora fornisce un callback firmato o un meccanismo di conferma server-to-server, usalo insieme alla verifica dello stato. Avrai così due controlli: uno nel flusso del cliente e uno nel flusso del server. Se hai bisogno di una procedura dettagliata per verificare la firma, consulta la guida su come testare un pagamento in criptovaluta: illustra il rigore di convalida che dà i suoi frutti prima del lancio.

Contrassegna l’ordine come pagato solo dopo la conferma del server. Non perché lo dice il cliente. Non perché lo dice il browser. Il database deve riflettere lo stato del pagamento confermato da Payora, perché è quello di cui si fideranno in seguito i team che gestiscono l’evasione degli ordini e la contabilità.

7. Salva i dati del pagamento e gestisci gli invii duplicati

Salva nel database il riferimento della transazione Payora, l’ID dell’ordine locale, l’importo, la valuta e lo stato finale. Se possibile, esegui tutto con un’unica scrittura. Se un cliente ti scrive «Ho pagato due volte», vorrai trovare una registrazione chiara, non tre aggiornamenti incompleti.

Gli invii duplicati si verificano per ragioni comuni: il cliente fa clic due volte, usa il pulsante Indietro oppure il browser ripete la richiesta. Il codice PHP dovrebbe rilevare se l’ordine ha già un riferimento Payora e impedire la creazione di un secondo pagamento per lo stesso ordine, a meno che il primo non sia fallito o scaduto. Questo è il principio fondamentale dell’idempotenza.

Una regola semplice funziona bene: un ordine locale, una transazione Payora attiva. Se arriva una seconda richiesta per lo stesso ordine mentre la prima è ancora in sospeso, mostra il link di checkout Payora già esistente anziché crearne uno nuovo. Se l’ordine è già stato pagato, non fare nulla. Senza rumore: anche questo è un vantaggio.

Usa nomi specifici per le colonne del database. Per esempio, crea payora_reference, payment_status, paid_at e last_checked_at. Questi campi sono utili per l’assistenza, la contabilità e il debugging. Se in seguito dovrai riconciliare un pagamento, potranno rispondere alla maggior parte delle domande senza costringerti a passare un’ora a cercare nei log.

Se stai creando un flusso per le fatture dei clienti anziché per il checkout di un negozio, può esserti utile anche l’articolo sui gateway di pagamento in criptovalute per freelance, soprattutto per la logica di registrazione dei dati, quando i numeri delle fatture contano più dei carrelli.

8. Testa l’intero flusso su una copia di staging del sito

Prima di andare online, clona il sito in un ambiente di staging e testa l’intera sequenza: creazione dell’ordine, reindirizzamento a Payora, pagina di ritorno, verifica lato server e gestione dei doppi clic. Se testi solo il reindirizzamento, hai verificato un terzo del problema.

Esegui almeno questi controlli:

• Crea un nuovo ordine e verifica che venga generata la richiesta di pagamento Payora.
• Aggiorna la pagina di ritorno 2 volte e verifica che l’ordine non venga modificato di nuovo.
• Invia due volte il modulo di checkout e controlla che esista una sola transazione attiva.
• Forza un esito in sospeso o non riuscito e verifica che l’ordine rimanga non pagato.
• Controlla che il riferimento Payora salvato corrisponda a quello nel database.

Prova il flusso con la stessa versione di PHP e la stessa configurazione del server che userai in produzione. Un flusso che funziona sul tuo portatile può non funzionare su un server di produzione con una configurazione SSL più rigida o impostazioni cURL diverse. Non è raro: succede.

Un’ultima verifica pratica: apri l’ordine in una finestra di navigazione in incognito, completa il pagamento e poi apri lo stesso URL di ritorno da un secondo browser. La tua app non dovrebbe aggiornare una seconda volta lo stato del pagamento. Se succede, correggi il problema prima del lancio. Senza eccezioni.

Per i team che offrono checkout in USDC insieme ad altri metodi di pagamento, le indicazioni in come accettare pagamenti in USDC possono aiutarti a confrontare le aspettative dei clienti prima di portare il flusso PHP in produzione.

Quest’ultimo controllo è fondamentale: lo stesso ordine deve superare un reindirizzamento, un aggiornamento della pagina e una conferma del server senza perdere la sincronizzazione. Se ci riesce, il checkout PHP personalizzato è pronto per il primo pagamento in produzione.