MevvPos Documentation

Installazione

MevvPos richiede WordPress 6.0+, PHP 8.1+ e WooCommerce 9.0 o successivo. WooCommerce è una dipendenza obbligatoria, dichiarata nell’intestazione del plugin: senza di esso WordPress rifiuta l’attivazione, e sulle versioni più vecchie di WordPress il plugin semplicemente non fa nulla.

Carichi il plugin da Plugin → Aggiungi nuovo → Carica plugin e lo attivi.
Apra MevvPos nel menu di amministrazione a sinistra. C’è anche una scorciatoia sotto WooCommerce, dove i commercianti tendono a cercare le impostazioni di pagamento.
Nella scheda Generale, attivi il metodo di pagamento e imposti il titolo che il cliente vedrà al momento del pagamento.
In API della banca, scelga la Sua banca e inserisca le credenziali che le ha fornito.
In Rate e commissioni, inserisca i Suoi tassi di rateizzazione.
Provi con le credenziali di test della Sua banca prima di andare in produzione.

L’edizione gratuita non crea tabelle nel database né registra alcuna attività pianificata. Tutto risiede nelle opzioni di WordPress e nei metadati dell’ordine.

Pro è un plugin a parte, installato accanto a quello gratuito — non lo sostituisce. Il plugin gratuito è pubblicato su WordPress.org, dove tutto ciò che è pubblicato può essere ridistribuito sotto GPL; tenere il codice a pagamento nello stesso pacchetto lo avrebbe reso legalmente ridistribuibile da chiunque avesse cancellato i controlli di licenza. La chiave di licenza si inserisce nella scheda Licenza.

Aprire WooCommerce → Impostazioni → Pagamenti → MevvPos La reindirizza alla schermata di MevvPos. È deliberato: c’è un solo posto per queste impostazioni, non due che possano contraddirsi.

Come funziona

Lei definisce uno o più record POS. Un record POS è il POS virtuale di una banca: le sue credenziali, l’indirizzo del gateway, le sue percentuali per le rate.
Al checkout il cliente digita la sua carta. Le prime sei cifre — il BIN — identificano la banca che l’ha emessa.
MevvPos cerca il BIN e invia il pagamento al Suo POS presso quella banca, se ne ha uno. Altrimenti ripiega sul Suo POS predefinito.
Le rate vengono offerte solo quando la carta appartiene alla banca di quel POS, perché le banche non concedono rateizzazioni sulle carte di un’altra banca.
Il cliente passa dal 3-D Secure della banca, e la banca torna a un unico indirizzo di callback sul Suo sito.
La firma del ritorno viene verificata con la chiave del POS che l’ordine ha effettivamente usato, l’ordine viene completato e l’esito registrato.

Numero della carta, scadenza e CVV non vengono mai scritti nel Suo database né nella sessione di WooCommerce. Gli unici dati di carta conservati sono le prime sei cifre e il nome della banca riconosciuta.

Record POS

La barra dei POS sta sopra le schede ed è visibile in tutte. Ogni scheda mostra la banca, il numero esercente e un contrassegno quando qualcosa richiede la Sua attenzione.

Predefinito: Il POS che incassa quando non si trova una corrispondenza migliore. Ce n’è sempre esattamente uno.
Inattivo: Conservato ma non attivo negli incassi. Usi questo invece di eliminare quando un POS è configurato ma non è ancora operativo presso la banca — altrimenti un cliente con la carta di quella banca non potrebbe pagare.
In attesa di una licenza: Il record esiste ma è inattivo perché la licenza non è attiva. Non è stato eliminato nulla; riprende da dove si era fermato quando la licenza viene rinnovata.
I dati API non sono stati inseriti: Il record non ha ancora un numero esercente.

Le banche sono indicate da una fascia di colore invece che da un logo. I loghi bancari sono marchi registrati, e quindici di essi sono insieme un’esposizione legale e una manutenzione perpetua — Lei sa già qual è la Sua banca.

L’ultimo POS non può essere eliminato e l’ultimo abilitato non può essere disattivato. Per smettere del tutto di accettare pagamenti con carta, disattivi invece il metodo di pagamento nella scheda Generale.

L’edizione gratuita consente un POS. I record aggiuntivi sono una funzionalità Pro — e di conseguenza lo è anche l’instradamento per BIN: con un solo POS non c’è nulla tra cui instradare.

