MevvPos Documentation

Instalacja

Wtyczka MevvPos wymaga WordPress 6.0+, PHP 8.1+ oraz WooCommerce 9.0 lub nowszego. WooCommerce jest twardą zależnością zadeklarowaną w nagłówku wtyczki: bez niego WordPress odmawia włączenia, a na starszych wersjach WordPress wtyczka po prostu nic nie robi.

Wgraj wtyczkę w Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer i włącz ją.
Otwórz pozycję MevvPos w lewym menu administracyjnym. Skrót jest też w sekcji WooCommerce, gdzie sprzedawcy zwykle szukają ustawień płatności.
W zakładce Ogólne należy włączyć metodę płatności i ustawić tytuł, który klient zobaczy przy składaniu zamówienia.
W zakładce API banku należy wybrać swój bank i wpisać dane uwierzytelniające, które od niego otrzymano.
W zakładce Raty i prowizja należy wpisać własne stawki ratalne.
Przed uruchomieniem produkcyjnym przetestuj wszystko na testowych danych dostępowych z banku.

Edycja darmowa nie tworzy żadnych tabel w bazie danych ani nie rejestruje żadnego zadania cyklicznego. Wszystko żyje w opcjach WordPress i w polach meta zamówienia.

Pro to osobna wtyczka, instalowana obok darmowej — nie jest jej zamiennikiem. Darmowa wtyczka jest publikowana na WordPress.org, gdzie wszystko, co opublikowane, może być rozpowszechniane dalej na licencji GPL; pozostawienie płatnego kodu w tej samej paczce sprawiłoby, że każdy, kto usunąłby sprawdzanie licencji, mógłby go legalnie rozpowszechniać. Klucz licencyjny wpisuje się w zakładce Licencja.

Otwarcie WooCommerce → Ustawienia → Płatności → MevvPos przekierowuje na ekran wtyczki MevvPos. To zamierzone: te ustawienia mają jedno miejsce, a nie dwa, które mogłyby się różnić.

Jak to działa

Definiuje się jeden lub więcej rekordów POS. Rekord POS to wirtualny POS jednego banku: jego dane dostępowe, adres bramki i stawki rat.
Na stronie zamówienia klient wpisuje dane karty. Pierwsze sześć cyfr — numer BIN — wskazuje bank, który ją wydał.
Wtyczka MevvPos sprawdza numer BIN i wysyła płatność do własnego POS w tym banku, jeżeli taki istnieje. W przeciwnym razie płatność trafia do POS domyślnego.
Raty są proponowane wyłącznie wtedy, gdy karta należy do banku danego POS, ponieważ banki nie udzielają rat na karty innego banku.
Klient przechodzi przez 3-D Secure w banku, a bank wraca pod jeden adres zwrotny w witrynie.
Podpis na powrocie weryfikowany jest kluczem tego POS, którego zamówienie faktycznie użyło, zamówienie zostaje ukończone, a wynik zapisany.

Numer karty, data ważności i kod CVV nigdy nie trafiają do bazy danych witryny ani do sesji WooCommerce. Jedyne zachowywane dane karty to pierwsze sześć cyfr i rozpoznana nazwa banku.

Rekordy POS

Pasek POS znajduje się nad kartami i jest widoczny na każdej z nich. Każda karta pokazuje bank, numer sprzedawcy oraz plakietkę, gdy coś wymaga uwagi.

Domyślny: POS, który przyjmuje płatność, gdy nie znaleziono lepszego dopasowania. Zawsze jest dokładnie jeden.
Nieaktywny: Zachowany, ale nieprzyjmujący płatności. Z tego stanu należy korzystać zamiast usuwania, gdy POS jest skonfigurowany, ale nie działa jeszcze po stronie banku — inaczej klient z kartą tego banku nie mógłby zapłacić.
Oczekiwanie na licencję: Rekord istnieje, ale jest uśpiony, ponieważ licencja nie jest aktywna. Nic nie zostało usunięte; po odnowieniu licencji podejmuje pracę w tym samym miejscu.
Dane API nie zostały wprowadzone: Rekord nie ma jeszcze numeru sprzedawcy.

