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.

POST/api/v1/pbl/details→Sprawdź status transakcji: parametry, checksum i pola odpowiedzi.Pełny kontrakt w API Reference

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 (dla kart pre-auth: środki zautoryzowane)	Tak*
captured	Płatność kartowa pre-auth przechwycona (capture) - środki pobrane	Tak
expired	Transakcja wygasła lub nie doszła do skutku (timeout, odrzucenie, rezygnacja klienta)	Tak

* Dla płatności kartowych w modelu pre-auth/capture transakcja paid (autoryzacja) może jeszcze przejść w captured po przechwyceniu środków. Dla pozostałych metod paid jest finalny.

Diagram stanów

created

processing

paid

captured

expired

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.

informacja

Stan oznaczony na diagramie jako „canceled" jest zwracany przez API o statusie transakcji jako expired. Dodatkowo płatności kartowe pre-auth mogą po paid przejść w finalny stan captured.

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 → expired

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 → expired

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

paid → captured (tylko karty pre-auth)

Dotyczy wyłącznie płatności kartowych w modelu pre-auth/capture. Po autoryzacji (paid) przechwytujesz środki (capture) - transakcja przechodzi w finalny stan captured.

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
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, a dla kart pre-auth dodatkowo captured). Transakcje wygasłe i nieudane 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
captured (capture karty pre-auth)	Tak	capture
expired	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 'captured':
        // Płatność kartowa pre-auth przechwycona - środki pobrane
        markOrderAsPaid($orderId);
        break;

    case 'expired':
        // Transakcja wygasła / nie doszła do skutku
        // 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.