API della banca — credenziali e indirizzo del gateway

Banca: Scelga la banca presso cui si trova il Suo POS. Sia l’indirizzo del gateway sia l’elenco dei BIN usato per le rate dipendono da questa scelta. Gli istituti ancora privi di implementazione sono elencati con “— yakında” (in arrivo) e non sono selezionabili.
Numero esercente (Client ID): Il numero esercente che Le ha assegnato la banca.
Chiave esercente (store key): La chiave di sicurezza dell’esercente. Salvata come campo password; una volta salvata viene mostrata mascherata.
Gate URL: L’indirizzo a cui il modulo di pagamento invia i dati.
Attiva la modalità test: Blocca il reindirizzamento automatico così può ispezionare la richiesta prima che venga inviata.

Lasciare vuota la Store Key al salvataggio significa “non modificarla”. Scrivere il valore vuoto cancellerebbe la chiave e il Suo negozio smetterebbe di incassare senza un solo messaggio di errore. La stessa regola vale per gli altri campi segreti.

Alcune famiglie richiedono credenziali aggiuntive, e il modulo le mostra solo per la banca che ha scelto:

Garanti BBVA — Merchant ID, nome utente di autorizzazione, password di autorizzazione.
VakıfBank — Terminal No, e un indirizzo MPI (lo lasci vuoto per usare l’indirizzo di prova).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — nessun campo aggiuntivo: la chiave API va nel Numero esercente e il segreto nella Chiave esercente.

Queste credenziali aggiuntive entrano nella firma. Se una manca, la firma viene calcolata con un valore vuoto e la banca rifiuta il pagamento in silenzio — nessun errore, nessun messaggio, solo un rifiuto.

Per le sette banche NestPay l’indirizzo del gateway viene compilato dalla scelta della banca, quindi può lasciare Gate URL vuoto. Per le altre il campo non è precompilato: inserisca l’indirizzo che Le ha dato la banca o il provider, altrimenti il modulo di pagamento non ha dove inviare i dati.

I tredici istituti supportati

NestPay / Asseco (Payten): İş Bankası, Akbank, Halkbank, QNB, Şekerbank, TEB, Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
Istituti di pagamento: iyzico, PayTR, Craftgate, Sipay

Gli istituti privi di implementazione restano di proposito nell’elenco delle banche, contrassegnati con “— yakında”. Rimuoverli nasconderebbe quali famiglie di protocollo mancano ancora. Se la Sua è tra queste, la scheda Richiesta banca è il posto in cui segnalarlo.

Solo la firma NestPay ha un test su vettore di riferimento rispetto all’esempio pubblicato dalla banca stessa. Ogni altro provider è contrassegnato come beta nel proprio codice: il flusso è implementato secondo la documentazione, ma non è ancora stato verificato end-to-end con un conto esercente reale presso quell’istituto. Quell’etichetta resta finché non lo sarà.

Gli istituti di pagamento non emettono carte, quindi non hanno un elenco di BIN. Li seleziona come Suo POS invece di instradarvi le carte.

Instradamento basato su BIN

Le prime sei cifre di una carta identificano la banca che l’ha emessa. MevvPos confronta esattamente quelle sei cifre.

Un’istantanea della tabella dei BIN è inclusa nel plugin — 1.449 BIN di 36 banche nella build attuale — così l’instradamento funziona offline, nell’edizione gratuita, fin dal momento dell’installazione.
Pro la aggiorna ogni settimana dai nostri server. L’aggiornamento viene fuso sopra la tabella inclusa invece di sostituirla: una risposta parziale o vuota non deve mai lasciare un negozio del tutto privo di dati BIN.
Una risposta che porta meno di cento BIN viene rifiutata perché non plausibile e non viene scritta.
I conflitti — lo stesso BIN rivendicato da due banche — vengono risolti dalla nostra parte prima che l’elenco venga inviato. Un negozio che li risolvesse in locale potrebbe considerare una carta come “nostra” e allo stesso tempo instradarla altrove.

Un BIN non riconosciuto non viene mai rifiutato. Ricade sul Suo POS predefinito. Respingere una carta che semplicemente non abbiamo in archivio significherebbe perdere una vendita per proteggere una tabella di consultazione.

