VibeFox Peach Payments for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione OpenSSL (usata per decrittare i webhook). Senza di esse il modulo non si installa.

Valuta: la valuta del carrello deve essere ZAR, KES o MUR. Per i carrelli in altre valute il metodo di pagamento viene nascosto. La pagina delle impostazioni ti avvisa quando la valuta predefinita del negozio non è una di queste.

Account Peach Payments: ti servono le credenziali della Card API del tuo account Peach Payments: l'Entity ID e l'Access Token. Le credenziali di test si ottengono dal pannello sandbox di Peach Payments, quelle live dal pannello di Peach Payments; sono diverse. Per i webhook ti serve anche una chiave di decrittazione dei webhook, che Peach Payments ti invia quando attiva i webhook Card per il tuo negozio (vedi Configurazione). Il negozio deve essere raggiungibile da internet per ricevere i webhook.

Chiave di licenza VibeFox: si acquista 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 Peach Payments Pay 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, poi clicca su Activate (vedi Chiave di licenza).

4. Inserisci l'Entity ID e l'Access Token di test dal pannello sandbox di Peach Payments, e chiedi a Peach Payments di attivare i webhook Card per l'URL del webhook mostrato nella pagina delle impostazioni (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Lascia attivo Test mode ed effettua un pagamento con una carta di test della sandbox di Peach Payments. Poi disattiva Test mode, inserisci le credenziali live e la chiave webhook live, e fai clic su Save.

All'installazione il modulo crea due stati dell'ordine: Awaiting Peach Payments payment e Peach Payments payment on hold. PrestaShop offre un nuovo modulo di pagamento per le valute, i paesi e i gruppi di clienti attivi in quel momento. I paesi aggiunti in seguito devono essere abilitati per il modulo in Payment > Preferences, dove puoi anche limitarli.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra degli avvisi: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; un errore quando manca l'Entity ID o l'Access Token della modalità attuale (finché non sono inseriti, il metodo di pagamento non viene mostrato al checkout); un avviso quando manca la chiave di decrittazione dei webhook della modalità attuale (in tal caso i pagamenti vengono confermati solo quando il cliente torna nel negozio); e un errore quando la valuta predefinita del negozio non è supportata. Al salvataggio gli spazi vengono rimossi dalle credenziali, e una chiave webhook che non è un valore esadecimale di 64 caratteri viene segnalata con un avviso.

Peach Payments

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

Title: il nome del metodo di pagamento mostrato al cliente al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit / Debit Card (Peach Payments). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API credentials

L'Access Token e l'Entity ID della Card API sono mostrati nel pannello di Peach Payments (le credenziali di test nel pannello sandbox). La sezione contiene i collegamenti ad entrambi i pannelli e alla documentazione per sviluppatori di Peach Payments.

Test mode: invia i nuovi pagamenti alla sandbox di Peach Payments con le credenziali di test, e non viene addebitato denaro reale. Disattivalo per accettare pagamenti reali con le credenziali live. Un pagamento avviato in una modalità viene sempre verificato in quella modalità, anche dopo che hai cambiato. Predefinito: attivo.

Test Entity ID: l'Entity ID (canale 3-D Secure) del tuo account sandbox.

Test Access Token: l'access token bearer del tuo account sandbox.

Test Webhook Decryption Key: la chiave esadecimale di 64 caratteri usata per decrittare i webhook Card della sandbox.

Live Entity ID: l'Entity ID (canale 3-D Secure) del tuo account live.

Live Access Token: l'access token bearer del tuo account live.

Live Webhook Decryption Key: la chiave esadecimale di 64 caratteri usata per decrittare i webhook Card del tuo account live.

Gli access token e le chiavi webhook salvati non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: spunta un access token o una chiave webhook e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Webhook

I webhook confermano i pagamenti anche quando il cliente chiude il browser prima di tornare nel negozio. Il campo Webhook URL mostra l'URL del webhook del tuo negozio. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_peach_pay/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come appare nelle impostazioni. Chiedi a Peach Payments (support@peachpayments.com) di attivare i webhook Card per il tuo account con questo URL, poi inserisci la chiave di decrittazione che ricevi nel campo Webhook Decryption Key della stessa modalità.

Peach Payments cifra ogni webhook (AES-256-GCM). Un webhook che non può essere decrittato con la chiave di test o quella live viene rifiutato, quindi solo Peach Payments può modificare i tuoi ordini. Un webhook decrittato con la chiave di una modalità si applica solo ai pagamenti avviati in quella modalità. Il modulo usa le notifiche di pagamento:

