VibeFox 2C2P for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

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

Account 2C2P: ti servono il Merchant ID e la Secret Key del tuo account commerciante 2C2P. Vengono rilasciati da 2C2P quando viene aperto il tuo account commerciante. Gli account sandbox e live hanno chiavi diverse. La documentazione per sviluppatori e le carte di prova del sandbox si trovano su developer.2c2p.com.

Valuta: la valuta del carrello deve essere supportata dal modulo e abilitata nel tuo account 2C2P. Sono supportate, tra le altre, THB, SGD, MYR, PHP, IDR, VND, MMK, KHR, LAK, CNY, HKD, TWD, JPY, KRW, INR, AUD, NZD, USD, EUR e GBP. Se la valuta del carrello non è supportata, il metodo di pagamento non viene mostrato nel checkout.

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 2C2P Payment 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. Inserisci il tuo Merchant ID e la tua Secret Key sandbox, attiva Enable/Disable, fai clic su Save ed effettua un ordine di prova.

5. Quando sei pronto, inserisci le credenziali live e disattiva Sandbox Mode.

All'installazione il modulo crea due stati dell'ordine: Awaiting 2C2P payment e 2C2P payment on hold. PrestaShop abilita il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences. Gli URL di ritorno e di notifica vengono inviati con ogni pagamento. Non serve configurare nulla nel portale 2C2P.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox 2C2P Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina mostra Sandbox mode is active. No real transactions will be processed. finché la modalità sandbox è attiva. Avvisa quando il gateway è abilitato ma il Merchant ID o la Secret Key della modalità corrente sono vuoti, e quando la valuta predefinita del negozio non è supportata. In entrambi i casi il metodo di pagamento non viene mostrato nel checkout. Se salvi con Sandbox Mode disattivato, il modulo mostra Please enter your live Merchant ID. oppure Please enter your live Secret Key. se un campo live è vuoto. Le impostazioni vengono comunque salvate.

2C2P

Enable/Disable: Enable 2C2P Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: 2C2P Payment.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. In modalità sandbox viene aggiunto (TEST MODE).

Modalità di test (sandbox)

Sandbox Mode: invia i pagamenti al sandbox di 2C2P (demo2.2c2p.com) con le credenziali sandbox indicate sotto. Predefinito: attivo. Disattivalo per accettare pagamenti reali.

Sandbox Merchant ID: il tuo Merchant ID 2C2P sandbox.

Sandbox Secret Key: la tua Secret Key 2C2P sandbox.

Credenziali API live

Vengono usate quando la modalità sandbox è disattivata.

Merchant ID: il tuo Merchant ID 2C2P live.

Secret Key: la tua Secret Key 2C2P live. La chiave viene salvata esattamente come inserita, comprese virgolette e barre rovesciate.

Le Secret Key salvate non vengono mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Cancellare i segreti salvati: spunta Sandbox Secret Key o Secret Key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Gli esiti vengono sempre verificati con il Merchant ID e la Secret Key della modalità in cui è stato effettuato il pagamento. Un pagamento avviato in modalità sandbox viene comunque verificato con la chiave sandbox dopo il passaggio al live, e un esito firmato con la chiave dell'altra modalità viene rifiutato.

Pagina di pagamento

URL di esito: mostra, a titolo di riferimento, il Frontend return URL e il Backend notification URL. Con URL semplificati hanno questo aspetto: https://your-shop/module/wcp_2c2p_payment/return e https://your-shop/module/wcp_2c2p_payment/notify, eventualmente con un codice lingua come /en/. Vengono inviati automaticamente con ogni pagamento.

Payment Page Language: la lingua della pagina di pagamento 2C2P. Predefinito: English.

Redirect API version: lascia 8.5, a meno che 2C2P non ti abbia comunicato che il tuo account usa ancora la versione precedente 7.0 (firme SHA-1). Gli esiti dei pagamenti avviati prima di un cambio continuano a essere verificati.

Order ID prefix: facoltativo, solo lettere e cifre (massimo 10), per esempio SHOP1. 2C2P rifiuta un ID ordine che ha già ricevuto. Imposta un prefisso unico quando più negozi condividono un account 2C2P e nel sandbox, dove gli account commerciante di prova sono condivisi. Gli altri caratteri vengono rimossi al salvataggio, con un avviso.