Banki oznaczane są kolorowym paskiem, a nie logo. Loga banków to znaki towarowe, a piętnaście z nich to zarówno ryzyko prawne, jak i stałe utrzymanie — i tak wiadomo, który bank jest własny.

Ostatniego POS-a nie można usunąć, a ostatniego włączonego nie można wyłączyć. Aby całkowicie przestać przyjmować płatności kartą, należy zamiast tego wyłączyć metodę płatności w zakładce Ogólne.

Edycja darmowa pozwala na jeden POS. Dodatkowe rekordy to możliwość wersji Pro — a co za tym idzie, także kierowanie po numerze BIN: przy jednym POS nie ma między czym kierować.

API banku — dane uwierzytelniające i adres bramki

Bank: Wybierz bank, w którym prowadzony jest POS. Od tego wyboru zależy adres bramki oraz lista BIN używana do rat. Instytucje bez gotowej implementacji wypisane są z dopiskiem „— yakında” (wkrótce) i nie da się ich wybrać.
Numer akceptanta (Client ID): Numer sprzedawcy otrzymany z banku.
Klucz akceptanta (Store key): Klucz zabezpieczający sprzedawcy. Przechowywany jako pole hasła; po zapisaniu pokazywany w postaci zamaskowanej.
Gate URL: Adres, pod który wysyłany jest formularz płatności.
Włącz tryb testowy: Zatrzymuje automatyczne przekierowanie, aby można było obejrzeć żądanie przed jego wysłaniem.

Pozostawienie pola Store Key pustym przy zapisie oznacza „nie zmieniaj go”. Zapisanie pustej wartości wymazałoby klucz, a sklep przestałby przyjmować płatności bez jednego komunikatu o błędzie. Ta sama zasada dotyczy pozostałych pól tajnych.

Niektóre rodziny protokołów wymagają dodatkowych danych dostępowych, a formularz pokazuje je tylko dla wybranego banku:

Garanti BBVA — Merchant ID, nazwa użytkownika autoryzacji, hasło autoryzacji.
VakıfBank — Terminal No oraz adres MPI (pozostawienie pustego pola oznacza użycie adresu testowego).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — bez dodatkowych pól: klucz API wpisuje się w Numer akceptanta, a sekret w Klucz akceptanta.

Te dodatkowe dane dostępowe wchodzą do podpisu. Gdy brakuje jednego z nich, podpis liczony jest z pustą wartością, a bank odrzuca płatność po cichu — bez błędu, bez komunikatu, po prostu odmowa.

Dla siedmiu banków NestPay adres bramki wypełniany jest na podstawie wyboru banku, więc pole Gate URL można zostawić puste. Dla pozostałych pole nie jest wypełniane z góry: należy wpisać adres otrzymany od banku lub dostawcy, inaczej formularz płatności nie ma dokąd wysyłać danych.

Trzynaście obsługiwanych instytucji

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

Instytucje bez implementacji celowo pozostają na liście banków, oznaczone „— yakında”. Usunięcie ich ukryłoby, których rodzin protokołów wciąż brakuje. Jeśli chodzi o taki właśnie bank, miejscem na zgłoszenie tego jest zakładka Zgłoszenie banku.

Tylko podpis NestPay ma test na wzorcowym wektorze zgodny z opublikowanym przykładem samego banku. Każdy inny dostawca oznaczony jest w swoim kodzie źródłowym jako beta: przepływ jest zaimplementowany zgodnie z dokumentacją, ale nie został jeszcze zweryfikowany od początku do końca na działającym koncie sprzedawcy w tej instytucji. Ta etykieta zostaje, dopóki tak się nie stanie.

Instytucje płatnicze nie wydają kart, więc nie mają listy BIN. Wybiera się je jako własny POS, a nie kieruje się do nich kart.