Le altre notifiche, per esempio la notifica di test inviata all'attivazione del webhook, ricevono la risposta ignored. Senza la chiave webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo il pagamento.

Payment form

Card brands: i circuiti mostrati nel modulo di Peach Payments: Visa, Mastercard, American Express, Diners Club. Seleziona solo i circuiti abilitati per il tuo Entity ID. Predefinito: Visa e Mastercard. Se non è selezionato nessun circuito, al salvataggio compare un avviso e il modulo mostra Visa e Mastercard.

Advanced

Logging: registra le richieste API e gli esiti dei pagamenti in logs/peach_p_debug.log.php, nella cartella del modulo. Il file non può essere letto dal web. Errori e avvisi vengono sempre registrati. I registri non contengono dati delle carte, chiavi o dati dei clienti. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono eliminate le sue impostazioni e i registri. I dati Peach Payments degli ordini (tentativi di pagamento, ID dei pagamenti) e gli stati dell'ordine vengono conservati, perché appartengono agli ordini. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / Debit Card (Peach Payments)) e conferma l'ordine. In modalità test il metodo di pagamento mostra Test mode: no real payment will be made. Il modulo prepara un checkout Peach Payments per il totale del carrello nella valuta del carrello e mostra la pagina Peach Payments payment del tuo negozio con il modulo carta di Peach Payments e i circuiti selezionati, nella lingua del cliente quando Peach Payments la supporta. In modalità test la pagina mostra Test mode: use a Peach Payments test card, no real payment will be made. I dati della carta vengono inseriti nel modulo di Peach Payments, e lo script del modulo viene caricato con un hash Subresource Integrity. Il link Choose another payment method riporta al checkout. A questo punto l'ordine non esiste ancora. Ricaricando la pagina viene riutilizzato lo stesso checkout per un massimo di 25 minuti, a meno che il carrello non sia cambiato.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Peach Payments: il negozio legge il risultato del checkout di questo carrello tramite l'API Peach Payments, nella modalità in cui il checkout è stato creato, e verifica che il pagamento appartenga a questo carrello. Il webhook fa lo stesso in modo indipendente, quindi chi arriva per primo crea l'ordine e l'altro non cambia nulla. Il cliente vede poi la normale pagina di conferma dell'ordine.

Se il pagamento non viene completato, il cliente torna al checkout con un messaggio e può riprovare: Payment failed: seguito dal motivo comunicato da Peach Payments e da Please try again or use another card., oppure The payment was not completed. Please try again. Il carrello viene conservato. Se l'esito non può ancora essere confermato (per esempio perché Peach Payments non ha risposto, o perché il webhook sta elaborando proprio in quel momento lo stesso carrello), il messaggio è We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Quando per la modalità del pagamento non è impostata alcuna chiave webhook, al cliente viene chiesto invece di contattarti.

Se il modulo di pagamento non può essere preparato, il cliente resta al checkout con un breve messaggio: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenziali mancanti o errate), un messaggio che indica che alcuni dati di fatturazione non sono stati accettati dal fornitore di pagamento, oppure The payment form could not be loaded. Please try again in a moment. Il motivo tecnico viene scritto nel registro.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del negozio.

Il modulo non ha un modulo carta nella fase di checkout stessa, né carte salvate, abbonamenti, preautorizzazione e acquisizione, né EFT, BNPL, QR o altri metodi senza carta.

Ordini

Stati dell'ordine

No order yet: il cliente non ha pagato, il pagamento è stato rifiutato o non completato, oppure Peach Payments non lo ha ancora confermato. Esiste solo il carrello, e il cliente può pagare di nuovo.

Payment accepted: il pagamento è stato confermato e importo e valuta corrispondono al carrello. Il pagamento viene registrato con l'ID del pagamento Peach Payments come ID della transazione, e una nota mostra il codice di esito, la descrizione e l'ID del pagamento di Peach Payments. Se Peach Payments ha segnalato il pagamento per una verifica manuale, la nota ti chiede di controllarlo nel pannello di Peach Payments prima della spedizione.

Awaiting Peach Payments payment: Peach Payments ha segnalato un pagamento in attesa di conferma. Il webhook sposta poi l'ordine su Payment accepted oppure lo segna come fallito.

Peach Payments payment on hold: l'importo o la valuta pagati differiscono dal carrello (nota amount/currency mismatch — manual review required), oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota spiega cosa verificare. Controlla il pagamento nel pannello di Peach Payments, poi elabora l'ordine o rimborsa il pagamento.