Impostazioni avanzate

Enable Logging: scrive gli eventi 2C2P in logs/tc2p_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Non vengono registrati dati della carta, chiavi segrete, e-mail dei clienti o token di pagamento. Predefinito: disattivato. Finché è disattivato non viene scritto nulla, errori compresi.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. Le transazioni 2C2P, gli ordini e gli stati degli ordini del modulo restano sempre, quindi un esito tardivo di un vecchio pagamento viene comunque gestito dopo una reinstallazione. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita 2C2P Payment) e conferma. La pagina successiva mostra Thank you for your order. You will be redirected to 2C2P to complete your payment. e, dopo un momento, invia il cliente alla pagina di pagamento di 2C2P. Se questo non avviene, il cliente fa clic su Pay via 2C2P. La pagina ha anche un pulsante Back to checkout. In questo momento l'ordine non esiste ancora.

Sulla pagina di 2C2P il cliente paga con uno qualsiasi dei metodi attivi sul tuo account 2C2P, per esempio carte, portafogli elettronici, pagamenti QR, internet banking o pagamenti in contanti. Il modulo trasmette il totale del carrello nella valuta del carrello, l'e-mail del cliente e i nomi dei prodotti nel carrello. Il pagamento può essere completato entro 24 ore. Ogni tentativo di pagamento riceve un proprio ID ordine 2C2P (il numero del carrello e il numero del tentativo, dopo il prefisso facoltativo), perché 2C2P non accetta mai lo stesso ID ordine due volte.

2C2P comunica l'esito due volte: il browser del cliente torna al negozio e 2C2P invia una notifica server-to-server. Entrambi vengono gestiti allo stesso modo. L'ordine viene segnato come pagato solo dopo che 2C2P lo conferma con una firma valida. L'esito deve inoltre appartenere al pagamento: l'ID ordine 2C2P deve essere stato emesso dal tuo negozio, e vengono verificati il Merchant ID e il token casuale del tentativo. Gli esiti senza una firma valida vengono rifiutati. La notifica funziona anche quando il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del tuo negozio.

Dopo un pagamento riuscito l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your 2C2P payment has been received. Per un pagamento in attesa la pagina mostra Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. Per un ordine in sospeso mostra Your payment was received and is being reviewed by the shop. Se un pagamento in attesa viene annullato in seguito, mostra Your 2C2P payment was not completed. Please contact us about this order.

Se il pagamento non è stato completato, non viene creato alcun ordine. Il cliente torna al checkout con il messaggio Payment was not completed. Please try again or choose a different payment method. Il carrello viene conservato e il cliente può pagare di nuovo o scegliere un altro metodo di pagamento. Se l'esito non può essere confermato, il cliente vede We could not confirm the payment result. If your account was charged, please contact us before paying again. Se il pagamento non può essere avviato, per esempio perché la valuta del carrello non è supportata, il messaggio è This payment method is currently unavailable for this order. Please contact us or choose another payment method.

Se il carrello ha già un ordine (pagato o in attesa di un pagamento in sospeso), non viene generato un secondo modulo di pagamento. Il cliente viene inviato alla pagina di conferma dell'ordine.

Il modulo non gestisce rimborsi da PrestaShop, carte salvate, pagamenti ricorrenti o abbonamenti, campi carta sul tuo sito, né supporta l'API 2C2P PGW 4.x.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a 2C2P e non è ancora arrivato alcun esito, oppure il pagamento non è riuscito. Esiste solo il carrello.

Payment accepted: 2C2P ha comunicato un pagamento riuscito (stato 000). Il pagamento viene registrato con il riferimento della transazione 2C2P come ID transazione. Una nota privata sull'ordine mostra la transazione 2C2P, il codice di approvazione, la data e il canale di pagamento.

Awaiting 2C2P payment: il pagamento è in attesa presso 2C2P (stato 001), per esempio un pagamento in contanti che il cliente non ha ancora effettuato. L'ordine passa in Payment accepted quando 2C2P comunica il pagamento.