Kierowanie na podstawie BIN

Pierwsze sześć cyfr karty wskazuje bank, który ją wydał. Wtyczka MevvPos dopasowuje dokładnie po tych sześciu cyfrach.

Migawka tabeli BIN dostarczana jest wewnątrz wtyczki — 1.449 numerów BIN z 36 banków w bieżącej kompilacji — więc kierowanie działa offline, w edycji darmowej, od chwili instalacji.
Wersja Pro odświeża ją co tydzień z naszych serwerów. Odświeżenie nakłada się na tabelę dostarczoną w pakiecie, zamiast ją zastępować: częściowa albo pusta odpowiedź nigdy nie może zostawić sklepu zupełnie bez danych BIN.
Odpowiedź niosąca mniej niż sto numerów BIN jest odrzucana jako niewiarygodna i nie zostaje zapisana.
Konflikty — ten sam numer BIN przypisywany przez dwa banki — rozstrzygane są po naszej stronie, zanim lista zostanie wysłana. Sklep rozstrzygający je lokalnie mógłby jednocześnie uznać kartę za „naszą” i skierować ją gdzie indziej.

Nierozpoznany numer BIN nigdy nie powoduje odmowy. Karta trafia wtedy do POS domyślnego. Odprawienie z kwitkiem karty, której po prostu nie ma w kartotece, byłoby utratą sprzedaży w obronie tabeli wyszukiwania.

Ta sama tabela odpowiada na stronie zamówienia na drugie, inne pytanie: czy ta karta pochodzi z banku tego POS? To właśnie decyduje o tym, czy proponowane są raty — patrz niżej.

Dokładność danych BIN nie jest funkcją płatną. Wersja Pro płaci za świeżość, a nie za poprawność: lista w pakiecie to ta sama lista, tyle że zamrożona w chwili kompilacji.

Raty i prowizja

Stawki ustawia się osobno dla każdego POS-a, od płatności jednorazowej po dwanaście rat, w zakładce Raty i prowizja. Są to wartości procentowe: dla 5,5% należy wpisać 5.50.

0: Opcja jest pokazywana i nie dolicza się prowizji.
Puste: Opcja w ogóle nie jest pokazywana. Pusta wartość i zero to nie to samo.

Prowizja pojawia się w koszyku jako opłata podlegająca opodatkowaniu o nazwie „N Taksit Komisyonu”, liczona od sumy koszyka wraz z wysyłką i podatkiem.

Raty proponowane są wyłącznie na kartach wydanych przez bank danego POS, a pilnuje tego serwer — nie jest to jedynie ukryte w interfejsie. Karta z innego banku zostaje przymusowo sprowadzona do płatności jednorazowej, a opłata wyzerowana.

Edycja darmowa pokazuje klientowi najwyżej trzy raty; wersja Pro podnosi pułap do dwunastu. Pułap stosowany jest w trzech miejscach: na liście, którą widzi klient, w wartości przychodzącej z formularza i w wartości wysyłanej do banku. To ostatnie ma znaczenie, ponieważ wartość wybrana, gdy licencja była jeszcze ważna, może przetrwać w sesji.

Formularz ustawień zawsze pokazuje wszystkie dwanaście pól, niezależnie od licencji. Gdyby znikały po wygaśnięciu licencji, zapisanie strony po cichu usunęłoby już wprowadzone stawki. Pola powyżej limitu są oznaczone jako „Odblokowane w Pro”, a wpisane liczby zostają zachowane.

Nie ma tabeli rat dostarczanej przez bank. Stawki są tymi, które wpisze sprzedawca, a prowizja dla dawnego zamówienia liczona jest ze stawki obowiązującej w dniu sprzedaży — zmiana stawki dziś nie przepisuje wczorajszego raportu.

Przepływ płatności i obsługa karty

Każda rodzina protokołów przechodzi przez 3-D Secure. Nie ma trybu bez 3-D ani ustawienia, które by go wyłączało.

