VibeFox Satispay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione OpenSSL. Il modulo non si installa su versioni precedenti di PHP o senza OpenSSL.

Valuta: EUR. Satispay incassa solo in euro, quindi il metodo di pagamento è nascosto quando la valuta del carrello non è EUR.

Account Satispay: un account Satispay Business. Non copi nessuna chiave API: il modulo si collega con un codice di attivazione monouso che generi nel Satispay Business Dashboard (vedi Configurazione). Per i test ti serve un account sandbox di Satispay, che richiedi a Satispay per sviluppatori.

Negozio pubblico: il negozio deve essere raggiungibile da internet, perché Satispay possa richiamarlo quando cambia un pagamento. In Satispay non c'è nulla da configurare.

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 Satispay Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la 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. Scegli l'ambiente: attiva Sandbox Mode per i test, lascialo disattivato per i pagamenti reali.

5. Incolla in Activation Code un codice di attivazione di quell'ambiente e fai clic su Save. Il campo Status mostrerà allora Connected con il Key ID.

6. Attiva Enable/Disable e fai clic su Save. Prova un pagamento in sandbox, poi disattiva Sandbox Mode e collega l'ambiente live con un codice di attivazione live.

All'installazione il modulo crea lo stato ordine Satispay payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences. Lì il modulo deve essere consentito per l'euro.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Satispay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina.

Checkout

Ciò che i clienti vedono nell'elenco dei metodi di pagamento.

Enable/Disable: Enable Satispay payment attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Satispay. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Connessione Satispay

Status: lo stato di entrambi gli ambienti, per esempio Live: Connected con il Key ID oppure Sandbox: Not connected, e quale ambiente è in uso. Finché l'ambiente in uso non è collegato, il campo mostra Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: usa l'ambiente sandbox (di prova) di Satispay. I pagamenti in sandbox non vengono addebitati. Predefinito: off. Sandbox e live hanno chiavi separate: collega ogni ambiente con un codice di attivazione di quell'ambiente. Mentre si usa la sandbox, i clienti vedono Sandbox mode: no real money is charged. sotto il metodo di pagamento.

Activation Code: per collegare l'ambiente selezionato sopra, incolla un nuovo codice di attivazione di 6 caratteri e fai clic su Save. I codici live si generano nel Satispay Business Dashboard, sezione Online shop. I codici sandbox si ottengono con un account sandbox di Satispay. Il codice viene usato una sola volta e non viene memorizzato. Lascia il campo vuoto per mantenere il collegamento attuale.

Quando salvi con un codice, il modulo crea una coppia di chiavi RSA, invia la chiave pubblica e il codice a Satispay, e memorizza il Key ID e le chiavi di quell'ambiente nella configurazione del negozio. Le chiavi private non vengono mai mostrate. In caso di successo la pagina mostra, per esempio, Satispay Live connected. Key ID: seguito dall'ID. Se Satispay rifiuta il codice, la pagina mostra Satispay activation failed: con il messaggio di Satispay e ti chiede di verificare che il codice sia per questo ambiente e non sia già stato usato. Un codice con caratteri diversi da lettere e cifre viene rifiutato prima di inviare qualsiasi cosa. Salvare un nuovo codice per un ambiente sostituisce il suo collegamento precedente.

Notifiche di pagamento

In Satispay non c'è nulla da configurare. Ogni pagamento ha il proprio URL di callback, che Satispay richiama quando il pagamento cambia, e il modulo rilegge il pagamento dalle API di Satispay prima di creare o modificare un ordine. Il campo Callback URL mostra un esempio di questo URL. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}, eventualmente con un codice lingua come /en/. L'URL deve essere raggiungibile da internet: nessuna autenticazione di base davanti. La callback funziona anche con il negozio in modalità manutenzione e non è bloccata dalla restrizione per paese del tuo negozio.

Avanzate

