VibeFox Pin Payments for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni più vecchie di PHP.

Account Pin Payments: un account commerciante Pin Payments (per aziende in Australia o Nuova Zelanda; i clienti possono pagare da qualsiasi luogo). Ti servono la chiave pubblicabile e la chiave segreta, per il live e, per i test, per l'ambiente di test. Non serve alcun segreto webhook: il modulo non usa webhook. I dati della carta vengono inviati dal browser del cliente direttamente a Pin Payments tramite Pin.js e non arrivano mai al tuo negozio, quindi il negozio rientra in PCI SAQ A-EP.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox Pin Payments Gateway nell'elenco dei moduli e clicca su Configure.

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

4. Nella dashboard di Pin Payments apri Account > API Keys e copia le chiavi di test in Test publishable key e Test secret key. Lascia attivo Test mode, attiva Enable/Disable e clicca su Save.

5. Effettua un ordine di prova con una carta di test di Pin Payments. Quando tutto funziona, inserisci le chiavi live, disattiva Test mode e salva.

All'installazione il modulo crea lo stato ordine Pin Payments payment on hold. PrestaShop offre un nuovo modulo di pagamento per le valute, i gruppi di clienti e i paesi attivi al momento dell'installazione. Puoi modificarlo in Payment > Preferences; i paesi che attivi in seguito devono essere spuntati lì.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra un avviso mentre la modalità test è attiva, un errore se la chiave pubblicabile o la chiave segreta della modalità corrente è vuota, e un errore quando Pin Payments non supporta la valuta predefinita del negozio (con l'elenco delle valute supportate). Senza entrambe le chiavi della modalità corrente il metodo di pagamento è nascosto al checkout. Un Title vuoto non viene salvato: la pagina mostra Enter a title for the payment method.

Pin Payments

Enable/Disable: Enable Pin Payments 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: Credit card (Pin Payments). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with your credit card via Pin Payments.

Chiavi API

Trovi le chiavi nella dashboard di Pin Payments, in Account > API Keys. Le chiavi di test funzionano solo con l'API di test, quelle live solo con l'API live. La chiave pubblicabile è usata da Pin.js nel browser del cliente. La chiave segreta non lascia mai il tuo server.

Test mode: usa l'ambiente di test di Pin Payments (test-api.pinpayments.com) e le chiavi di test. Non vengono effettuati addebiti reali e i clienti vedono TEST MODE — no real charges will be made. sotto il metodo di pagamento. Quando è disattivata, vengono usate l'API live e le chiavi live. Predefinito: attivo.

Test publishable key: la chiave pubblicabile del tuo account di test di Pin Payments.

Test secret key: la chiave segreta del tuo account di test di Pin Payments.

Live publishable key: la chiave pubblicabile del tuo account live di Pin Payments.

Live secret key: la chiave segreta del tuo account live di Pin Payments.

Gli spazi attorno alle chiavi vengono rimossi. Le chiavi segrete salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: spunta una chiave segreta e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Avanzate

Debug log: scrive in logs/wc_ppg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati; attiva questa opzione per registrare anche ogni chiamata API. Dati della carta, chiavi API e dati personali dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del gateway e il log. I dati di pagamento degli ordini (addebiti e rimborsi) e lo stato ordine Pin Payments payment on hold vengono sempre conservati. Predefinito: disattivato.

Checkout

Il metodo di pagamento viene mostrato quando è attivo, sono impostate entrambe le chiavi della modalità corrente, la valuta del carrello è una delle 14 valute supportate (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) e il modulo è consentito per il carrello in Payment > Preferences.

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit card (Pin Payments), con le icone di Visa, Mastercard e American Express) e compila Card number, Expiry (MM / YY), CVC e Name on card. Prima dell'invio, il modulo controlla la lunghezza del numero di carta, il mese e l'anno di scadenza, un CVC di 3 o 4 cifre e il nome.

Quando il cliente effettua l'ordine, Pin.js invia dal browser direttamente a Pin Payments i dati della carta e l'indirizzo di fatturazione del carrello e ottiene un token carta monouso. Solo questo token viene inviato al tuo negozio. Il modulo crea quindi un addebito catturato per il totale del carrello nella valuta del carrello, con l'e-mail del cliente e la descrizione <shop name> - Cart <cart number>. Pin Payments risponde nella stessa richiesta. Prima di questa risposta non esiste alcun ordine.