Przepływ formularzowy: NestPay, Garanti, PayTR i Sipay: przeglądarka wysyła do banku podpisany formularz, klient się uwierzytelnia, a bank wraca do witryny.
Przepływ serwerowy: VakıfBank, iyzico i Craftgate: serwer witryny rozmawia z dostawcą, pobiera stronę 3-D, pokazuje ją i po uwierzytelnieniu domyka sprzedaż w komunikacji serwer–serwer.

Bank zawsze wraca pod jeden adres w witrynie: ?wc-api=mevvpos_callback. Podpis na tym powrocie weryfikowany jest kluczem tego POS, którego zamówienie faktycznie użyło, zapisanym przy samym zamówieniu — przy więcej niż jednym POS weryfikacja niewłaściwym kluczem daje błąd skrótu przy każdej pojedynczej płatności.

Karta nigdy nie trafia do bazy danych. Jest przechowywana w przeglądarce na czas przekierowania i usuwana później. Jeżeli nie ma jej tam w chwili wczytania strony płatności — nowa karta przeglądarki, odświeżenie, wyłączone przechowywanie, powrót z banku przyciskiem wstecz — pokazywany jest widoczny formularz karty, zamiast wysyłać do banku puste pola. Formularz karty jest domyślnie widoczny, i to celowo: przepływ płatności nie może zależeć od tego, czy JavaScript się wykonał.

Gdy bank zatwierdzi płatność, zamówienie zostaje ukończone nawet wtedy, gdy kod statusu 3-D był nieoczekiwany — notatka do zamówienia odnotowuje anomalię i prosi o potwierdzenie jej na ekranie samego banku. Skoro bank mówi „zatwierdzone”, klient został obciążony; odmowa oznaczałaby „karta została obciążona, ale zamówienie się nie powiodło”.

Każda próba zapisuje użyty POS, bank i numer BIN karty, liczbę rat i stawkę, wynik, kod i komunikat odpowiedzi banku oraz numery referencyjne autoryzacji i transakcji.

Raporty

Zakładka Raporty pokazuje przychód, udane transakcje, wskaźnik skuteczności oraz podział na płatności jednorazowe i ratalne, wraz z wykresem dziennym. Transakcje wciąż czekające na odpowiedź banku liczone są osobno i nie wchodzą do wskaźnika skuteczności.

Edycja darmowa raportuje w stałym oknie 30 dni. Wersja Pro dodaje zakresy 7 / 30 / 90 dni oraz trzy rozbicia:

Obciążenie ratami i prowizją — liczba, przychód i obciążenie prowizją dla każdego progu rat.
Rozbicie na POS i banki — przychód, sukcesy, niepowodzenia i skuteczność dla każdego POS i każdego banku wydającego kartę.
Rozkład kodów odmowy — z eksportem CSV. Powtarzający się kod odmowy wskazuje na coś, co da się naprawić: brak środków to problem klienta, ale błędy weryfikacji 3-D i konfiguracji POS należą do sprzedawcy.

Dane stojące za raportami zbiera wtyczka darmowa, więc historia narasta niezależnie od tego, czy wersja Pro jest posiadana. Tak musi być: danych z przeszłości nie da się wygenerować wstecz w chwili przejścia na wyższą wersję.

Świeżo zainstalowany sklep nie ma wykresu. Zapisywanie zaczyna się wraz z wtyczką, a ekran zapełnia się po pierwszej próbie płatności.

Wnioski o banki i wsparcie

Zgłoszenie banku: Wymienia każdą instytucję, która nie została jeszcze zaimplementowana, wraz z powodem: albo nie ustalono rodziny protokołu, albo rodzina jest znana i czekamy na dokumentację. Można otworzyć wniosek dotyczący jednej z nich albo wskazać instytucję, której na liście w ogóle nie ma.
Wsparcie: Temat, którego POS lub banku dotyczy sprawa, co się dzieje przy jakim działaniu oraz komunikat o błędzie pokazany przez bank.