Debug log: scrive le chiamate API e gli eventi di pagamento in logs/satispay_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Gli errori vengono sempre registrati, anche quando l'opzione è disattivata. Predefinito: off.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni, le chiavi Satispay di entrambi gli ambienti e il log. I pagamenti e i rimborsi Satispay salvati per gli ordini e lo stato ordine Satispay payment on hold vengono sempre conservati. Predefinito: off.

Checkout

Al passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Satispay) e conferma l'ordine. Il modulo crea un pagamento Satispay per il totale del carrello in euro, con il numero del carrello come riferimento, e invia il cliente alla pagina di pagamento Satispay. Su un computer il cliente inquadra il codice QR con l'app Satispay. Su un telefono il cliente conferma il pagamento nell'app. In questo momento non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo che Satispay lo ha confermato: il modulo legge il pagamento dalle API di Satispay, verifica che sia stato creato per questo carrello e confronta stato, importo (in centesimi) e valuta con il carrello. Questo avviene sia quando Satispay chiama l'URL di callback sia quando il cliente torna, a seconda di quale arriva per primo. L'ordine viene quindi creato e il cliente vede la consueta pagina di conferma dell'ordine. Se Satispay non ha ancora confermato il pagamento quando il cliente torna, una pagina Payment confirmation mostra Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. e un pulsante Check again. La callback crea l'ordine appena arriva.

Se il cliente lascia la pagina Satispay senza pagare, il modulo annulla il pagamento presso Satispay, così la pagina abbandonata non può più essere pagata. Il cliente torna al checkout con il messaggio Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. Lo stesso messaggio compare quando il cliente rifiuta il pagamento nell'app. Il carrello viene conservato.

Prima di creare un nuovo pagamento Satispay per lo stesso carrello, quello precedente viene verificato: un pagamento in sospeso viene annullato presso Satispay e, se era già stato pagato, l'ordine viene creato con quel pagamento senza effettuarne un secondo.

Se il pagamento non può essere avviato, il cliente resta al checkout con un messaggio breve: Satispay is not available at the moment. Please choose another payment method. quando il negozio non è collegato o Satispay rifiuta le chiavi, oppure Unable to create the Satispay payment. Please try again or choose another payment method. per altri errori. Il motivo viene scritto nel log.

Il modulo accetta solo pagamenti una tantum in euro. Non supporta abbonamenti, metodi di pagamento salvati, pre-autorizzazioni o buoni pasto. Non esiste un controllo programmato dei pagamenti in sospeso: se né la callback di Satispay né il ritorno del cliente raggiungono il tuo negozio, non viene creato alcun ordine e il pagamento resta visibile nel Satispay Dashboard.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Satispay e non ha pagato, oppure Satispay non ha ancora confermato il pagamento. Esistono solo il carrello e il pagamento Satispay del modulo.

Payment accepted: il pagamento è stato confermato. Viene registrato con l'ID del pagamento Satispay come ID transazione, e una nota mostra il pagamento Satispay, l'importo e come è stato verificato (callback, redirect or checkout).

Satispay payment on hold: Satispay ha segnalato un importo o una valuta diversi dal totale del carrello (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento), oppure il pagamento è stato accettato dopo che l'ordine era stato annullato. Il denaro ricevuto viene registrato sull'ordine e la nota lo spiega. Verifica il pagamento nel Satispay Dashboard, poi evadi l'ordine o rimborsa il pagamento. Se in seguito viene accettato un altro pagamento dello stesso carrello con l'importo corretto, l'ordine passa a Payment accepted.

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

Se per un ordine già pagato viene accettato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato dal Satispay Dashboard. Una conferma ripetuta non riapre mai un ordine annullato o rimborsato.

Blocco pagamento Satispay

La pagina dell'ordine mostra un blocco Satispay payment con l'ID del pagamento Satispay, il suo stato, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti in sandbox, lo storico dei rimborsi, l'elenco Satispay payments of this cart con ogni tentativo di pagamento e il suo ambiente, e le Satispay notes dell'ordine.

Rimborsi