2C2P payment on hold: 2C2P ha comunicato un importo o una valuta diversi dal totale dell'ordine. La nota mostra i valori ricevuti e quelli attesi. Verifica l'ordine e la transazione nel portale 2C2P.

Canceled: un pagamento in attesa è stato successivamente rifiutato, annullato o non è riuscito (stati 002, 003, 999). La nota mostra lo stato e il motivo. Un esito negativo di un tentativo precedente non annulla un ordine creato da un altro tentativo.

Un ordine pagato non viene mai modificato da un esito successivo, e un vecchio esito ripetuto non riapre un ordine annullato. Se arriva un secondo pagamento per un ordine già pagato, l'ordine non cambia. Una nota ti chiede di verificarlo e di rimborsare il duplicato nel portale commerciante 2C2P.

Blocco pagamento 2C2P

La pagina dell'ordine mostra un blocco 2C2P payment con l'ID ordine 2C2P, la transazione, lo stato del pagamento, il canale, il codice di approvazione, il numero di carta mascherato, la data, la risposta del canale e l'importo ricevuto, oltre a un badge Sandbox per i pagamenti sandbox.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il pagamento nel portale commerciante 2C2P, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox 2C2P Payment è il primo blocco di Modules > Module Manager > VibeFox 2C2P Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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 di essi si trovano la riga Product: presta-payment-2c2p 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 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: 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, 2C2P non viene mostrato ai clienti nel 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 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 nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati continuano a essere confermati.

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 alla settimana. Non serve alcun cron job. La disinstallazione o il ripristino del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

2C2P non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia un Merchant ID e una Secret Key: i campi sandbox in modalità sandbox, i campi live in modalità live. Verifica che la valuta del carrello sia supportata. La pagina delle impostazioni mostra un avviso in entrambi i casi. 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: nessun esito valido è arrivato al tuo negozio. Verifica che il Merchant ID e la Secret Key della modalità in cui è stato effettuato il pagamento corrispondano all'account 2C2P, e che Redirect API version corrisponda al tuo account. Un esito con firma errata o per un altro Merchant ID viene rifiutato. Attiva Enable Logging e cerca messaggi di hash o di Merchant ID nel campo Log. Verifica anche che il tuo server accetti le richieste di 2C2P all'URL di notifica backend.

La notifica backend risponde 400 FAIL: l'esito contiene campi mancanti, una firma errata, un altro Merchant ID o un token errato. 404 FAIL significa che l'ID ordine 2C2P non è stato emesso da questo negozio. 503 RETRY significa che l'ordine era in fase di conferma da un'altra richiesta nello stesso momento, oppure che non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato); 2C2P riproverà più tardi. Attiva Enable Logging per vedere il motivo.

L'URL di notifica mostra FAIL nel browser: è normale. L'URL accetta solo richieste POST da 2C2P.

2C2P segnala che l'ID ordine esiste già: 2C2P non accetta lo stesso ID ordine due volte. Succede quando più negozi condividono un account 2C2P oppure nel sandbox, dove gli account commerciante demo sono condivisi da molti sviluppatori. Imposta un Order ID prefix unico.

È stato effettuato un pagamento ma l'ordine è in Awaiting 2C2P payment o 2C2P payment on hold: o il pagamento è ancora in attesa presso 2C2P (per esempio un pagamento in contanti che il cliente non ha ancora effettuato), oppure l'importo o la valuta pagati non corrispondevano all'ordine. Verifica le note dell'ordine e la transazione nel portale 2C2P.

Il cliente vede This payment method is currently unavailable for this order: la valuta del carrello non è supportata, il Merchant ID o la Secret Key della modalità corrente sono vuoti, oppure il totale del carrello è zero.

Please enter your live Merchant ID o Please enter your live Secret Key al salvataggio: la modalità sandbox è disattivata e un campo live è vuoto. Inserisci le credenziali live oppure lascia Sandbox Mode attivo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox 2C2P Payment 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 del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le transazioni 2C2P e gli stati dell'ordine Awaiting 2C2P payment e 2C2P payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.

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