FAQ
Ogólne
Czym jest dpay.pl?
dpay.pl to bramka płatnicza umożliwiająca przyjmowanie płatności online. Obsługuje wiele metod płatności, w tym BLIK, przelewy bankowe, karty płatnicze, Google Pay, Apple Pay, SMS Premium i Direct Carrier Billing.
Jak założyć konto?
Przejdź na stronę panel.dpay.pl i kliknij Zarejestruj się. Po wypełnieniu formularza otrzymasz e-mail z linkiem aktywacyjnym. Szczegółowy opis procesu znajdziesz w Rejestracja.
Ile trwa weryfikacja konta?
Proces weryfikacji (KYC) trwa zwykle 1-2 dni robocze. W tym czasie nasz zespół weryfikuje przesłane dokumenty.
Czy dpay.pl oferuje środowisko testowe (sandbox)?
Tak. Po rejestracji możesz przetestować integrację bez obciążania prawdziwych kont. Skontaktuj się z obsługą techniczną przez panel, aby uzyskać dane testowe.
Integracja techniczna
Jaki jest bazowy URL API?
Rejestracja transakcji i operacje BLIK:
https://api-payments.dpay.pl/api/v1_0/payments/
Operacje na transakcjach (zwroty, szczegóły, wypłaty, lista banków):
https://panel.dpay.pl/api/v1/
Dla Direct Carrier Billing:
https://secure.dpay.pl/dcb/
Co to jest Secret Hash i gdzie go znajdę?
Secret Hash to prywatny klucz używany do generowania sum kontrolnych (checksum). Znajdziesz go w panelu: przejdź do Punkty Płatności > Serwisy, kliknij wybrany serwis i zjedź na dół strony.
Nigdy nie udostępniaj Secret Hash publicznie. Nie umieszczaj go w kodzie frontendowym ani w repozytorium kodu.
Otrzymuję błąd "Invalid checksum". Co robić?
Najczęstsze przyczyny:
- Zła kolejność pól - sprawdź, czy pola są w prawidłowej kolejności (patrz Generowanie checksum)
- Zły Secret Hash - upewnij się, że używasz aktualnego klucza z panelu
- Dodatkowe białoznaki - sprawdź, czy wartości nie zawierają spacji ani znaków nowej linii
- Zły separator - wszędzie użyj separatora
|(pipe)
Jak testować IPN lokalnie?
Użyj narzędzia do tunelowania, np. ngrok:
ngrok http 3000
Wygenerowany adres (np. https://abc123.ngrok.io/api/ipn) użyj jako url_ipn w zapytaniach testowych.
Gdzie podaję adresy URL (success, fail, IPN)?
Pola url_success i url_fail podajesz w każdym żądaniu rejestracji transakcji - są wymagane. url_ipn jest opcjonalny: bez niego dpay.pl nie wysyła IPN o tej płatności. Adresów URL nie konfiguruje się w panelu, obowiązują wyłącznie wartości przekazane per transakcja.
W jakim formacie podawać kwotę?
Dla większości metod płatności użyj formatu z kropką dziesiętną jako string: "29.99".
Wyjątkiem jest DCB (Direct Carrier Billing), gdzie kwotę podaje się w groszach: "1023" oznacza 10.23 PLN.
Płatności
Jakie metody płatności obsługuje dpay.pl?
- BLIK (kod jednorazowy)
- BLIK BNPL (płatność odroczona)
- Przelewy bankowe (Pay-by-Link)
- Karty płatnicze (Visa, Mastercard) - przez bramkę lub S2S
- Google Pay
- Apple Pay
- MB WAY (Portugalia)
- Bizum (Hiszpania)
- Banki czeskie i słowackie (white-label)
- SMS Premium
- Direct Carrier Billing (DCB)
Jak działa BLIK Level 0?
BLIK Level 0 pozwala klientowi wpisać 6-cyfrowy kod BLIK bezpośrednio na Twojej stronie, bez przekierowania do bramki. Wymaga to dodatkowych pól w zapytaniu: blik_code, user_ip, user_agent. Szczegóły: BLIK Level 0.
BLIK Płacę Później jest włączony w serwisie, ale nie wyświetla się na bramce. Dlaczego?
Najczęstsza przyczyna to kwota transakcji. BLIK Płacę Później jest oferowany wyłącznie dla kwot od 30 PLN do 2 000 PLN - poza tym przedziałem kafelek metody nie pojawia się na liście. Metoda wymaga też aktywnego klasycznego BLIK w serwisie i waluty PLN. Podobne progi obowiązują dla Twisto (30 dni do 2 000 PLN, raty 3x od 150 do 4 000 PLN). Szczegóły: Limity i ograniczenia.
Płatność BLIK została odrzucona. Jak rozpoznać przyczynę?
W odpowiedzi odrzuconej płatności pole additionalInfo.error zawiera surowy kod odmowy systemu BLIK przekazywany 1:1 (lista otwarta, np. USER_DECLINED, TIMEOUT, INSUFFICIENT_FUNDS). Pamiętaj, że kod BLIK jest ważny przez ok. 2 minuty - jeśli wygasł, poproś klienta o wygenerowanie nowego kodu w aplikacji bankowej. Szczegóły: Kody błędów.
Czy mogę wykonać zwrot częściowy?
Tak. dpay.pl obsługuje zwroty częściowe. Dla BLIK, kart płatniczych (Visa/Mastercard), MB WAY i przelewów Pay-by-Link możesz wykonać wiele zwrotów częściowych do jednej transakcji, dopóki suma zwrotów nie przekroczy kwoty pierwotnej. Dla PayPo i Twisto możliwy jest jeden zwrot (pełny lub częściowy). Szczegóły: Zwroty.
Jak długo mogę wykonać zwrot?
Limit 180 dni od daty zapłaty dotyczy zwrotów płatności kartami, MB WAY, PayPo i Twisto (dla BLIK 13 miesięcy). Zwroty przelewów bankowych (pay-by-link) nie mają limitu czasowego.
Jakie waluty są obsługiwane?
Waluty dostępne w API rejestracji transakcji:
| Waluta | Metody płatności |
|---|---|
| PLN | BLIK, PBL, karty, Google Pay, Apple Pay, SMS Premium, DCB |
| EUR | MB WAY, Bizum, banki słowackie |
| CZK | Banki czeskie |
Posiadacz karty zagranicznej może zapłacić w walucie własnej karty dzięki Dynamic Currency Conversion (DCC) - transakcję rejestrujesz wtedy normalnie w PLN, a przewalutowanie proponowane jest podczas płatności.
IPN (Instant Payment Notification)
Czym jest IPN?
IPN to automatyczne powiadomienie HTTP POST wysyłane przez dpay.pl na Twój serwer po zmianie statusu transakcji. Jest to jedyne wiarygodne źródło informacji o statusie płatności.
Jaką odpowiedź powinien zwracać mój endpoint IPN?
Twój endpoint musi odpowiedzieć kodem HTTP 200 i treścią "OK". Jeśli odpowie innym kodem, dpay.pl ponowi próbę dostarczenia.
Ile razy dpay.pl ponowi IPN?
dpay.pl ponawia próby dostarczenia do 10 razy z rosnącymi opóźnieniami (exponential backoff - 2, 4, 8, 16, 32, 64, 128, 256, 512 minut). Po 10 próbach powiadomienie nie będzie już ponawiane.
Czy mogę ręcznie sprawdzić status transakcji?
Tak, w panelu panel.dpay.pl w sekcji Transakcje możesz sprawdzić status każdej transakcji.
Dlaczego IPN przychodzi z tymi samymi danymi wielokrotnie?
Może to być spowodowane:
- Twój serwer nie odpowiedział kodem 200
- Timeout połączenia
- Błąd po stronie serwera
Upewnij się, że Twój endpoint odpowiada szybko (w ciągu kilku sekund) i że jest idempotentny (potrafi obsłużyć wielokrotne powiadomienia o tej samej transakcji).
Bezpieczeństwo
Czy mój serwer musi obsługiwać HTTPS?
Tak. Wszystkie adresy URL (success, fail, IPN) muszą używać protokołu HTTPS. dpay.pl nie wyśle powiadomień na adresy HTTP.
Jak weryfikować podpis IPN?
Wygeneruj SHA-256 z połączenia pól IPN i Twojego Secret Hash, a następnie porównaj wynik z polem signature. Szczegóły: Obsługa IPN.
Czy mogę przechowywać dane kart na swoim serwerze?
Nie. Nigdy nie przechowuj surowych danych kart (numerów, CVV, dat ważności). Dane karty powinny być szyfrowane RSA w przeglądarce klienta i przekazywane do dpay.pl w postaci zaszyfrowanej.
Co to jest 3D Secure?
3D Secure to dodatkowa warstwa autoryzacji płatności kartowych. Bank klienta może wymagać dodatkowego potwierdzenia (np. kodem SMS). dpay.pl obsługuje 3DS automatycznie - jeśli bank tego wymaga, API zwróci dane do przekierowania.
Panel administracyjny
Jak sprawdzić historię transakcji?
Zaloguj się do panel.dpay.pl i przejdź do sekcji Transakcje. Możesz filtrować po dacie, statusie, kwocie i identyfikatorze transakcji.
Jak zmienić adresy URL (success, fail, IPN)?
Adresów URL nie ustawia się w panelu. Pola url_success, url_fail i (opcjonalnie) url_ipn przekazujesz w każdym żądaniu rejestracji transakcji - wystarczy zmienić wartości wysyłane przez Twoją aplikację.
Jak wygenerować nowy Secret Hash?
Przejdź do Punkty Płatności > Serwisy, kliknij wybrany serwis, zjedź na dół strony i użyj opcji ponownego wygenerowania klucza. Pamiętaj, że po zmianie Secret Hash musisz zaktualizować go również w konfiguracji Twojego serwera.
Po wygenerowaniu nowego Secret Hash stary klucz natychmiast przestaje działać. Zaplanuj zmianę, aby uniknąć przerw w działaniu płatności.
Kontakt
Jeśli nie znalazłeś odpowiedzi na swoje pytanie:
- Sprawdź szczegółową dokumentację w sekcjach Cykl płatności i Bezpieczeństwo
- Skontaktuj się z obsługą techniczną przez panel.dpay.pl