Środowisko testowe

dpay.pl udostępnia tryb testowy, który pozwala przetestować integrację bez obciążania prawdziwych kont. Transakcje testowe są widoczne w panelu administracyjnym, ale nie generują rzeczywistych przepływów pieniężnych.

Włączanie trybu testowego

1. Zaloguj się do panel.dpay.pl.
2. Przejdź do Punkty Płatności > Serwisy.
3. Wybierz serwis, który chcesz przetestować.
4. Włącz przełącznik Tryb testowy.

informacja

Tryb testowy jest dostępny od razu po utworzeniu serwisu - nie musisz czekać na weryfikację konta, aby rozpocząć integrację.

Co się dzieje w trybie testowym?

• Brak rzeczywistych obciążeń - żadne pieniądze nie są pobierane z kont klientów
• Transakcje widoczne w panelu - wszystkie testowe transakcje pojawiają się w historii transakcji z oznaczeniem testowym
• IPN działa normalnie - powiadomienia IPN są wysyłane na Twój endpoint tak samo jak w trybie produkcyjnym
• Pełne API - wszystkie endpointy działają identycznie jak na produkcji

Testowanie IPN lokalnie

Podczas developmentu Twój serwer zwykle działa na localhost, który nie jest dostępny z internetu. Aby dpay.pl mogło wysyłać powiadomienia IPN na Twój lokalny serwer, użyj narzędzia do tunelowania.

ngrok

ngrok tworzy tunel HTTPS do Twojego lokalnego serwera:

# Uruchom tunel (zakładając, że Twój serwer działa na porcie 3000)
ngrok http 3000

ngrok wygeneruje publiczny adres, np. https://abc123.ngrok-free.app. Użyj go jako url_ipn:

{
  "url_ipn": "https://abc123.ngrok-free.app/api/ipn"
}

Alternatywy

• Cloudflare Tunnel - darmowy tunel od Cloudflare
• localtunnel - proste narzędzie open-source (npx localtunnel --port 3000)

wskazówka

Pamiętaj, że adres tunelu zmienia się po każdym restarcie (w darmowej wersji ngrok). Aktualizuj url_ipn w zapytaniach testowych.

Numery testowe do symulacji płatności

W trybie testowym możesz użyć specjalnych numerów testowych, które symulują różne scenariusze płatności - bez kontaktu z zewnętrznymi dostawcami. System automatycznie rozpoznaje te numery i zwraca odpowiednie odpowiedzi.

Karty płatnicze

W integracji whitelabel (karty S2S) użyj pola test_card_number w zapytaniu rejestracji:

Numer karty	Scenariusz	Opis
4111111111111111	Sukces	Visa - płatność zakończona sukcesem
5555555555554444	Sukces	Mastercard - płatność zakończona sukcesem
4000000000000002	Odmowa	Visa - transakcja odrzucona przez wydawcę
4000000000000069	Karta wygasła	Visa - karta przeterminowana
4000000000000127	Brak środków	Visa - niewystarczające środki
4000000000000085	Timeout	Visa - timeout przetwarzania
5105105105105100	Odmowa	Mastercard - transakcja odrzucona

BLIK

Użyj specjalnych 6-cyfrowych kodów BLIK w polu blik_code:

Kod BLIK	Scenariusz	Opis
777200	Sukces	Płatność zakończona sukcesem
777201	Sukces (opóźniony)	Sukces po dłuższym oczekiwaniu na potwierdzenie
777400	Odrzucone	Użytkownik odrzucił transakcję w aplikacji
777401	Timeout	Użytkownik nie potwierdził w wymaganym czasie
777402	Brak środków	Niewystarczające środki na koncie
777500	Błąd systemu	Symulacja błędu po stronie systemu

MB WAY

Użyj specjalnych numerów portugalskich w polu phone_number:

Numer telefonu	Scenariusz	Opis
+351900000001	Sukces	Płatność zakończona sukcesem
+351900000002	Sukces (opóźniony)	Sukces po dłuższym oczekiwaniu
+351900000400	Odrzucone	Użytkownik odrzucił w aplikacji MB WAY
+351900000401	Timeout	Brak potwierdzenia w wymaganym czasie
+351900000402	Numer niezarejestrowany	Numer telefonu nie jest powiązany z MB WAY
+351900000500	Błąd systemu	Symulacja błędu systemowego

Apple Pay i Google Pay

Apple Pay i Google Pay używają tokenów z portfela zamiast numerów kart. W trybie testowym zamiast prawdziwego tokena przekaż specjalną wartość testową w polu xPayToken:

