Ś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
- Zaloguj się do panel.dpay.pl.
- Przejdź do Punkty Płatności > Serwisy.
- Wybierz serwis, który chcesz przetestować.
- Włącz przełącznik Tryb testowy.
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)
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) scenariusz testowy jest wybierany po numerze karty (PAN) przekazanym w zaszyfrowanych danych karty (encryptedCardData) podczas wywołania płatności - wystarczy, że serwis ma włączony tryb testowy:
| Numer karty | Scenariusz | Opis |
|---|---|---|
4111111111111111 | Sukces | Visa - płatność zakończona sukcesem |
5555555555554444 | Sukces | Mastercard - płatność zakończona sukcesem |
4012888888881881 | Sukces z 3DS | Visa - kaskada FORM (challenge 3DS) → SUCCESS |
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 |
5346930000008110 | Oferta DCC | Mastercard zagraniczna - oferta przewalutowania (EUR→PLN, kurs 4.507968, marża 6%, karta z EOG, ważność 30 min). Po decyzji → SUCCESS |
5346930000008128 | DCC niedozwolone | Mastercard - karta nie kwalifikuje się do DCC. Transparentny SUCCESS od razu (frontend nie widzi oferty) |
5346930000008136 | DCC krótka ważność | Mastercard zagraniczna - oferta DCC w GBP (kurs 0.85123, marża 5.5%, karta spoza EOG) z validUntil = +60 sekund. Pozwala przetestować błąd DCC_OFFER_EXPIRED |
5346930000008144 | DCC + 3DS po decyzji | Mastercard zagraniczna - oferta DCC w USD (kurs 1.05432, marża 5%, karta spoza EOG), kaskada DCC_OFFER → FORM (3DS) → SUCCESS |
W trybie produkcyjnym formularz 3D Secure prowadzi na stronę banku (ACS wydawcy karty). W trybie testowym dpay udostępnia własną stronę testową ACS z trzema przyciskami (Approve / Decline / Timeout), funkcjonalnie identyczną z prod. Z perspektywy integracji nic nie musisz zmieniać - bramka zwraca standardowy redirectType: "FORM" z auto-submit HTML.
Pełen opis flow Dynamic Currency Conversion (kontrakt API, wymagane elementy UI, błędy biznesowe) znajdziesz na stronie Dynamic Currency Conversion (DCC).
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 |
W trybie testowym działa też cały proces płatności cyklicznych BLIK - bez wniosku i bez połączenia z BLIK. Rejestracja używa powyższych kodów oraz kodu 777000 (bank bez płatności powtarzalnych), a wynik obciążenia zależy od kwoty (np. 60,73 zł to brak środków). Szczegóły: BLIK - płatności cykliczne, testowanie w trybie testowym.
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 |
Numer testowy podaj dokładnie tak jak w tabeli, z + na początku (spacje i myślniki są usuwane). Numer bez +, np. 351900000400, zostanie odrzucony błędem Phone number is required for MB Way Direct transactions., a poprawny numer spoza tabeli (np. +351912345678) symulator potraktuje jak nieznany i zasymuluje sukces. Scenariusze odmowy, timeoutu, nieznanego numeru i błędu systemu zwracają wynik od razu w odpowiedzi na rejestrację - szczegóły na stronie MB WAY.
Multibanco
Dla Multibanco nie ma numerów testowych: po rejestracji transakcja czeka na zapłatę, a wynik wywołujesz sam - endpointem symulacji albo przyciskami na bramce. Ogólne zasady z ramki „Jak działają numery testowe?” poniżej nie dotyczą Multibanco.
curl -X POST https://api-payments.dpay.pl/api/v1_0/payments/transaction/{transactionId}/multibanco/simulate \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"action": "pay"}'
Akcja (action) | Scenariusz | Opis |
|---|---|---|
pay | Sukces | Referencja opłacona - IPN i webhook payment.succeeded |
expire | Wygaśnięcie | Referencja wygasła - webhook payment.failed z kodem expired, bez IPN |
Endpoint jest idempotentny: ponowne wywołanie dla opłaconej albo wygasłej referencji zwraca changed: false i bieżący stan. Te same akcje są dostępne jako przyciski na bramce, na którą prowadzi adres z pola msg - bramka pokazuje je razem z banerem trybu testowego. Bez symulacji referencja wygasa sama po upływie terminu ważności (72 godziny). Pełny opis: Multibanco - testowanie.
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 |
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.
- Dla scenariuszy sukces - transakcja natychmiast otrzymuje status
processing, a po kilku sekundach automatycznie zmienia się napaid. 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.
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
- Zarejestruj transakcję przez API z prawidłowymi danymi (lub użyj testowego numeru sukcesu).
- Klient zostaje przekierowany na bramkę płatności (lub w przypadku whitelabel - odpowiedź z API potwierdza rejestrację).
- Po zatwierdzeniu płatności - IPN trafia na Twój endpoint ze statusem
paid. - Klient jest przekierowany na
url_success.
Płatność anulowana
- Zarejestruj transakcję przez API (lub użyj testowego numeru odmowy/timeout).
- Na bramce klient wybiera opcję anulowania.
- Klient jest przekierowany na
url_fail.
IPN niedostępny (retry)
- Wyłącz tymczasowo swój endpoint IPN (np. zatrzymaj serwer).
- Zarejestruj i opłać transakcję testową.
- dpay.pl będzie ponawiać dostarczenie IPN (do 10 prób z exponential backoff).
- Uruchom serwer ponownie - IPN zostanie dostarczony przy następnej próbie.
- Sprawdź w panelu historię dostarczeń IPN dla danej transakcji.
Testowanie zwrotów
- Wykonaj udaną transakcję testową (np. BLIK z kodem
777200). - Wywołaj endpoint zwrotu z
transaction_idopłaconej transakcji. - 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 | Przy rejestracji odpowiedź 400 z komunikatem Invalid checksum |
| IPN | Weryfikacja signature, idempotentność, odpowiedź 200 OK |
| Zwrot | Status success w odpowiedzi, aktualizacja refunded_amount |
Endpoint zwrotów przy błędnym checksum odpowiada kodem 401 z komunikatem Unauthorized request (a nie 400). Uwzględnij to w obsłudze błędów.
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), odpowiada200 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ę.