VibeFox Quickpay for PrestaShop — Guida

Requisiti

PrestaShop: 8.0 – 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Account Quickpay: ti servono due valori dal gestore Quickpay: la chiave API di un utente API (per creare pagamenti, acquisire e rimborsare) e la chiave privata dell'account (per verificare la firma dei callback di Quickpay). Non occorre configurare altro in Quickpay. Il tuo negozio deve essere raggiungibile da internet, senza protezione con password, perché i callback di Quickpay possano arrivare.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Quickpay Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Incolla la chiave API e la chiave privata dal gestore Quickpay e fai clic su Test API key (vedi Configurazione).

5. Scegli la modalità di acquisizione e lo stato dell'ordine dopo il pagamento, attiva Enable/Disable e fai clic su Save. Mentre il tuo account Quickpay è in modalità test, attiva Test payments e fai un pagamento con una carta di prova Quickpay.

All'installazione il modulo crea uno stato d'ordine, Quickpay payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, i Paesi e i gruppi di clienti. Il modulo è collegato ai Paesi attivi al momento dell'installazione. Puoi modificarli tutti in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Finché la chiave API e la chiave privata non sono salvate, la pagina mostra Quickpay richiede la configurazione: inserisci la chiave API e la chiave privata. Finché entrambe non sono salvate, il metodo di pagamento è nascosto al checkout. Mentre Test payments è attivo, la pagina ti ricorda di disattivarlo quando il tuo account Quickpay va in produzione.

Quickpay

Enable/Disable: Enable Quickpay attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Quickpay. Obbligatorio: un titolo vuoto non viene salvato.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card or MobilePay on the Quickpay payment page.

Credenziali API Quickpay

Nel gestore Quickpay (manage.quickpay.net) apri Settings > Integration. Copia la chiave API di un utente API (Settings > Users) e la chiave privata dell'account.

Callback URL: mostra l'URL di callback del tuo negozio. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay lo richiama dopo ogni operazione di pagamento (autorizzazione, acquisizione, rimborso, annullamento). Viene inviato automaticamente con ogni pagamento, quindi non occorre configurare nulla in Quickpay.

API key: la chiave API di un utente API Quickpay. Serve per creare pagamenti, acquisire e rimborsare.

Private key: la chiave privata dell'account. Serve per verificare la firma (HMAC-SHA256) dei callback di Quickpay. Senza di essa nessun pagamento può essere confermato e i callback vengono rifiutati.

Le chiavi salvate non vengono più mostrate. Il campo resta vuoto e mostra Salvata — lasciala vuota per mantenerla. Inserisci un nuovo valore solo per modificarla.

Cancella segreti salvati: seleziona API key o Private key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Test payments: accetta i pagamenti effettuati con le carte di prova Quickpay. Quickpay non ha un sandbox separato: mentre il tuo account Quickpay è in modalità test, i pagamenti vengono effettuati con carte di prova e contrassegnati come tali. Attivalo solo durante i test. Quando è disattivato, un pagamento di prova non segna mai un ordine come pagato. Quando è attivo, il checkout mostra Modalità test: sono accettate le carte di prova Quickpay. sotto il metodo di pagamento. Predefinito: disattivato.

Test API key: questo pulsante verifica la chiave inserita nel campo API key (o quella salvata, se il campo è vuoto) con una richiesta autenticata a Quickpay, senza salvarla. Risponde Connessione riuscita — la chiave API è valida., Quickpay ha rifiutato la chiave API., La chiave API non è configurata. oppure Connessione non riuscita: seguito dal motivo.

Pagamento

Capture: quando il denaro viene prelevato dalla carta.

Order status after payment: lo stato dell'ordine una volta che Quickpay ha confermato il pagamento acquisito.

Avanzate

Debug log: scrive in logs/qpg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi, come i callback rifiutati e gli errori dell'API Quickpay, vengono sempre registrati. Attivalo per registrare anche i dettagli di ogni richiesta e callback. Le chiavi API, i dati della carta e i dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.

Delete data: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I dati degli ordini (pagamenti Quickpay, rimborsi, note) e lo stato d'ordine Quickpay payment on hold vengono sempre conservati. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Quickpay, con un'icona di carta) e conferma. Il modulo crea un pagamento Quickpay per il carrello nella valuta del carrello e un link di pagamento per il totale del carrello, e invia il cliente alla finestra di pagamento Quickpay. A questo punto l'ordine non esiste ancora. Il cliente paga lì con uno dei metodi attivati nella tua finestra di pagamento Quickpay. L'e-mail del cliente viene passata a Quickpay. La finestra di pagamento si apre nella lingua del cliente quando Quickpay la offre (danese, tedesco, inglese, spagnolo, finlandese, francese, italiano, olandese, norvegese, polacco, svedese), altrimenti in inglese.