Token	Scenariusz	Opis
TEST_SUCCESS	Sukces	Płatność zakończona sukcesem
TEST_SUCCESS_DELAYED	Sukces (opóźniony)	Sukces po dłuższym oczekiwaniu
TEST_DECLINE	Odmowa	Transakcja odrzucona
TEST_INSUFFICIENT	Brak środków	Niewystarczające środki
TEST_TIMEOUT	Timeout	Przekroczono czas oczekiwania
TEST_ERROR	Błąd systemu	Symulacja błędu systemowego

wskazówka

W trybie testowym nie musisz wywoływać prawdziwego Apple Pay / Google Pay sheet. Wystarczy wysłać zapytanie z testowym tokenem bezpośrednio do endpointu /pay/apple-pay lub /pay/google-pay.

Jak działają numery testowe?

• Dla scenariuszy sukces - transakcja natychmiast otrzymuje status processing, a po kilku sekundach automatycznie zmienia się na paid. IPN jest wysyłany na Twój endpoint.
• Dla scenariuszy błąd - API zwraca odpowiedź z kodem błędu, transakcja jest anulowana.
• Jeśli użyjesz numeru spoza listy testowej - system domyślnie symuluje płatność zakończoną sukcesem.

wskazówka

Numery testowe działają wyłącznie gdy serwis ma włączony Tryb testowy. Na produkcji są traktowane jak zwykłe dane płatności.

Testowanie scenariuszy

Płatność zakończona sukcesem

1. Zarejestruj transakcję przez API z prawidłowymi danymi (lub użyj testowego numeru sukcesu).
2. Klient zostaje przekierowany na bramkę płatności (lub w przypadku whitelabel - odpowiedź z API potwierdza rejestrację).
3. Po zatwierdzeniu płatności - IPN trafia na Twój endpoint ze statusem paid.
4. Klient jest przekierowany na url_success.

Płatność anulowana

1. Zarejestruj transakcję przez API (lub użyj testowego numeru odmowy/timeout).
2. Na bramce klient wybiera opcję anulowania.
3. Klient jest przekierowany na url_fail.

IPN niedostępny (retry)

1. Wyłącz tymczasowo swój endpoint IPN (np. zatrzymaj serwer).
2. Zarejestruj i opłać transakcję testową.
3. dpay.pl będzie ponawiać dostarczenie IPN (do 10 prób z exponential backoff).
4. Uruchom serwer ponownie - IPN zostanie dostarczony przy następnej próbie.
5. Sprawdź w panelu historię dostarczeń IPN dla danej transakcji.

Testowanie zwrotów

1. Wykonaj udaną transakcję testową (np. BLIK z kodem 777200).
2. Wywołaj endpoint zwrotu z transaction_id opłaconej transakcji.
3. Sprawdź odpowiedź API i status transakcji w panelu.

Weryfikacja odpowiedzi API

W trybie testowym odpowiedzi API mają identyczny format jak na produkcji. Upewnij się, że Twoja aplikacja poprawnie obsługuje:

Scenariusz	Co sprawdzić
Sukces rejestracji	Pole error: false, obecność transactionId i URL w msg
Błąd checksum	Odpowiedź 400 z komunikatem Invalid checksum
IPN	Weryfikacja signature, idempotentność, odpowiedź 200 OK
Zwrot	Status success w odpowiedzi, aktualizacja refunded_amount

Checklist przed przejściem na produkcję

Przed wyłączeniem trybu testowego upewnij się, że:

• Checksum - generowany poprawnie dla wszystkich typów zapytań (rejestracja, zwrot)
• IPN - endpoint działa, weryfikuje podpis (signature), odpowiada 200 OK
• Idempotentność - IPN przetwarzany tylko raz per transakcja
• Weryfikacja kwoty - kwota z IPN porównywana z kwotą zamówienia w bazie
• Obsługa błędów - aplikacja poprawnie reaguje na błędy API (400, 401, 500)
• HTTPS - wszystkie adresy URL (url_success, url_fail, url_ipn) używają HTTPS
• Secret Hash - przechowywany bezpiecznie w zmiennych środowiskowych, nie w kodzie
• Zwroty - jeśli korzystasz ze zwrotów, przetestowane zwroty pełne i częściowe
• Logowanie - przychodzące IPN i odpowiedzi API są logowane do celów diagnostycznych

Po spełnieniu wszystkich punktów wyłącz tryb testowy w panelu - Twój serwis jest gotowy na produkcję.