La stessa tabella risponde a una seconda domanda, diversa, al checkout: questa carta è della banca di questo POS? È ciò che decide se offrire le rate — vedi sotto.

L’accuratezza dei BIN non è una funzione a pagamento. Ciò che Pro paga è l’aggiornamento, non la correttezza: l’elenco incluso è lo stesso elenco, solo congelato al momento della build.

Rate e commissione

I tassi si impostano per POS, dal pagamento in un’unica soluzione fino a dodici rate, nella scheda Rate e commissioni. Sono percentuali: scriva 5.50 per 5,5%.

0: L’opzione viene mostrata e non viene aggiunta alcuna commissione.
Vuoto: L’opzione non viene mostrata affatto. Vuoto e zero non sono la stessa cosa.

La commissione compare nel carrello come una voce imponibile denominata “N Taksit Komisyonu” (commissione per N rate), calcolata sul totale del carrello comprensivo di spedizione e imposte.

Le rate vengono offerte solo sulle carte emesse dalla banca di quel POS, e questo viene imposto sul server — non semplicemente nascosto nell’interfaccia. Una carta di un’altra banca viene riportata al pagamento unico e la commissione viene azzerata.

L’edizione gratuita mostra al cliente al massimo tre rate; Pro alza il tetto a dodici. Il tetto viene applicato in tre punti: l’elenco che il cliente vede, il valore che arriva con il modulo e il valore inviato alla banca. Quest’ultimo conta perché un valore scelto quando la licenza era ancora valida può sopravvivere nella sessione.

Il modulo delle impostazioni mostra sempre tutti e dodici i campi, qualunque sia la Sua licenza. Se sparissero alla scadenza di una licenza, salvare la pagina cancellerebbe in silenzio tassi già inseriti. I campi oltre il Suo limite sono contrassegnati come “Sbloccato in Pro” e i Suoi numeri vengono conservati.

Non esiste una tabella delle rate fornita dalla banca. Le percentuali sono quelle che inserisce Lei, e la commissione di un ordine passato viene calcolata con la percentuale in vigore il giorno della vendita — cambiare una percentuale oggi non riscrive il report di ieri.

Il flusso di pagamento e la gestione della carta

Ogni famiglia passa dal 3-D Secure. Non esiste una modalità senza 3D né un’impostazione per disattivarlo.

Flusso a modulo: NestPay, Garanti, PayTR e Sipay: il browser invia un modulo firmato alla banca, il cliente si autentica e la banca torna al Suo sito.
Flusso da server: VakıfBank, iyzico e Craftgate: il Suo server dialoga con il provider, ottiene la pagina 3-D, la mostra e completa la vendita da server a server dopo l’autenticazione.

La banca torna sempre a un unico indirizzo del Suo sito: ?wc-api=mevvpos_callback. La firma di quel ritorno viene verificata con la chiave del POS che l’ordine ha effettivamente usato, registrata sull’ordine stesso — con più di un POS, verificare con la chiave sbagliata produce un errore di hash su ogni singolo pagamento.

La carta non arriva mai al Suo database. Resta nel browser per la durata del reindirizzamento e viene poi rimossa. Se non c’è quando la pagina di pagamento si carica — una nuova scheda, un ricaricamento, l’archiviazione disattivata, un ritorno indietro dalla banca — viene mostrato un modulo carta visibile invece di inviare campi vuoti alla banca. Il modulo carta è visibile per impostazione predefinita, di proposito: un flusso di pagamento non può dipendere dall’esecuzione di JavaScript.

Quando la banca approva il pagamento, l’ordine viene completato anche se il codice di stato 3-D era inatteso — una nota d’ordine registra l’anomalia e Le chiede di confermarla dalla schermata della banca. Se la banca dice approvato, il cliente è già stato addebitato; rifiutare significherebbe “la Sua carta è stata addebitata ma il Suo ordine è fallito”.

Ogni tentativo registra il POS usato, la banca e il BIN della carta, il numero di rate e la percentuale, l’esito, il codice e il messaggio di risposta della banca, e i riferimenti di autorizzazione e di transazione.

Report

La scheda Report mostra il fatturato, le transazioni riuscite, il tasso di successo e la ripartizione tra pagamento unico e rateizzato, con un grafico giornaliero. Le transazioni ancora in attesa della risposta della banca sono conteggiate a parte e restano fuori dal tasso di successo.