Dopo il pagamento, il cliente torna al tuo negozio. Il ritorno in sé non segna nulla come pagato. L'ordine viene segnato come pagato solo dopo la conferma di Quickpay: il callback firmato crea l'ordine quando l'importo acquisito e la valuta corrispondono al carrello. Il cliente vede poi la normale pagina di conferma dell'ordine. Con Authorize only, l'ordine viene creato in Quickpay payment on hold e tu acquisisci il pagamento più tardi. Se il callback non è ancora arrivato quando il cliente torna, una pagina Payment confirmation mostra Il tuo pagamento è in fase di conferma da parte di Quickpay. Riceverai un'e-mail non appena l'ordine sarà confermato. con i pulsanti Check again e Back to checkout.

Se il cliente annulla nella finestra di pagamento, il link di pagamento viene eliminato in Quickpay e il cliente torna al checkout con il messaggio Il pagamento è stato annullato. Puoi riprovare o scegliere un altro metodo di pagamento. Se la carta è stata rifiutata, il messaggio è Il pagamento non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Il carrello viene conservato. Un nuovo tentativo riutilizza il pagamento Quickpay del carrello con un nuovo link, quindi un vecchio link non può mai essere pagato in parallelo. Mentre un pagamento del carrello è autorizzato e attende l'acquisizione, non viene avviato un secondo pagamento; il cliente vede la pagina Payment confirmation.

Se il pagamento non può essere avviato, il cliente resta al checkout con il messaggio Impossibile avviare il pagamento Quickpay. Riprova o scegli un altro metodo di pagamento. Il motivo tecnico viene scritto nel registro. Se mancano le chiavi, il messaggio è Quickpay non è disponibile al momento. Scegli un altro metodo di pagamento.

Il callback funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per Paese del tuo negozio.

Il modulo accetta solo pagamenti una tantum. Non prevede abbonamenti o pagamenti ricorrenti, carte salvate, acquisizione parziale, non invia righe di carrello o fattura a Quickpay e non ha metodi separati MobilePay, Apple Pay o Klarna: il cliente sceglie tra i metodi della tua finestra di pagamento Quickpay.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Quickpay e non ha pagato, la carta è stata rifiutata, oppure il pagamento è autorizzato e attende l'acquisizione automatica. Esiste solo il carrello.

Payment accepted or Delivered: Quickpay ha confermato il pagamento acquisito con l'importo e la valuta corretti. Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID pagamento Quickpay come ID transazione, e una nota mostra il pagamento (contrassegnato TEST per i pagamenti di prova).

Quickpay payment on hold: il pagamento è solo autorizzato e attende Capture Quickpay payment; oppure Quickpay ha segnalato un importo o una valuta diversi dal totale dell'ordine (ad esempio, il carrello è stato modificato dopo l'avvio del pagamento, o nel gestore Quickpay è stato acquisito un importo diverso); oppure l'acquisizione automatica non è riuscita e l'importo è ancora solo riservato. La nota lo spiega. Quando il denaro è stato acquisito con un importo diverso, il pagamento viene registrato sull'ordine con l'importo acquisito da Quickpay.

Canceled: hai annullato l'ordine, oppure il pagamento di un ordine in attesa è stato annullato nel gestore Quickpay.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.

Un pagamento che arriva per un ordine già pagato, annullato o rimborsato non modifica l'ordine. Una nota ti chiede di verificare il pagamento nel gestore Quickpay, ad esempio per rimborsare un pagamento doppio.

Quando annulli un ordine non pagato, il suo link di pagamento viene eliminato in Quickpay. Annullare un ordine autorizzato non libera automaticamente l'importo riservato: una nota ti ricorda di annullare il pagamento nel gestore Quickpay; altrimenti la riserva termina alla scadenza dell'autorizzazione.

Blocco Quickpay

La pagina dell'ordine mostra un blocco Quickpay payment con l'ID pagamento, lo stato del pagamento, l'importo e l'importo rimborsato, un badge Test payment per i pagamenti di prova, l'elenco di tutti i pagamenti Quickpay del carrello (quando ce n'è più di uno), la cronologia dei rimborsi e le Quickpay notes dell'ordine. Acquisizione e rimborsi richiedono il diritto di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario.

Acquisizione

