VibeFox Pin Payments for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

WooCommerce: 7.1 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

HTTPS: il checkout deve usare HTTPS, come richiesto per accettare pagamenti con carta (PCI DSS). I dati della carta vengono inviati dal browser del cliente direttamente a Pin Payments tramite Pin.js e non arrivano mai al tuo server, quindi il negozio rientra nell'ambito di PCI SAQ A-EP.

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 sua chiave pubblicabile (publishable) e la sua chiave segreta (secret), per il live e, per i test, per l'ambiente di test. Non serve alcun segreto webhook: il plugin non usa webhook.

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_pinpayments_gateway in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Pin Payments > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. 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 salva.

6. 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.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Pin Payments. Sopra i campi la pagina mostra un avviso mentre la modalità test è attiva, un errore mentre la chiave pubblicabile o la chiave segreta della modalità corrente è vuota, e un errore quando Pin Payments non supporta la valuta del negozio (con l'elenco delle valute supportate). In questi ultimi due casi il gateway viene nascosto nel checkout. Dopo il salvataggio, gli avvisi riflettono già la nuova modalità e le nuove chiavi. Nell'elenco dei metodi di pagamento il gateway risulta da configurare finché la modalità corrente non ha entrambe le chiavi.

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

Title: il titolo del metodo di pagamento mostrato nel checkout. Predefinito: Credit card (Pin Payments).

Description: la descrizione del metodo di pagamento mostrata nel 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 viene usata da Pin.js nel browser del cliente. La chiave segreta non lascia mai il tuo server.

Test mode: Enable test mode. Usa l'ambiente di test di Pin Payments (test-api.pinpayments.com) e le chiavi di test. Non viene effettuato alcun addebito reale e i clienti vedono MODALITÀ TEST — non verrà effettuato alcun addebito reale. nel modulo della carta. Quando è disattivata, vengono usate l'API live (api.pinpayments.com) 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. È un campo password.

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. È un campo password.

Gli spazi attorno alle chiavi vengono rimossi. Entrambe le chiavi della modalità corrente devono essere compilate, altrimenti il gateway non viene mostrato nel checkout.

Avanzate

Debug log: Log Pin Payments API calls — i log vengono salvati in WooCommerce > Status > Logs, origine wcp_pinpayments_gateway. 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.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati di pagamento salvati negli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

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 nel tuo checkout. Prima dell'invio, il modulo della carta 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 l'ordine viene effettuato, Pin.js invia dal browser i dati della carta e l'indirizzo di fatturazione direttamente a Pin Payments e ottiene un token carta monouso. Solo questo token viene inviato al tuo server. Il server crea quindi un addebito acquisito per il totale dell'ordine nella valuta dell'ordine, con la descrizione <store name> - Order <number>. Pin Payments risponde nella stessa richiesta. L'ordine viene segnato come pagato solo quando Pin Payments conferma un addebito riuscito, e solo per esattamente l'importo e la valuta dell'ordine. Poi il cliente arriva alla pagina di ricezione dell'ordine.

Per ogni ordine viene eseguito un solo tentativo di pagamento alla volta. Un secondo invio riceve Questo ordine è già in fase di pagamento. Attendi un momento e controlla la tua e-mail prima di riprovare. Un ordine già pagato, o addebitato e trattenuto, non viene mai addebitato di nuovo. Un token carta può essere usato una sola volta: dopo un tentativo non riuscito, o quando il cliente modifica i dati della carta, viene creato un nuovo token.

Messaggi che il cliente può vedere: La tua carta è stata rifiutata. Usa un'altra carta o contatta la tua banca.; La tua carta non ha fondi sufficienti. Usa un'altra carta.; La tua carta è scaduta. Usa un'altra carta.; Il codice di sicurezza della carta (CVC) non è corretto.; Questo tipo di carta non è accettato. Usa Visa, Mastercard o American Express.; Pagamento non riuscito: con il motivo indicato da Pin Payments per i dati rifiutati; I dati della tua carta sono scaduti. Inseriscili di nuovo e riprova. quando il token non può essere usato; Impossibile caricare il modulo sicuro della carta. Ricarica la pagina o scegli un altro metodo di pagamento. quando Pin.js non si carica; I pagamenti con carta sono temporaneamente non disponibili. Riprova più tardi o scegli un altro metodo di pagamento. quando Pin Payments rifiuta la chiave segreta; Non siamo riusciti a confermare il tuo pagamento con Pin Payments. Controlla la tua e-mail e l'estratto conto della carta prima di riprovare, oppure contattaci. quando Pin Payments non risponde. I dettagli tecnici vengono registrati nelle note dell'ordine e nel log.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout (con gli stessi campi carta) e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin non prevede un flusso 3-D Secure. Se il tuo account Pin Payments richiede 3-D Secure, l'addebito resta in sospeso e il plugin fa fallire l'ordine, quindi con quel tentativo non viene prelevato alcun denaro; il cliente vede Il pagamento con carta non è stato completato (è richiesta una verifica aggiuntiva). Prova con un'altra carta o un altro metodo di pagamento. Non esiste una modalità solo autorizzazione con cattura successiva, né carte salvate, WooCommerce Subscriptions, Apple Pay o Google Pay, né webhook.

Ordini e rimborsi

Stati dell'ordine

Processing: Pin Payments ha segnalato un addebito riuscito e acquisito per esattamente l'importo e la valuta dell'ordine. Gli ordini con soli prodotti digitali scaricabili diventano Completato, il valore predefinito di WooCommerce. La nota dell'ordine mostra l'importo e il token dell'addebito (e TEST MODE per i pagamenti di test). L'ID transazione è il token di addebito di Pin Payments.

Failed: la carta è stata rifiutata, l'addebito è rimasto in sospeso (3-D Secure), Pin Payments ha rifiutato la chiave segreta o la richiesta. Ogni tentativo non riuscito aggiunge una nota all'ordine con il codice di errore e il messaggio di Pin Payments, anche quando l'ordine era già Non riuscito per un tentativo precedente. Il cliente può riprovare con lo stesso ordine.

Pending payment: Pin Payments non ha dato una risposta chiara (timeout, errore del server, risposta illeggibile). L'ordine non viene segnato come non riuscito, perché l'addebito potrebbe comunque essere stato creato. La nota ti invita a cercare la descrizione dell'addebito nella dashboard di Pin Payments prima che il cliente paghi di nuovo o che l'ordine venga spedito. Questo stato è In attesa di pagamento.

On hold: Pin Payments ha addebitato un importo o una valuta diversi dall'ordine (la nota mostra l'importo previsto e quello addebitato), oppure l'addebito è autorizzato ma non acquisito. Controlla l'addebito nella dashboard di Pin Payments prima di evadere l'ordine.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit card (Pin Payments) (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali. 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. Una richiesta riuscita aggiunge una nota all'ordine con l'importo, il token di rimborso di Pin Payments e il relativo stato. Pin Payments elabora i rimborsi in modo asincrono, quindi lo stato è di solito Pending. Se Pin Payments rifiuta il rimborso o non risponde, WooCommerce mostra l'errore e non viene registrato alcun rimborso.