Payment error: Peach Payments ha rifiutato il pagamento che l'ordine in attesa aspettava. Un tentativo rifiutato non modifica mai un ordine pagato, in sospeso o annullato.

Se un secondo pagamento per un ordine già pagato va a buon fine, l'ordine non cambia. Una nota segnala che si tratta di un pagamento duplicato e chiede di rimborsarlo nel pannello di Peach Payments. Un pagamento arrivato per un ordine rimborsato viene solo annotato sull'ordine.

Blocco pagamento Peach Payments

La pagina dell'ordine mostra un blocco Peach Payments payment con l'ID del pagamento, l'ID del checkout, l'ID della transazione del commerciante, l'importo inviato a Peach Payments, l'esito e il codice di esito, un badge Test mode per i pagamenti di test e le Peach Payments notes dell'ordine.

Rimborsi

I rimborsi dalla pagina dell'ordine di PrestaShop non sono disponibili. Rimborsa il pagamento nel pannello di Peach Payments e registralo in PrestaShop (rimborso parziale o nota di credito) se necessario. Con il webhook configurato, rimborsi, storni e contestazioni effettuati in Peach Payments vengono aggiunti alle note dell'ordine con importo e ID; lo stato dell'ordine non cambia.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Peach Payments Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per 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 compaiono la riga Product: presta-payment-peach 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 incluse le lingue inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per 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, clicca 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: quello 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, Peach Payments non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Il negozio online di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 dal ritorno del cliente e dal webhook.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Peach Payments non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che siano inseriti l'Entity ID e l'Access Token della modalità attuale (Test Entity ID e Test Access Token in modalità test, Live Entity ID e Live Access Token in modalità live) e che la valuta del carrello sia ZAR, KES o MUR. Gli avvisi in cima alle impostazioni indicano il problema. 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 cliente non è tornato nel negozio e il webhook non è arrivato. Verifica che Peach Payments abbia attivato i webhook Card esattamente per l'URL mostrato nelle impostazioni, che sia inserita la Webhook Decryption Key della modalità in cui è stato effettuato il pagamento, e che nessun firewall o protezione con password blocchi l'URL. Attiva Logging e controlla il campo Log per i webhook rifiutati.

Il webhook risponde Decryption failed: il webhook non è stato decrittato né con la chiave di test né con quella live. La chiave è errata oppure appartiene a un altro account o a un'altra modalità. Inserisci la chiave che Peach Payments ha inviato per questo URL del webhook.

Il webhook risponde Webhook key not configured: non sono impostate né valide né la chiave webhook di test né quella live. Inserisci la chiave di 64 caratteri. Peach Payments invierà di nuovo il webhook più tardi.

Il webhook risponde Busy, retry later: il carrello era in elaborazione per il ritorno del cliente in quello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Non è stato modificato nulla e Peach Payments invierà di nuovo il webhook. Il registro mostra il motivo.

Il webhook risponde Missing or malformed data: la richiesta non aveva un corpo cifrato né le intestazioni X-Initialization-Vector / X-Authentication-Tag, per esempio perché un proxy l'ha modificata. Non è stato modificato nulla.

Il webhook risponde ignored: la notifica è autentica ma non appartiene a un checkout di questo negozio (un altro negozio con lo stesso Entity ID, un carrello eliminato), oppure proviene da una modalità diversa da quella del pagamento. Non è stato modificato nulla.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da Peach Payments.

Il cliente vede The payment form is not available right now: l'Access Token o l'Entity ID della modalità attuale sono errati. Controlla le credenziali e la modalità, e leggi il registro per il codice di Peach Payments.

L'ordine è Peach Payments payment on hold dopo il pagamento: leggi le note nel blocco Peach Payments payment. L'importo o la valuta pagati erano diversi dal carrello, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Verifica il pagamento nel pannello di Peach Payments, poi elabora l'ordine o rimborsa il pagamento.

Al salvataggio compare il messaggio che la chiave webhook deve essere la chiave esadecimale di 64 caratteri: il valore non è la chiave fornita da Peach Payments. I webhook non possono essere decrittati finché non viene corretto.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Peach Payments Pay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, le impostazioni e i registri del modulo vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I tentativi di checkout, gli ID dei pagamenti e gli stati dell'ordine Awaiting Peach Payments payment e Peach Payments payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento, gli ID delle transazioni e i dati del checkout Peach Payments.

Peach Payments è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato né approvato da Peach Payments.