Con Authorize only, fai clic su Capture Quickpay payment nel blocco Quickpay e conferma Acquisire l'intero totale dell'ordine tramite Quickpay? Viene acquisito l'intero totale dell'ordine; l'acquisizione parziale non è disponibile. Se Quickpay conferma subito, l'ordine passa allo stato di Order status after payment. Altrimenti una nota indica che l'acquisizione è stata richiesta, e l'ordine viene segnato come pagato quando il callback di Quickpay lo conferma. Un'acquisizione rifiutata viene mostrata nel blocco e annotata sull'ordine.

Rimborsi

Nel blocco Quickpay inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Quickpay. Conferma la domanda Rimborsare questo importo tramite Quickpay? Non è possibile annullare l'operazione. Sono supportati rimborsi totali e parziali per i pagamenti acquisiti. I rimborsi vengono effettuati nell'importo e nella valuta acquisiti da Quickpay, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Quickpay elabora i rimborsi in modo asincrono: la cronologia dei rimborsi mostra requested, e il callback lo imposta su confirmed oppure failed e aggiunge l'esito alle note. Se Quickpay rifiuta subito il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non modifica lo stato. Un pagamento autorizzato mai acquisito non può essere rimborsato; annullalo nel gestore Quickpay.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non rimborsano denaro tramite Quickpay.

I rimborsi effettuati direttamente nel gestore Quickpay vengono solo aggiunti alle note. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Quickpay Gateway è il primo blocco di Modules > Module Manager > VibeFox Quickpay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: presta-payment-quickpay e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono cambiare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Quickpay non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e acquisizione e rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Quickpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che siano salvate sia API key sia Private key. Senza entrambe le chiavi il metodo viene nascosto. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il Paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il callback di Quickpay non ha raggiunto il tuo negozio oppure è stato rifiutato. Verifica che il negozio sia raggiungibile da internet (senza protezione con password) e che Private key sia la chiave privata dello stesso account Quickpay. I callback rifiutati vengono sempre scritti nel registro nella pagina del modulo. Attiva Debug log per vedere ogni callback.

Il registro mostra Callback rejected: invalid checksum.: la chiave privata nelle impostazioni non appartiene all'account che ha inviato il callback. Copiala di nuovo da Settings > Integration nel gestore Quickpay.

Il registro mostra Callback rejected: the private key is not configured.: inserisci la chiave privata. I callback non vengono mai accettati senza di essa.

Il registro mostra Callback: no cart found for payment …: il callback appartiene a un pagamento Quickpay che questo negozio non ha creato, ad esempio un pagamento effettuato al di fuori di PrestaShop.

Il registro mostra Could not lock the cart oppure Cannot create the order: un altro callback dello stesso carrello era in fase di applicazione in quel momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). Il callback riceve una risposta di errore, quindi Quickpay lo invia di nuovo.

Un pagamento di prova non ha segnato l'ordine come pagato: Test payments è disattivato. Il registro (e la nota, se l'ordine esiste) indica che il pagamento di prova non è stato accettato. Attivalo durante i test e disattivalo quando il tuo account va in produzione.

L'ordine è in Quickpay payment on hold dopo il pagamento: leggi le note nel blocco Quickpay. Il pagamento potrebbe essere solo autorizzato in attesa di Capture Quickpay payment, l'importo o la valuta pagati potrebbero non corrispondere all'ordine, oppure l'acquisizione non è riuscita. Acquisisci, evadi l'ordine o rimborsa il pagamento.

Test API key mostra «Quickpay ha rifiutato la chiave API.»: la chiave è errata o appartiene a un utente senza accesso API. Copia la chiave API di un utente API dal gestore Quickpay.

Il cliente vede «Impossibile avviare il pagamento Quickpay.»: guarda il campo Log nella pagina del modulo. Mostra l'errore di Quickpay, ad esempio una valuta che il tuo account Quickpay non accetta.

Il rimborso non riesce: l'ordine deve avere un pagamento Quickpay acquisito. Il messaggio Il pagamento Quickpay di questo ordine non è stato acquisito — non c'è nulla da rimborsare. significa che il pagamento è solo autorizzato; acquisiscilo o annullalo nel gestore Quickpay. Importo di rimborso non valido: massimo … significa che l'importo supera ciò che resta del pagamento acquisito.

Gli sviluppatori possono modificare i parametri del link di pagamento Quickpay con l'hook actionQpgQuickpayLinkData.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Quickpay Gateway e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, le impostazioni del gateway e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I pagamenti Quickpay, i rimborsi e lo stato d'ordine Quickpay payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono comunque essere rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

Quickpay è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Quickpay né approvato da Quickpay.