L’edizione gratuita riporta una finestra fissa di 30 giorni. Pro aggiunge intervalli di 7 / 30 / 90 giorni e tre suddivisioni:

Carico di rate e commissioni — numero, ricavi e onere delle commissioni per fascia di rate.
Dettaglio per POS e banca — ricavi, successi, fallimenti e tasso di successo per ogni POS e per ogni banca emittente.
Distribuzione dei codici di rifiuto — con esportazione CSV. Un codice di rifiuto che si ripete indica qualcosa che può correggere: fondi insufficienti è un problema del cliente, ma gli errori di verifica 3-D e di configurazione del POS sono Suoi.

I dati alla base dei report sono raccolti dal plugin gratuito, quindi lo storico continua ad accumularsi che abbia Pro o no. Deve essere così: i dati passati non si possono generare retroattivamente al momento dell’aggiornamento.

Un negozio appena installato non ha alcun grafico. La registrazione comincia con il plugin, e la schermata si riempie dopo il primo tentativo di pagamento.

Richieste bancarie e assistenza

Richiesta banca: Elenca ogni istituto non ancora implementato, con il motivo: o la famiglia di protocollo non è stata determinata, oppure la famiglia è nota e stiamo aspettando la documentazione. Può aprire una richiesta per uno di essi, o segnalare un istituto che non compare affatto nell’elenco.
Assistenza: Un oggetto, il POS o la banca interessata, che cosa succede quando fa che cosa, e il messaggio di errore mostrato dalla banca.

Il modulo di assistenza Le chiede di non includere numeri di carta o codici di sicurezza. Non servono mai per diagnosticare un problema di pagamento, e con nessuno dei due moduli viene inviato alcun dato di pagamento o di carta.

Il plugin gratuito contatta i nostri server solo quando preme uno di questi pulsanti. Non viene inviato nulla in modo pianificato e nell’edizione gratuita non c’è alcuna chiamata di licenza.

Free e Pro

La divisione è nella quantità, non nella capacità. Tutti e tredici gli istituti, il 3-D Secure, la modalità di prova, un volume illimitato di transazioni e il report base dei ricavi sono nell’edizione gratuita.

Gratuito: Un POS. Fino a tre rate mostrate al cliente. Un riepilogo dei ricavi fisso a 30 giorni. La tabella dei BIN inclusa nel plugin.
Pro: Record POS illimitati — e quindi instradamento per BIN. Fino a dodici rate. Intervalli di report e suddivisioni per POS, banca, rate e codice di rifiuto, con esportazione CSV. Aggiornamento settimanale dei BIN dal vivo. Aggiornamenti automatici per il plugin Pro stesso.

Quando una licenza scade o manca:

Il Suo negozio continua a incassare. Non c’è alcun controllo di licenza sul percorso del pagamento. Tagliare i ricavi di un negozio non è un modo accettabile di mandare un promemoria di rinnovo.
Il POS predefinito continua a funzionare, 3-D Secure e modalità di prova compresi.
I record POS aggiuntivi diventano inattivi ma non vengono mai eliminati, credenziali comprese. Riprendono al rinnovo.
Il tetto delle rate torna a tre. Le percentuali inserite oltre quel tetto vengono conservate, non cancellate.
I report tornano al riepilogo a 30 giorni. Lo storico raccolto non viene eliminato.
L’aggiornamento dei BIN dal vivo si ferma; la tabella inclusa continua a funzionare.

Se i nostri server non sono raggiungibili, una licenza attiva continua a funzionare per sette giorni sulla base dell’ultimo controllo riuscito. Ma una licenza la cui data di scadenza è già passata risulta comunque scaduta — altrimenti bloccare il nostro indirizzo sarebbe un modo per prolungare una licenza di una settimana.

Quando qualcosa non funziona