Formularz wsparcia prosi, aby nie podawać numeru karty ani kodu zabezpieczającego. Nigdy nie są one potrzebne do zdiagnozowania problemu z płatnością, a żaden z tych formularzy nie wysyła danych płatności ani danych karty.

Darmowa wtyczka kontaktuje się z naszymi serwerami tylko po naciśnięciu jednego z tych przycisków. Nic nie jest wysyłane według harmonogramu, a w edycji darmowej nie ma w ogóle żadnego wywołania licencji.

Free i Pro

Podział dotyczy ilości, a nie możliwości. Wszystkie trzynaście instytucji, 3-D Secure, tryb testowy, nieograniczony wolumen transakcji i podstawowy raport przychodów są w edycji darmowej.

Za darmo: Jeden POS. Najwyżej trzy raty pokazywane klientowi. Stałe podsumowanie przychodu z 30 dni. Tabela BIN dostarczona z wtyczką.
Pro: Nieograniczona liczba rekordów POS — a więc i kierowanie po numerze BIN. Do dwunastu rat. Zakresy raportów oraz rozbicia na POS, banki, raty i kody odmowy, z eksportem CSV. Cotygodniowe odświeżanie danych BIN na żywo. Automatyczne aktualizacje samej wtyczki Pro.

Gdy licencja wygaśnie albo jej nie ma:

Sklep nadal przyjmuje płatności. Na ścieżce płatności nie ma nigdzie sprawdzania licencji. Odcięcie sklepowi przychodu nie jest dopuszczalnym sposobem przypominania o odnowieniu.
Domyślny POS działa dalej, łącznie z 3-D Secure i trybem testowym.
Dodatkowe rekordy POS zapadają w uśpienie, ale nigdy nie są usuwane, wraz z danymi dostępowymi. Po odnowieniu podejmują pracę.
Pułap rat wraca do trzech. Wpisane powyżej niego stawki są zachowywane, a nie czyszczone.
Raporty wracają do podsumowania 30-dniowego. Zebrana historia nie jest usuwana.
Odświeżanie danych BIN na żywo zatrzymuje się; tabela z pakietu działa dalej.

Jeżeli nasze serwery są nieosiągalne, aktywna licencja działa jeszcze przez siedem dni na podstawie ostatniego udanego sprawdzenia. Licencja, której własna data ważności minęła, i tak czytana jest jako wygasła — inaczej zablokowanie naszego adresu byłoby sposobem na przedłużenie licencji o tydzień.

Gdy coś nie działa

