VibeFox CCAvenue for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo, con l'estensione OpenSSL (usata per cifrare la richiesta e decifrare la risposta). Il modulo non si installa su versioni precedenti di PHP né senza OpenSSL.

Account CCAvenue: ti serve un account commerciante CCAvenue con Merchant ID, Access Code e Working Key. Access Code e Working Key vengono emessi per un dominio web, quindi generali per il dominio di questo negozio. CCAvenue usa le stesse credenziali per l'ambiente di test; l'accesso al test deve essere abilitato per il tuo account da CCAvenue. Il modulo utilizza gli endpoint CCAvenue India.

Valuta: la valuta del carrello viene inviata a CCAvenue così com'è. Gli account CCAvenue accettano INR per impostazione predefinita; le altre valute richiedono l'elaborazione multivaluta sul tuo account CCAvenue.

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 CCAvenue 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 alto nella pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Inserisci il Merchant ID, l'Access Code e la Working Key dalla tua dashboard CCAvenue e attiva Enable/Disable.

5. Lascia attivo Test mode durante i test, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting CCAvenue payment e CCAvenue payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox CCAvenue Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando CCAvenue è attivo ma manca il Merchant ID, l'Access Code o la Working Key (in quel caso il metodo di pagamento è nascosto al checkout finché non sono compilati tutti e tre), mostra CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken. mentre la modalità test è attiva, e ti ricorda l'elaborazione multivaluta quando la valuta predefinita del negozio non è INR.

CCAvenue

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: CCAvenue.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Credenziali API

Accedi alla tua dashboard commerciante CCAvenue (M.A.R.S.) e apri Settings > API Keys. Genera l'Access Code e la Working Key per il dominio di questo negozio. Gli spazi nelle credenziali vengono rimossi al salvataggio.

Merchant ID: il tuo Merchant ID CCAvenue numerico. Se contiene caratteri diversi dalle cifre, al salvataggio compare il messaggio CCAvenue: the Merchant ID must contain digits only — the previous value was kept., il valore salvato in precedenza resta invariato e le altre impostazioni vengono salvate.

Access Code: l'Access Code di questo sito web (Settings > API Keys).

Working Key: la Working Key (chiave di cifratura) di questo sito web. Cifra la richiesta di pagamento ed è l'unico modo per verificare la risposta di CCAvenue, quindi tienila segreta. Una Working Key salvata non viene mai più mostrata. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarla.

Clear saved Working Key: spunta la casella e fai clic su Save per rimuovere la Working Key salvata. Un campo vuoto mantiene il valore salvato.

Test mode: invia i clienti all'ambiente di test di CCAvenue (test.ccavenue.com). CCAvenue usa lo stesso Merchant ID, Access Code e Working Key per test e produzione; l'accesso al test deve essere abilitato per il tuo account da CCAvenue. In modalità test il checkout mostra TEST MODE: no real transactions will be processed. sotto il metodo di pagamento. Predefinito: attivo. Disattivalo per i pagamenti reali.

Return URL

CCAvenue riporta il cliente all'indirizzo indicato in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_ccavenue_payment/return, eventualmente con un codice lingua come /en/. Il modulo invia questo URL con ogni pagamento (come URL di reindirizzamento e di annullamento), quindi non c'è nulla da configurare in CCAvenue. Deve appartenere al dominio registrato presso CCAvenue.

Avanzate

Debug log: scrive gli eventi di CCAvenue in logs/ccavenue_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Vengono registrati solo riferimenti ordine, ID di tracciamento e stati; chiavi, dati della carta, e-mail e indirizzi non vengono registrati. 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 modulo, il registro e i riferimenti ordine CCAvenue. Gli ordini e gli stati dell'ordine del modulo restano. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita CCAvenue) e conferma. Una pagina mostra Thank you for your order. You are being redirected to CCAvenue to complete the payment. e invia il cliente alla pagina di pagamento CCAvenue. Senza JavaScript il cliente fa clic su Pay via CCAvenue oppure su Back to checkout. A questo punto non esiste ancora alcun ordine.