I rimborsi effettuati nella dashboard di Pin Payments non vengono sincronizzati con WooCommerce, quindi effettuali da WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Pin Payments. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito 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 nel checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato come (senza licenza — visibile solo agli amministratori), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i rimborsi continuano a funzionare.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Pin Payments non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che entrambe le chiavi della modalità corrente siano compilate (Test publishable key e Test secret key in modalità test, le chiavi live altrimenti) e che la valuta del carrello sia una delle 14 valute supportate. Nella pagina Pay for order conta la valuta dell'ordine. La pagina delle impostazioni mostra un errore per le chiavi mancanti e per una valuta non supportata.

Nel checkout compare «Non siamo riusciti a confermare il tuo pagamento»: Pin Payments non ha risposto in tempo. L'ordine resta In attesa di pagamento con una nota. Cerca nella dashboard di Pin Payments un addebito con la descrizione <store name> - Order <number> prima che il cliente paghi di nuovo o che l'ordine venga spedito. Il plugin non cerca automaticamente tale addebito, e un nuovo tentativo crea un nuovo addebito.

I clienti vedono «I pagamenti con carta sono temporaneamente non disponibili»: Pin Payments ha rifiutato la chiave segreta. La nota dell'ordine indica di controllare le chiavi della modalità corrente. Le chiavi di test funzionano solo in modalità test, quelle live solo in modalità live.

Gli ordini falliscono con «è richiesta una verifica aggiuntiva»: il tuo account Pin Payments richiede 3-D Secure, che il plugin non supporta. Chiedi a Pin Payments di disattivare il 3-D Secure obbligatorio.

Un ordine è In sospeso con la nota «does not match»: Pin Payments ha segnalato un importo o una valuta dell'addebito diversi dall'ordine. Controlla l'addebito nella dashboard di Pin Payments e rimborsa o completa l'ordine manualmente.

Impossibile caricare il modulo sicuro della carta: Pin.js dalla CDN di Pin Payments non si è caricato nel browser, per esempio a causa di un blocco degli script o di un plugin di cache o ottimizzazione che modifica gli script. Escludi il checkout da queste ottimizzazioni.

Il rimborso non riesce: leggi il messaggio. Un messaggio sulla modalità TEST o LIVE significa che la chiave segreta della modalità in cui è stato pagato l'ordine è vuota. Pin Payments non ha confermato il rimborso significa che non è arrivata alcuna risposta; controlla l'addebito nella dashboard di Pin Payments prima di riprovare.

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 la nota dell'ordine contiene il codice di errore.

Pagamenti di test: la modalità test usa l'ambiente di test e le chiavi di test. Usa le carte di test della 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 aver cambiato modalità.

Dove trovare gli errori: gli errori vengono sempre scritti in WooCommerce > Status > Logs, origine wcp_pinpayments_gateway. Attiva Debug log per vedere ogni chiamata API.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Per gli sviluppatori: il filtro wc_ppg_supported_currencies modifica l'elenco delle valute, e wc_ppg_icon modifica l'icona nell'elenco dei metodi di pagamento di WooCommerce.

Disinstallazione

Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le opzioni di versione del plugin e i suoi log (file di log, inclusi quelli ruotati, e voci di log nel database) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. I dati di pagamento salvati negli ordini, come il token di addebito di Pin Payments, non vengono mai eliminati. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

Pin Payments è un marchio di proprietà dei rispettivi titolari. Questo plugin non è affiliato né approvato da Pin Payments.