Dopo un addebito riuscito l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your card payment has been received. Se l'ordine è finito in Pin Payments payment on hold, la pagina mostra Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Se Pin Payments non risponde (timeout, errore del server, risposta illeggibile), un addebito potrebbe comunque essere stato creato. L'ordine viene quindi creato in Pin Payments payment on hold senza pagamento, e la pagina di conferma mostra We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Inviare di nuovo lo stesso carrello non crea mai un secondo addebito.

Per ogni carrello è in corso un solo tentativo di pagamento alla volta. Un secondo invio riceve This order is already being paid. Please wait a moment and check your e-mail before trying again. Un carrello che ha già un ordine, o un tentativo precedente che ha prelevato o potrebbe aver prelevato denaro, non viene addebitato di nuovo; l'ordine viene invece creato da quel tentativo. Un token carta può essere usato una sola volta: dopo un tentativo fallito, o quando il cliente modifica i dati della carta, viene creato un nuovo token.

Quando il pagamento non riesce, non viene creato alcun ordine. Il cliente resta nella fase di pagamento, il carrello viene conservato e viene mostrato uno di questi messaggi: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: con il motivo indicato da Pin Payments per i dati rifiutati; Your card details have expired. Please enter them again and retry. quando il token non può essere usato; The secure card form could not be loaded. Please reload the page or choose another payment method. quando Pin.js non si carica; Card payments are temporarily unavailable. Please try again later or choose another payment method. quando Pin Payments rifiuta la chiave segreta; Your payment could not be processed. Please try again or choose another payment method. per altri errori. Il motivo tecnico viene scritto nel log.

Il modulo non include un flusso 3-D Secure. Se il tuo account Pin Payments richiede 3-D Secure, l'addebito resta in sospeso, non viene creato alcun ordine e il cliente vede Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Non esiste una modalità di sola autorizzazione con cattura successiva, né carte salvate, abbonamenti, Apple Pay o Google Pay, né webhook.

Ordini e rimborsi

Stati dell'ordine

No order yet: la carta è stata rifiutata, l'addebito richiedeva 3-D Secure, oppure il cliente non ha pagato. Esiste solo il carrello.

Payment accepted: Pin Payments ha comunicato un addebito riuscito e catturato per esattamente l'importo e la valuta del carrello. Il pagamento viene registrato con il token di addebito di Pin Payments come ID transazione, e una nota mostra l'importo e il token di addebito (e TEST MODE per i pagamenti di test).

Pin Payments payment on hold: l'addebito richiede la tua verifica. La nota spiega il motivo: Pin Payments ha addebitato un importo o una valuta diversi da quelli del carrello (viene registrato il pagamento dell'importo addebitato), il carrello è cambiato durante il pagamento, l'addebito è autorizzato ma non catturato (cattura l'importo nella dashboard di Pin Payments, poi imposta l'ordine su Pagamento accettato), oppure Pin Payments non ha dato una risposta chiara (nessun pagamento viene registrato; cerca la descrizione dell'addebito nella dashboard di Pin Payments prima della spedizione dell'ordine).

Refunded: l'addebito è stato rimborsato interamente tramite il modulo.

Se viene effettuato un secondo addebito per un carrello che ha già un ordine, l'ordine non cambia. Una nota ti chiede di verificarlo e di rimborsarlo nella dashboard di Pin Payments.

Blocco Pin Payments

La pagina dell'ordine mostra un blocco Pin Payments con un badge Test mode per i pagamenti di test, il token di addebito, lo stato, il marchio della carta e le ultime quattro cifre, l'importo addebitato, il totale dell'ordine e l'importo rimborsato, la Description at Pin Payments, lo storico dei rimborsi e le Pin Payments notes dell'ordine.

Rimborsi

Nel blocco Pin Payments inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Pin Payments. Conferma la domanda Refund this amount through Pin Payments? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi sono limitati all'importo e alla valuta effettivamente addebitati da Pin Payments, quindi dopo una differenza di importo o valuta puoi rimborsare fino a quanto ha pagato il cliente, non il totale dell'ordine. Il rimborso viene inviato all'ambiente (test o live) in cui l'ordine è stato pagato, quindi la chiave segreta di quella modalità deve essere impostata. Pin Payments elabora i rimborsi in modo asincrono, quindi lo stato è di solito in attesa. Una richiesta riuscita viene aggiunta allo storico dei rimborsi e alle note, con il token di rimborso di Pin Payments e il suo stato. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. Se Pin Payments rifiuta il rimborso o non risponde, il blocco mostra l'errore e nessun rimborso viene registrato.