Ogni tentativo riceve un nuovo riferimento ordine CCAvenue composto dal numero del carrello e dall'ora. Totale e valuta del carrello, dati di fatturazione, indirizzo di consegna (quando diverso da quello di fatturazione) e un token segreto del tentativo vengono inviati nella richiesta cifrata. Nomi e indirizzi vengono ripuliti fino ai caratteri e alle lunghezze accettati da CCAvenue; paese e regione vengono inviati come nomi e il telefono solo come cifre. Il cliente sceglie carta, Net Banking, UPI, wallet o EMI nella pagina CCAvenue.

Dopo il pagamento, CCAvenue riporta il cliente con una risposta cifrata. L'ordine viene segnato come pagato solo quando CCAvenue lo conferma: la risposta deve decifrarsi con la tua Working Key, appartenere a un tentativo di questo negozio e avere lo stesso importo e la stessa valuta inviati e del totale del carrello. A quel punto l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your CCAvenue payment has been received. Per un pagamento Awaited la pagina mostra Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. Dopo una differenza di importo o di valuta mostra Your payment was received and is being reviewed by the shop. Se un ordine in attesa viene poi annullato o fallisce senza pagamento, la pagina di conferma mostra Your CCAvenue payment was not completed. Please contact us about this order.

Se il pagamento non va a buon fine, il cliente torna al checkout con Payment was not completed. Please try again or choose a different payment method. Se il cliente annulla nella pagina CCAvenue, il messaggio è Payment was cancelled. You may try again. Se la risposta non può essere verificata, il messaggio è We could not confirm the payment result. If your account was charged, please contact us before paying again. In questi casi non viene creato alcun ordine e il carrello viene conservato, così il cliente può pagare di nuovo. Se il carrello ha già un ordine, un nuovo tentativo porta direttamente alla pagina di conferma di quell'ordine invece di un secondo pagamento.

Il risultato viene preso solo dal ritorno del cliente da CCAvenue: non ci sono notifiche da server a server né richieste di stato. Se il cliente chiude il browser prima di tornare, non viene creato alcun ordine; controlla il pagamento nella dashboard CCAvenue. Il modulo non prevede rimborsi da PrestaShop, carte salvate, abbonamenti o pagamenti ricorrenti, né un modulo carta sul sito, e non supporta CCAvenue UAE né altre piattaforme regionali.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a CCAvenue e non è tornato, oppure il pagamento non è riuscito o è stato annullato. Esiste solo il carrello. Controlla il pagamento nella dashboard CCAvenue se il cliente non torna.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID di tracciamento CCAvenue come ID transazione, e una nota mostra il riferimento bancario, l'ID di tracciamento e la modalità di pagamento.