La banca rifiuta ogni pagamento senza alcun messaggio utile: Quasi sempre è la firma. Una firma sbagliata non genera errori da nessuna parte — la banca semplicemente rifiuta. Controlli il numero esercente, la chiave esercente e le eventuali credenziali aggiuntive di quella famiglia: entrano tutte nella firma. Una prova utile è che le banche rispondono diversamente a un errore di firma e a una carta non valida; ricevere un messaggio di “carta non valida” significa che la firma è corretta.
“Errore di hash” al ritorno, con più di un POS: Il ritorno è una richiesta separata, priva di sessione. MevvPos registra quale POS ha usato un ordine e verifica con quella chiave. Se ha eliminato il record POS con cui un ordine è stato pagato, la verifica ripiega sul POS predefinito e può fallire.
Il cliente arriva a una pagina di pagamento vuota, o il pulsante Öde (Paga) non fa nulla: Un plugin di cache o di ottimizzazione sta posticipando gli script. Su LiteSpeed, escluda mevvpos, jquery e gli script front-end di WooCommerce dall’elenco dei ritardi. Il modulo carta viene mostrato per impostazione predefinita così il flusso continua a funzionare, ma il reindirizzamento automatico no.
L’ordine resta “in attesa” dopo un pagamento riuscito: La banca o il provider non ha raggiunto l’indirizzo di callback. Verifichi che ?wc-api=mevvpos_callback sia raggiungibile dall’esterno — una modalità di manutenzione, una restrizione per IP o un muro di accesso davanti al sito lo bloccheranno.
Il modulo di pagamento viene inviato alla stessa pagina: Il campo Gate URL è vuoto per una banca il cui indirizzo non è precompilato. Inserisca l’indirizzo che Le ha dato la banca o il provider.
La modalità di prova è attiva ma il pagamento va comunque alla banca reale: La modalità di prova blocca il reindirizzamento automatico e Le mostra la richiesta; non riscrive l’indirizzo del gateway per le banche NestPay. Metta l’indirizzo di prova della Sua banca in Gate URL mentre sta facendo i test.
Le rate non compaiono: O la percentuale per quel numero di rate è vuota invece che zero, o la carta è di un’altra banca, oppure sta oltre il tetto di tre dell’edizione gratuita.
Le carte finiscono al POS sbagliato dopo un aggiornamento: Le versioni più vecchie contenevano intervalli di BIN scritti a mano in parte errati. Verifichi che ogni POS sia archiviato sotto la banca presso cui si trova davvero.
La schermata di amministrazione appare priva di stile, o una correzione non compare: Una cache del browser obsoleta. Ricarichi la pagina bypassando la cache.

Limiti

L’elenco qui sotto è deliberato. Nulla di ciò è un difetto.

Nessun rimborso né annullamento da WordPress. Il plugin non implementa l’API dei rimborsi di WooCommerce e nessun provider prevede una chiamata di rimborso. Effettui il rimborso dalla schermata della Sua banca.
Solo lira turca. Il codice valuta è fisso in ogni provider; non esiste un’impostazione multivaluta.
Nessuna carta salvata, nessuna tokenizzazione, nessun abbonamento o pagamento ricorrente.
Nessuna preautorizzazione. Ogni transazione è una vendita diretta.
Nessun instradamento basato su regole. L’instradamento avviene solo per banca emittente — non per importo, circuito della carta o paese.
Il modulo di pagamento è scritto per il checkout classico di WooCommerce. Nel pacchetto non è incluso alcun componente separato per il Checkout a blocchi.
3D Pay Hosting è stato scartato di proposito. La pagina ospitata elimina l’ambito PCI, ma elimina anche il BIN e la tabella delle rate — e tutto il valore di questo plugin sta nell’instradamento che essi rendono possibile.
Nessun editor dei BIN. La tabella è gestita da noi e fusa con l’aggiornamento dal vivo; non c’è alcuna schermata per modificarla a mano.
Ventisei istituti sono elencati ma non implementati. Restano visibili perché la lacuna resti visibile.
Ogni provider tranne NestPay è dichiarato beta da noi stessi finché non sia stato verificato end-to-end con un conto esercente reale.
Le schede sono nella pagina. Le voci della barra laterale aprono la schermata di MevvPos; cambi scheda nella pagina stessa.

Ciò che non viene mai memorizzato, in nessuna forma: il numero della carta, la data di scadenza e il codice di sicurezza. Gli unici dati di carta conservati sono le prime sei cifre e la banca che identificano. Memorizzare il codice di sicurezza è vietato in ogni circostanza, e persino mascherato ne rivela la lunghezza.

Da un solo POS virtuale a una carta instradata alla banca che l’ha emessa.