Cykl życia transakcji

Każda transakcja w dpay.pl przechodzi przez określone stany - od utworzenia do finalnego rozliczenia lub anulowania. Zrozumienie cyklu życia transakcji pozwala poprawnie obsługiwać płatności w Twojej aplikacji.

Statusy transakcji

Status	Opis	Czy finalny?
created	Transakcja zarejestrowana, klient nie dokonał jeszcze płatności	Nie
processing	Płatność w trakcie przetwarzania przez operatora	Nie
paid	Płatność zakończona sukcesem	Tak
canceled	Transakcja anulowana (timeout, odrzucenie, rezygnacja klienta)	Tak

Diagram stanów

created

processing

paid

canceled

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Opis przejść między stanami

created → processing

Klient wybrał metodę płatności i rozpoczął proces autoryzacji. Dla niektórych metod (np. BLIK, karty) przejście do processing następuje natychmiast po wysłaniu danych płatności.

processing → paid

Operator płatności (bank, BLIK, procesor kart) potwierdził autoryzację. Środki zostały pobrane z konta klienta. dpay.pl wysyła IPN z potwierdzeniem.

processing → canceled

Płatność nie powiodła się. Najczęstsze przyczyny:

• Klient anulował płatność
• Nieprawidłowy kod BLIK lub odrzucenie w aplikacji bankowej
• Niewystarczające środki
• Timeout (klient nie ukończył płatności w wymaganym czasie)
• Odrzucenie przez system antyfraudowy

created → canceled

Klient nie podjął żadnej akcji i transakcja wygasła (timeout).

Zachowanie per metoda płatności

Różne metody płatności mają różny przebieg cyklu życia:

Metoda	Przechodzi przez processing?	Typowy czas na płatność
BLIK	Tak	~2 minuty (ważność kodu)
Przelewy bankowe (PBL)	Tak	Do 15 minut
Karty płatnicze	Tak (autoryzacja + opcjonalnie 3DS)	Do 5 minut
Google Pay / Apple Pay	Tak	Sekundy
MB WAY	Tak (potwierdzenie w aplikacji)	Do 5 minut
Bizum	Tak (potwierdzenie w aplikacji)	Do 5 minut
DCB	Tak	Do 2 minut
SMS Premium	Nie dotyczy (inny model)	-

Jak sprawdzać status transakcji?

IPN (zalecane)

Najlepszym sposobem śledzenia statusu transakcji jest obsługa IPN. dpay.pl automatycznie wysyła powiadomienie HTTP POST na Twój endpoint, gdy transakcja przechodzi do stanu paid.

informacja

IPN jest wysyłany tylko dla udanych transakcji (status paid). Transakcje anulowane nie generują IPN.

Polling (odpytywanie API)

Jeśli IPN nie dotarł lub potrzebujesz dodatkowej weryfikacji, możesz samodzielnie sprawdzić status:

POST https://panel.dpay.pl/api/v1/pbl/details
Content-Type: application/json

{
  "service": "abc123",
  "transaction_id": "A75AEBB4-4B89-4834-AD43-EF442C133769",
  "checksum": "sha256(service|transaction_id|secret_hash)"
}

Szczegóły endpointu i przykłady kodu znajdziesz w sekcji Samodzielne odpytywanie o status.

wskazówka

Nie odpytuj API zbyt często. Zalecanym podejściem jest:

1. Główny mechanizm - IPN (automatycznie, natychmiast)
2. Fallback - zadanie cron sprawdzające statusy transakcji oczekujących >15 minut

Mapowanie statusów na IPN

Status transakcji	IPN wysłany?	Typ IPN
created	Nie	-
processing	Nie	-
paid	Tak	transfer
paid (capture karty)	Tak	capture
canceled	Nie	-

Obsługa stanów w aplikacji

Przykładowa logika obsługi statusów po stronie Twojego serwera:

// Mapowanie statusów dpay.pl na statusy zamówienia
switch ($transactionStatus) {
    case 'created':
        // Zamówienie oczekuje na płatność
        // Wyświetl klientowi informację "Oczekujemy na płatność"
        break;

    case 'processing':
        // Płatność w trakcie - nie zmieniaj statusu zamówienia
        // Klient widzi stronę oczekiwania
        break;

    case 'paid':
        // Płatność potwierdzona przez IPN
        // Zaktualizuj zamówienie, wyślij e-mail z potwierdzeniem
        markOrderAsPaid($orderId);
        break;

    case 'canceled':
        // Transakcja anulowana
        // Przywróć dostępność produktu, poinformuj klienta
        markOrderAsCanceled($orderId);
        break;
}

ostrzeżenie

Nie aktualizuj statusu zamówienia na paid na podstawie przekierowania klienta na url_success. Jedynymi wiarygodnymi źródłami informacji o udanej płatności są IPN i zapytanie do API dpay.