Sylius
Oficjalny plugin dpay.pl dla platformy Sylius. Umożliwia przyjmowanie płatności online w sklepie internetowym opartym na Sylius z wykorzystaniem biblioteki Payum. Obsługuje pełny cykl płatności - od rejestracji transakcji, przez powiadomienia IPN, po zwroty.
Wymagania
- Sylius 1.12 lub 2.0+
- PHP 8.1 lub nowszy
- Payum Core 1.7+
- Composer
- 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 (BLIK BNPL)
Instalacja
Zainstaluj plugin za pomocą Composera:
composer require dpay/sylius-plugin
Następnie zarejestruj bundle w pliku config/bundles.php:
return [
// ...
DPay\SyliusPlugin\DPaySyliusPlugin::class => ['all' => true],
];
Zaimportuj konfigurację serwisów. Utwórz plik config/packages/dpay_sylius_plugin.yaml:
imports:
- { resource: "@DPaySyliusPlugin/config/services.xml" }
Wyczyść cache:
bin/console cache:clear
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 (
- Adres IPN zostanie ustawiony automatycznie przez Payum (token notify).
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 bramki płatności w Sylius
- Przejdź do panelu administracyjnego Sylius.
- Otwórz Configuration > Payment methods.
- Kliknij Create i wybierz gateway dPay.pl.
- Wypełnij formularz konfiguracyjny:
| Pole | Opis |
|---|---|
| Service Name | Nazwa serwisu z Panelu dpay.pl |
| Hash Key | Tajny hash z Panelu dpay.pl |
| PayPal | Włącz/wyłącz płatności PayPal |
| Credit Card | Włącz/wyłącz płatności kartą |
| Paysafecard | Włącz/wyłącz płatności Paysafecard |
| Installment | Włącz/wyłącz płatności ratalne |
| No Banks | Ukryj listę banków |
| BLIK Zero | Włącz płatności BLIK Level 0 (inline) |
| Apple Pay | Włącz płatności Apple Pay |
| Google Pay | Włącz płatności Google Pay |
| Card Inline | Włącz formularz karty inline |
- Zapisz konfigurację.
Krok 3 - Weryfikacja
- Złóż testowe zamówienie w sklepie.
- Wybierz dPay.pl jako metodę płatności.
- Sprawdź, czy następuje poprawne przekierowanie na stronę płatności.
- Po dokonaniu płatności sprawdź, czy status zamówienia w Sylius zmienił się na Opłacone.
Zwroty
Plugin obsługuje zwroty online za pośrednictwem mechanizmu Payum Refund. Zwroty mogą być:
- Pełne - zwrot całej kwoty transakcji
- Częściowe - zwrot wybranej kwoty (ustawianej przez pole
dpay_refund_amount)
Zwrot zostanie automatycznie przesłany do API dpay.pl.
Mapowanie statusów
| Status dpay.pl | Status Sylius (Payum) |
|---|---|
pending | Pending |
pending_inline | Pending (BLIK inline) |
completed | Captured (Opłacone) |
failed | Failed |
refunded | Refunded |
Rozwiązywanie problemów
Zamówienia nie zmieniają statusu automatycznie
- Sprawdź, czy token notify Payum jest poprawnie generowany.
- Upewnij się, że serwer dpay.pl ma dostęp do adresu IPN (nie jest blokowany przez firewall).
- Sprawdź logi Symfony:
var/log/dev.loglubvar/log/prod.log.
Błąd "Only PLN currency is supported"
- Plugin obsługuje wyłącznie walutę PLN. Upewnij się, że kanał sprzedaży (channel) w Sylius ma ustawioną walutę PLN.
Błąd "Invalid IPN payload"
- Upewnij się, że Hash Key w konfiguracji bramki jest identyczny z hashem w Panelu dpay.pl.
- Sprawdź, czy nie ma dodatkowych spacji przed lub po wartości klucza.
Plugin nie pojawia się jako opcja gateway
- Sprawdź, czy bundle jest poprawnie zarejestrowany w
config/bundles.php. - Wyczyść cache:
bin/console cache:clear.