Awaiting CCAvenue payment: CCAvenue ha segnalato il pagamento come Awaited (la banca non l'ha ancora confermato). L'ordine non viene mai segnato come non riuscito finché il denaro potrebbe ancora essere incassato. Verificalo nella dashboard CCAvenue prima di evadere l'ordine. Una risposta successiva con lo stesso ID di tracciamento viene comunque applicata: Success imposta Payment accepted, Failure imposta Payment error e Aborted imposta Canceled.

CCAvenue payment on hold: CCAvenue ha confermato un pagamento il cui importo o la cui valuta differisce dal carrello o da quanto inviato (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento), oppure il cliente ha pagato dopo che l'ordine era stato annullato. La nota mostra l'importo ricevuto e quello atteso. L'importo segnalato da CCAvenue viene registrato come pagamento dell'ordine quando la valuta corrisponde. Controlla il pagamento nella dashboard CCAvenue, poi evadi l'ordine o rimborsa il pagamento.

Un fallimento tardivo non modifica mai un ordine pagato. Se per un ordine già pagato arriva un altro pagamento riuscito (per esempio da due schede del browser), l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella dashboard CCAvenue.

Blocco pagamento CCAvenue

La pagina dell'ordine mostra un blocco CCAvenue payment con l'ID ordine CCAvenue, l'ID di tracciamento, lo stato, il riferimento bancario, la modalità di pagamento e il nome della carta, l'importo inviato e quello ricevuto, la data e il messaggio di CCAvenue, e un badge Test mode per i pagamenti di test. Le note CCAvenue sono messaggi privati dell'ordine, visibili solo nel back office.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il pagamento nella dashboard CCAvenue, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox CCAvenue Payment è il primo blocco di Modules > Module Manager > VibeFox CCAvenue Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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 ci sono la riga Product: presta-payment-ccavenue 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 inclusi inglese e russo).

Se la chiave non viene accettata, il blocco spiega 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 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: quello 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, CCAvenue 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. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per 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 quando il cliente torna da CCAvenue.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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

CCAvenue non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che siano impostate tutte e tre le credenziali: Merchant ID, Access Code e Working Key. La pagina delle impostazioni mostra un avviso quando ne manca una. 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 da CCAvenue al tuo negozio, per esempio perché ha chiuso il browser. Il modulo non ha notifiche da server a server. Controlla il pagamento nella dashboard CCAvenue e crea o aggiorna l'ordine manualmente.

Ogni pagamento termina con We could not confirm the payment result: la risposta non può essere decifrata. La Working Key è sbagliata, appartiene a un altro dominio o è stata copiata con caratteri in più. Genera le chiavi per il dominio di questo negozio e incollale di nuovo. Attiva Debug log e controlla il campo Log nella pagina del modulo.

CCAvenue mostra un errore prima della pagina di pagamento: verifica che Access Code e Working Key siano stati generati per questo dominio, che il Return URL appartenga al dominio registrato presso CCAvenue e, in modalità test, che CCAvenue abbia abilitato l'accesso al test per il tuo account. Per una valuta diversa da INR, sul tuo account CCAvenue deve essere attiva l'elaborazione multivaluta.

Il cliente vede This payment method is temporarily unavailable: manca una delle credenziali, oppure il totale del carrello è zero. Debug log mostra il motivo.

Il cliente vede This payment method is not available: il modulo è disattivato, oppure non è consentito per la valuta del carrello, il paese o il gruppo cliente in Payment > Preferences.

Il cliente vede Payment gateway error: encryption failed: la richiesta non è stata cifrata. Verifica che l'estensione OpenSSL di PHP sia installata.

Il Merchant ID non cambia al salvataggio: il valore contiene caratteri diversi dalle cifre. Inserisci solo i numeri del tuo Merchant ID.

L'ordine è CCAvenue payment on hold o Awaiting CCAvenue payment: leggi la nota dell'ordine (vedi Stati dell'ordine). Verifica il pagamento nella dashboard CCAvenue, poi evadi l'ordine o rimborsa il pagamento.

Per gli sviluppatori, il modulo offre l'hook actionCcavenueRequestParams (modifica i dati inviati a CCAvenue prima della cifratura, per esempio da merchant_param2 a merchant_param5; i valori non devono contenere &; non modificare amount, currency, order_id né merchant_param1).

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox CCAvenue Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. La conferma ti ricorda che impostazioni e riferimenti CCAvenue vengono conservati, a meno che Delete data on uninstall non sia attivo. Se è attivo, vengono rimosse le impostazioni del modulo, il registro e i riferimenti ordine CCAvenue. Se è disattivo, tutto viene conservato per una successiva reinstallazione. Gli stati dell'ordine Awaiting CCAvenue payment e CCAvenue payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e i propri ID transazione.

CCAvenue è un marchio del rispettivo proprietario. Questo modulo non è affiliato a CCAvenue né da essa approvato.