Nel blocco Satispay payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Satispay. Conferma la domanda Refund this amount through Satispay? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine Modules. I rimborsi sono limitati all'importo che Satispay ha addebitato per il pagamento, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente in cui è stato effettuato il pagamento (live o sandbox), quindi quell'ambiente deve essere ancora collegato. Un rimborso risulta eseguito solo quando Satispay lo accetta: un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso Satispay e il motivo. Se Satispay non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Satispay. I rimborsi effettuati nel Satispay Dashboard non vengono registrati in PrestaShop. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Satispay Gateway è il primo blocco di Modules > Module Manager > VibeFox Satispay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 di essi ci sono la riga Product: presta-payment-satispay 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 modificare 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Satispay 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. La vetrina di PrestaShop non sa che sei collegato al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Satispay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'ambiente in uso sia collegato (il campo Status mostra Connected per esso) e che la valuta del carrello sia EUR. In Payment > Preferences verifica che il modulo sia consentito per l'euro, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: l'ordine viene creato quando Satispay chiama il tuo negozio o quando il cliente torna. Verifica che il negozio sia raggiungibile da internet, senza autenticazione di base davanti all'URL di callback, e attiva Debug log per vedere le callback nel campo Log. Il pagamento è visibile nel Satispay Dashboard.

La callback risponde Payment status unavailable, retry later. oppure Not configured.: il modulo non è riuscito a leggere il pagamento da Satispay, oppure l'ambiente del pagamento non è collegato. Nessun ordine viene modificato. Satispay richiama. Controlla lo stato del collegamento e il log.

La callback risponde Busy, retry later.: il carrello era in fase di conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Satispay richiama. Il log mostra il motivo.

La callback risponde Unknown payment. oppure Missing or invalid payment_id.: il pagamento non è stato creato da questo negozio per questo carrello, oppure la richiesta non è una callback di Satispay. Non viene modificato nulla.

L'attivazione non riesce: i codici di attivazione possono essere usati una sola volta. Verifica che il codice appartenga all'ambiente selezionato in Sandbox Mode (un codice live per live, un codice sandbox per la sandbox), genera un nuovo codice e salva di nuovo. Se la pagina dice che non è stato possibile generare una coppia di chiavi RSA, chiedi al tuo hosting di attivare l'estensione OpenSSL di PHP. Se Satispay non è raggiungibile, verifica che il server possa aprire connessioni HTTPS in uscita.

Satispay è scomparso dal checkout dopo il passaggio da sandbox a live: sandbox e live usano chiavi diverse. Incolla un codice di attivazione live con Sandbox Mode disattivato e salva.

Il cliente vede This payment method is not available.: il metodo di pagamento non è consentito per il carrello (paese, valuta o gruppo di clienti in Payment > Preferences), è disattivato oppure l'ambiente in uso non è collegato.

L'ordine è Satispay payment on hold dopo il pagamento: leggi le note nel blocco Satispay payment (vedi Stati dell'ordine), verifica il pagamento nel Satispay Dashboard, poi evadi l'ordine o rimborsa il pagamento.

Il rimborso non riesce perché l'ambiente non è più collegato: il pagamento è stato effettuato in live o in sandbox, e quell'ambiente ora non ha più chiavi. Collegalo di nuovo con un codice di attivazione, oppure rimborsa il pagamento dal Satispay Dashboard.

Il rimborso non riesce con Satispay did not accept the refund: Satispay ha restituito uno stato diverso da accepted. PrestaShop non ha registrato il rimborso, e una nota lo indica. Verificalo nel Satispay Dashboard.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Satispay 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, vengono rimosse le impostazioni, le chiavi Satispay di entrambi gli ambienti e il log. Se è disattivo, tutte le impostazioni e le chiavi vengono conservate per una successiva reinstallazione. I pagamenti e i rimborsi Satispay salvati per gli ordini e lo stato ordine Satispay payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione, una volta che l'ambiente è di nuovo collegato. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

Satispay è un marchio del suo rispettivo titolare. Questo modulo non è affiliato né approvato da Satispay.