Quando per l'ordine non è registrato alcun addebito (Pin Payments non ha dato una risposta chiara), il blocco non mostra il modulo di rimborso e ti indica quale descrizione cercare nella dashboard di Pin Payments.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Pin Payments. I rimborsi effettuati nella dashboard di Pin Payments non vengono sincronizzati con PrestaShop, quindi effettuali dalla pagina dell'ordine.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Pin Payments Gateway è il primo blocco di Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi 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-pinpayments 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 oppure 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, 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: 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, Pin Payments non viene mostrato ai clienti al checkout. Se viene avviato comunque un pagamento, il cliente vede This payment method is not available. Please choose another one. La vetrina 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 puoi provarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i rimborsi di ordini pagati in precedenza continuano a funzionare.

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

Pin Payments non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che siano compilate entrambe le chiavi della modalità corrente (Test publishable key e Test secret key in modalità test, altrimenti le chiavi live) e che la valuta del carrello sia una delle 14 valute supportate. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un errore per le chiavi mancanti e per una valuta del negozio non supportata.

Il pagamento è andato a buon fine, ma l'ordine è in Pin Payments payment on hold: leggi le note nel blocco Pin Payments (vedi Stati dell'ordine). Se Pin Payments non ha dato una risposta chiara, cerca nella dashboard di Pin Payments un addebito con la descrizione <shop name> - Cart <cart number>, poi spedisci l'ordine oppure rimborsa l'addebito nella dashboard.

Il cliente vede Your payment was received, but the order could not be completed automatically: la carta è stata addebitata, ma PrestaShop non è riuscito a creare l'ordine (ad esempio perché nel frattempo il modulo è stato disattivato). Il motivo è nel log. Al cliente viene chiesto di non pagare di nuovo; inviare di nuovo lo stesso carrello crea l'ordine senza un nuovo addebito.

I clienti vedono Card payments are temporarily unavailable: Pin Payments ha rifiutato la chiave segreta, oppure manca la chiave della modalità corrente. Le chiavi di test funzionano solo in modalità test, le chiavi live solo in modalità live. Il log mostra il motivo.

Gli ordini falliscono con additional verification is required: il tuo account Pin Payments richiede 3-D Secure, che il modulo non supporta. Chiedi a Pin Payments di disattivare il 3-D Secure obbligatorio.

Il modulo carta sicuro non è stato caricato: Pin.js dalla CDN di Pin Payments non si è caricato nel browser, per esempio a causa di un blocco script o di un modulo che combina o modifica gli script. Escludi il checkout da queste ottimizzazioni.

Pin Payments non ha risposto: il token carta non è stato creato nel browser entro 30 secondi. Il cliente può controllare la connessione e riprovare; non è stato addebitato nulla.

Pagamento non riuscito con un motivo di Pin Payments: Pin Payments ha rifiutato i dati dell'addebito, per esempio un importo inferiore al suo addebito minimo per la valuta. Il cliente vede il motivo e il log contiene il codice errore.

Il rimborso non riesce: leggi il messaggio nel blocco. Un messaggio su modalità TEST o LIVE significa che la chiave segreta della modalità in cui è stato pagato l'ordine è vuota. Pin Payments did not confirm the refund significa che non è arrivata alcuna risposta; controlla l'addebito nella dashboard di Pin Payments prima di riprovare. at most indica l'importo ancora rimborsabile dall'addebito.

Pagamenti di test: la modalità test usa l'ambiente di test e le chiavi di test. Usa le carte di test dalla documentazione per sviluppatori di Pin Payments, per esempio 4200 0000 0000 0000 (riuscito) o 4100 0000 0000 0001 (rifiutato), con qualsiasi data di scadenza futura e qualsiasi CVC. Gli ordini mantengono la modalità in cui sono stati pagati, quindi i rimborsi vanno all'ambiente giusto dopo il cambio di modalità.

Dove trovare gli errori: gli errori vengono sempre scritti nel log; vedi il campo Log nella pagina del modulo. Attiva Debug log per vedere ogni chiamata API.

Disinstallazione

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

Pin Payments è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da Pin Payments.