Bank odrzuca każdą płatność bez użytecznego komunikatu: Prawie zawsze chodzi o podpis. Błędny podpis nigdzie nie wywołuje błędu — bank po prostu odmawia. Należy sprawdzić numer sprzedawcy, klucz sklepu oraz wszelkie dodatkowe dane dostępowe tej rodziny protokołów: wszystkie wchodzą do podpisu. Przydatny test polega na tym, że banki inaczej odpowiadają na błąd podpisu, a inaczej na nieprawidłową kartę; komunikat o „nieprawidłowej karcie” oznacza, że podpis jest poprawny.
„Hash error” przy powrocie, gdy POS jest więcej niż jeden: Powrót to osobne żądanie bez sesji. Wtyczka MevvPos zapisuje, którego POS użyło zamówienie, i weryfikuje właśnie tym kluczem. Jeżeli rekord POS, przez który opłacono zamówienie, został usunięty, weryfikacja spada na POS domyślny i może się nie powieść.
Klient trafia na pustą stronę płatności albo przycisk Öde („Zapłać”) nic nie robi: Wtyczka pamięci podręcznej lub optymalizacji odracza skrypty. W LiteSpeed należy wyłączyć mevvpos, jquery i skrypty frontu WooCommerce z listy opóźnień. Formularz karty pokazywany jest domyślnie, więc przepływ nadal działa, ale automatyczne przekierowanie już nie.
Zamówienie pozostaje w stanie „oczekujące” po udanej płatności: Bank albo dostawca nie dotarł do adresu zwrotnego. Należy sprawdzić, czy ?wc-api=mevvpos_callback jest osiągalny z zewnątrz — tryb konserwacji, ograniczenie po adresie IP albo ściana logowania przed witryną go zablokują.
Formularz płatności wysyła dane z powrotem na tę samą stronę: Pole Gate URL jest puste dla banku, którego adres nie jest wypełniany z góry. Należy wpisać adres otrzymany od banku lub dostawcy.
Tryb testowy jest włączony, ale płatność i tak idzie do banku produkcyjnego: Tryb testowy zatrzymuje automatyczne przekierowanie i pokazuje żądanie; nie przepisuje adresu bramki dla banków NestPay. Na czas testów należy wpisać testowy adres banku w pole Gate URL.
Raty się nie pojawiają: Albo stawka dla tej liczby rat jest pusta, a nie zerowa, albo karta pochodzi z innego banku, albo przekroczono pułap trzech rat w edycji darmowej.
Po aktualizacji karty trafiają do niewłaściwego POS: Starsze wersje niosły ręcznie pisane zakresy BIN, które były częściowo błędne. Należy sprawdzić, czy każdy POS jest przypisany do banku, w którym naprawdę działa.
Ekran administracyjny wygląda na pozbawiony stylów albo poprawka się nie pojawia: Nieaktualna pamięć podręczna przeglądarki. Należy przeładować stronę z pominięciem bufora.

Ograniczenia

Poniższa lista jest zamierzona. Nic z tego nie jest błędem.

Brak zwrotów i anulowań z poziomu WordPress. Wtyczka nie implementuje API zwrotów WooCommerce i żaden dostawca nie niesie wywołania zwrotu. Zwrot wykonuje się na ekranie własnego banku.
Wyłącznie lira turecka. Kod waluty jest zapisany na stałe u każdego dostawcy; nie ma ustawienia wielowalutowego.
Brak zapisanych kart, brak tokenizacji, brak subskrypcji i płatności cyklicznych.
Brak preautoryzacji. Każda transakcja jest bezpośrednią sprzedażą.
Brak kierowania opartego na regułach. Kierowanie odbywa się wyłącznie według banku wydającego kartę — nie według kwoty, marki karty ani kraju.
Formularz płatności napisano pod klasyczną stronę zamówienia WooCommerce. W pakiecie nie ma osobnego komponentu dla strony zamówienia opartej na blokach.
Rozwiązanie 3D Pay Hosting zostało odrzucone celowo. Strona hostowana zdejmuje zakres PCI, ale zabiera też numer BIN i tabelę rat — a cała wartość tej wtyczki tkwi w kierowaniu, które one umożliwiają.
Brak edytora BIN. Tabelą zarządzamy my i jest ona łączona z odświeżeniem na żywo; nie ma ekranu do ręcznej edycji.
Dwadzieścia sześć instytucji jest wypisanych, ale niezaimplementowanych. Zostają widoczne, aby widoczna była luka.
Każdy dostawca poza NestPay ma samodzielnie zadeklarowany status beta, dopóki nie zostanie zweryfikowany od początku do końca na działającym koncie sprzedawcy.
Karty znajdują się wewnątrz strony. Pozycje z paska bocznego otwierają ekran wtyczki MevvPos; karty przełącza się na samej stronie.

Czego nigdy się nie przechowuje, w żadnej postaci: numeru karty, daty ważności i kodu zabezpieczającego. Jedyne zachowywane dane karty to pierwsze sześć cyfr i bank, który one wskazują. Przechowywanie kodu zabezpieczającego jest zabronione w każdych okolicznościach, a nawet zamaskowany zdradza swoją długość.

Od jednego wirtualnego POS do karty kierowanej do banku, który ją wydał.