OroCommerce
Oficjalny bundle płatności dpay.pl dla OroCommerce. Umożliwia przyjmowanie płatności online w sklepie B2B opartym na OroCommerce. Bundle integruje się z systemem płatności Oro i obsługuje zwroty online, automatyczne powiadomienia IPN oraz konfigurację feature toggles.
Wymagania
- OroCommerce 5.1 lub 6.0
- PHP 8.1 lub nowszy
- Aktywne konto w Panelu dpay.pl z utworzonym Punktem Płatności
Obsługiwane metody płatności
- BLIK (w tym BLIK Level 0 - inline)
- Przelewy bankowe (pay-by-link)
- Karty płatnicze (inline)
- Google Pay i Apple Pay
- PayPal
- Paysafecard
- Raty
Instalacja
Metoda 1 - Composer (zalecana)
- W katalogu głównym OroCommerce wykonaj:
composer require dpay/orocommerce-bundle - Wyczyść cache i zaktualizuj schemat bazy danych:
bin/console cache:clear
bin/console oro:platform:update --env=prod
Metoda 2 - ręczna instalacja
- Pobierz najnowszą wersję bundle ze strony dpay.pl lub z GitHuba.
- Rozpakuj archiwum do katalogu
src/DPay/OroCommerceBundle/. - Zarejestruj bundle w konfiguracji aplikacji.
- Wyczyść cache i uruchom migracje:
bin/console cache:clear
bin/console oro:platform:update --env=prod
Konfiguracja
Krok 1 - Przygotowanie danych w Panelu dpay.pl
- Zaloguj się do Panelu dpay.pl.
- Przejdź do sekcji Punkty Płatności.
- Utwórz nowy Punkt Płatności lub wybierz istniejący.
- Zanotuj:
- Nazwa serwisu (
service_name) - unikalna nazwa Twojego Punktu Płatności - Tajny hash (
secret_hash) - klucz używany do podpisywania żądań
- Nazwa serwisu (
- W ustawieniach Punktu Płatności ustaw adres IPN - OroCommerce wykorzystuje standardowy mechanizm callback Oro Payment Bundle. Adres IPN jest generowany automatycznie dla każdej transakcji.
Ważne
Tajny hash powinien być traktowany jak hasło. Nigdy nie udostępniaj go publicznie ani nie umieszczaj w kodzie frontendowym.
Krok 2 - Konfiguracja bundle w OroCommerce
- Przejdź do System > Integrations > Manage Integrations w panelu administracyjnym.
- Kliknij Create Integration i wybierz typ dPay.
- Wypełnij formularz konfiguracyjny:
| Pole | Opis |
|---|---|
| Name | Nazwa integracji (widoczna w panelu administracyjnym) |
| Label | Etykieta metody płatności widoczna dla klienta |
| Short Label | Skrócona etykieta wyświetlana na liście płatności |
| Service Name | Nazwa serwisu z Panelu dpay.pl |
| Hash Key | Tajny hash z Panelu dpay.pl |
| Enable PayPal | Włącz płatności PayPal |
| Enable Credit Card | Włącz płatności kartą kredytową |
| Enable Paysafecard | Włącz płatności Paysafecard |
| Enable Installments | Włącz płatności ratalne |
| Disable Bank Transfers | Wyłącz przelewy bankowe i pay-by-link |
| BLIK Zero | Włącz wpisywanie kodu BLIK bezpośrednio w checkoucie |
| Apple Pay | Włącz płatności Apple Pay |
| Google Pay | Włącz płatności Google Pay |
| Inline Card Form | Włącz formularz karty inline w checkoucie |
- Kliknij Save and Close.
- Przejdź do System > Payment Rules i utwórz regułę płatności przypisaną do metody dpay.pl. Upewnij się, że reguła jest ograniczona do waluty PLN.
Krok 3 - Weryfikacja
- Złóż testowe zamówienie w sklepie.
- Wybierz dPay.pl jako metodę płatności na etapie checkout.
- Sprawdź, czy następuje poprawne przekierowanie na stronę płatności dpay.pl.
- Po dokonaniu płatności sprawdź, czy transakcja w OroCommerce została oznaczona jako zakończona sukcesem.
Zwroty
Bundle obsługuje zwroty online:
- Przejdź do zamówienia w Sales > Orders.
- Otwórz szczegóły transakcji płatniczej.
- Wykonaj operację zwrotu (pełnego lub częściowego).
- System automatycznie wyśle żądanie zwrotu do dpay.pl.
Jeśli kwota zwrotu jest mniejsza niż kwota transakcji, zostanie wykonany zwrot częściowy. W przeciwnym razie wykonywany jest zwrot pełny.
Mapowanie statusów
| Status dpay.pl | Status transakcji OroCommerce |
|---|---|
new | Pending |
completed | Successful |
rejected | Failed |
Rozwiązywanie problemów
Metoda płatności nie pojawia się w checkoucie
- Sprawdź, czy integracja dpay.pl jest aktywna w System > Integrations.
- Upewnij się, że reguła płatności jest poprawnie skonfigurowana w System > Payment Rules.
- Sprawdź, czy waluta zamówienia to PLN - bundle obsługuje wyłącznie tę walutę i kwoty większe od 0.
Błąd podczas rejestracji płatności
- Sprawdź logi aplikacji w katalogu
var/logs/- szukaj wpisów z przedrostkiem[dPay]. - Upewnij się, że Service Name i Hash Key są prawidłowe.
- Sprawdź, czy serwer ma dostęp do API dpay.pl (brak blokady firewall na połączenia wychodzące).
Zwrot nie został przetworzony
- Sprawdź, czy transakcja źródłowa ma przypisany numer referencyjny (Transaction ID z dpay.pl).
- Sprawdź logi pod kątem komunikatów
[dPay] Refund failedlub[dPay] Refund error.
Problemy z aktualizacją bundle
- Po aktualizacji wykonaj:
bin/console cache:clear && bin/console oro:platform:update --env=prod. - Upewnij się, że wersja OroCommerce jest kompatybilna (5.1 lub 6.0).