DocsosCommerce
Integracja Cost+ ze sklepem osCommerce 4 za pomocą oficjalnego modułu płatności
Zintegruj Cost+ jako metodę płatności w swoim sklepie osCommerce 4. Oficjalny moduł NoPayn Payments korzysta z hostowanej strony płatności, więc żadne dane karty nie trafiają na Twój serwer — w pełni zgodny z PCI DSS.
Wymagania wstępne
- Aktywne konto sprzedawcy Cost+
- osCommerce 4.x
- PHP 8.1 lub nowszy
- Włączone rozszerzenie cURL
- Certyfikat SSL (wymagany HTTPS)
- Dostęp administratora do panelu osCommerce
Obsługiwane metody płatności
| Etykieta w kasie | Identyfikator NoPayn |
|---|---|
| Credit / Debit Card | credit-card |
| Apple Pay | apple-pay |
| Google Pay | google-pay |
| Vipps MobilePay | vipps-mobilepay |
Każda metoda może być indywidualnie włączona lub wyłączona z panelu administracyjnego.
1. Zainstaluj moduł
Pobierz lub sklonuj moduł z GitHub.
Skopiuj katalog lib/ do katalogu głównego osCommerce 4:
cp -r lib/ /path/to/oscommerce/Umieszcza to pliki modułu w:
lib/common/modules/orderPayment/nopayn.php
lib/common/modules/orderPayment/nopayn/NoPaynApiClient.php
lib/common/modules/orderPayment/nopayn/NoPaynLogger.php
lib/common/modules/orderPayment/nopayn/NoPaynWebhookHandler.phpW panelu administracyjnym osCommerce:
- Przejdź do Modules → Payment → Online
- Włącz filtry „Show inactive" i „Show not installed", jeśli potrzeba
- Znajdź NoPayn Payments i kliknij Install
2. Skonfiguruj moduł
Zaloguj się do portalu sprzedawcy i przejdź do sekcji Strony, następnie kliknij na stronę, którą chcesz połączyć. Kliknij Integracja, aby znaleźć swój klucz API.
Wprowadź klucz API i skonfiguruj następujące ustawienia:
| Ustawienie | Opis | Domyślnie |
|---|---|---|
| Enable NoPayn Payments | Główny przełącznik włącz/wyłącz | True |
| API Key | Twój klucz API NoPayn | — |
| Enable Credit / Debit Card | Pokaż kartę kredytową/debetową w kasie | True |
| Enable Apple Pay | Pokaż Apple Pay w kasie | True |
| Enable Google Pay | Pokaż Google Pay w kasie | True |
| Enable Vipps MobilePay | Pokaż Vipps MobilePay w kasie | True |
| Manual Capture (Credit Card) | Tylko autoryzacja — przechwycenie przy realizacji zamówienia | False |
| Debug Logging | Zapisuj żądania/odpowiedzi API do dziennika | False |
| Completed Order Status | Status ustawiany po pomyślnej płatności | Processing |
| Pending Order Status | Status ustawiany podczas oczekiwania na płatność | Pending |
| Cancelled Order Status | Status ustawiany przy anulowaniu/błędzie/wygaśnięciu | Cancelled |
| Payment Zone | Ogranicz do strefy geograficznej (opcjonalnie) | Wszystkie strefy |
| Sort Order | Kolejność wyświetlania na stronie kasy | 0 |
Aktywuj tylko te metody płatności, na które uzyskałeś zgodę i potwierdzenie.
3. Zaktualizuj etykiety kasy (zalecane)
Domyślne etykiety przycisków kasy osCommerce zakładają jednoetapowy przepływ. Dla lepszego doświadczenia z przekierowaniem na zewnętrzną stronę płatności zaktualizuj te tłumaczenia w Admin → Localisation → Languages → English → Define:
| Klucz | Domyślnie | Zalecane |
|---|---|---|
TEXT_PAY_WITH_CARD | Pay with card | Przejdź do płatności |
TEXT_CONFIRM_AND_PAY | Confirm and pay | Przejrzyj zamówienie |
CONFIRM_ORDER | Confirm order | Potwierdź i zapłać |
Poprawia to doświadczenie klienta, czyniąc przepływ kasy bardziej zrozumiałym — klienci rozumieją, że zostaną przekierowani na bezpieczną stronę płatności.
4. Przepływ płatności
Po skonfigurowaniu przepływ płatności działa następująco:
- Klient wybiera metodę płatności Cost+ w kasie
- Klient potwierdza zamówienie
- Moduł tworzy oczekujące zamówienie i wywołuje API Cost+
- Klient jest przekierowywany na hostowaną stronę płatności Cost+ (HPP)
- Klient realizuje płatność na bezpiecznej HPP
- Klient jest przekierowywany z powrotem do sklepu
- Moduł weryfikuje status płatności przez API Cost+
- Status zamówienia jest odpowiednio aktualizowany
Linki płatności wygasają po 5 minutach. Jeśli klient nie dokończy płatności w tym oknie, zamówienie jest automatycznie oznaczane jako anulowane.
5. Webhooki
Moduł rejestruje URL webhooka w Cost+ dla aktualizacji statusu serwer-serwer. Gdy status płatności się zmieni, Cost+ wysyła powiadomienie, a moduł:
- Odbiera webhook POST
- Weryfikuje status płatności przez API (nigdy nie ufa treści webhooka)
- Aktualizuje status zamówienia w osCommerce
Ręczna konfiguracja webhooka nie jest wymagana — moduł obsługuje rejestrację automatycznie.
Ręczne przechwycenie
Gdy włączone dla płatności kartą:
- Płatność jest autoryzowana, ale nie przechwycona w kasie
- Środki są pobierane, gdy zamówienie przechodzi do statusu completed
- Jeśli zamówienie zostanie anulowane, autoryzacja jest automatycznie anulowana
Użyj ręcznego przechwycenia, jeśli chcesz obciążać klientów dopiero po wysyłce zamówienia. Jest to przydatne dla sprzedawców z dłuższym czasem realizacji.
Logowanie debugowania
Gdy Debug Logging jest włączone, moduł zapisuje do pliku nopayn_debug.log w katalogu logów osCommerce. Wpisy dziennika obejmują:
- Wszystkie żądania i odpowiedzi API
- Zdarzenia webhooków i wyniki przetwarzania
- Operacje przechwycenia i anulowania
- Błędy (zawsze logowane, niezależnie od ustawienia debugowania)
Wszystkie wpisy mają prefiks NoPayn_ dla łatwego filtrowania.
Odinstalowanie
- Przejdź do Modules → Payment → Online w panelu administracyjnym
- Wybierz NoPayn Payments
- Kliknij Remove
Odinstalowanie modułu usuwa konfigurację i tabele nopayn_transactions i nopayn_refunds z bazy danych. Upewnij się, że wyeksportujesz wszystkie potrzebne dane przed odinstalowaniem.
Przetestuj i uruchom
Złóż kilka testowych zamówień, aby upewnić się, że wszystko działa poprawnie. Zalecamy testowanie zarówno udanych, jak i nieudanych płatności, aby potwierdzić prawidłową obsługę wszystkich scenariuszy.
Wsparcie
Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.