Karty - pre-autoryzacja i przechwycenie (capture)

Pre-autoryzacja pozwala zablokować środki na karcie klienta bez natychmiastowego obciążenia, a następnie przechwycić (capture) je w wybranym momencie - w całości lub częściowo. Niewykorzystaną blokadę można anulować (cancellation). To standardowy model dla scenariuszy, gdzie kwota końcowa lub moment obciążenia nie są znane w chwili zakupu.

POST/api/v1_0/cards/payment/{transactionId}/pay/card-pre-authZablokuj środki na karcie bez obciążenia (z 3D Secure).Pełny kontrakt w API Reference POST/api/v1_0/cards/payment/{transactionId}/capturePrzechwyć zablokowane środki - w całości lub częściowo.Pełny kontrakt w API Reference POST/api/v1_0/cards/payment/{transactionId}/cancellationZwolnij niewykorzystaną blokadę środków.Pełny kontrakt w API Reference

Kiedy używać

Rezerwacje (hotele, wynajem) - blokada kaucji, obciążenie po pobycie
Wysyłka po skompletowaniu - obciążenie dopiero przy wysyłce towaru
Kwota zmienna - autoryzacja z zapasem, capture rzeczywistej kwoty
Marketplace - autoryzacja teraz, rozliczenie po potwierdzeniu przez sprzedawcę

Pre-autoryzacja na zapisanej karcie (card-on-file)

Pre-autoryzację można wykonać także na zapisanym tokenie (card-on-file) - przez pole authorize_only na aliasie mandatu cyklicznego; patrz Karty - płatności cykliczne. Ta strona opisuje pre-autoryzację świeżej karty. Krok przechwycenia (capture) i anulowania jest wspólny dla obu.

Jak działa?

Proces składa się z dwóch faz:

Pre-autoryzacja - blokada środków na karcie (bez obciążenia). Klient przechodzi 3D Secure tak jak przy zwykłej płatności.
Przechwycenie (capture) LUB anulowanie (cancellation) - pobranie zablokowanych środków (pełne/częściowe) albo zwolnienie blokady.

Bazuje na integracji Server-to-Server

Pre-autoryzacja korzysta z tego samego mechanizmu szyfrowania danych karty i obsługi 3D Secure co płatności kartowe Server-to-Server. Zapoznaj się z nią najpierw - poniżej opisujemy tylko różnice.

Wymagania

Aktywna integracja kartowa Server-to-Server (wymaga certyfikacji PCI DSS i zgody dpay - patrz Karty S2S)
Pre-autoryzacja włączona na Punkcie Płatności (skontaktuj się z dpay)

Krok 1. Rejestracja i pre-autoryzacja

Zarejestruj transakcję (transactionType: card_auth), pobierz klucz publiczny i zaszyfruj dane karty dokładnie tak jak w Karty S2S (kroki 1-3). Różnica jest tylko w endpointie płatności - zamiast /pay/card-otp użyj /pay/card-pre-auth:

POST https://api-payments.dpay.pl/api/v1_0/cards/payment/{transactionId}/pay/card-pre-auth
Content-Type: application/json

Parametry zapytania

Identyczne jak dla /pay/card-otp:

{
  "encryptedCardData": "Base64-encoded-encrypted-data...",
  "deviceInfo": {
    "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "browserJavaEnabled": "false",
    "browserLanguage": "pl-PL",
    "browserColorDepth": "24",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "-60",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "systemFamily": "Windows",
    "geoLocalization": "52.2297,21.0122",
    "deviceID": "device-unique-id",
    "applicationName": "Chrome"
  }
}

Obiekt deviceInfo wymaga kompletu pól - w tym systemFamily, geoLocalization, deviceID i applicationName. Brak któregokolwiek zwróci HTTP 422. Pełna specyfikacja w Karty S2S.

Odpowiedź

Odpowiedź ma tę samą strukturę co /pay/card-otp - pole message.redirectType determinuje dalszą akcję:

`redirectType`	Znaczenie
`SUCCESS`	Środki zablokowane (autoryzacja udana) - przejdź do capture/cancellation
`FORM`	Wymagana autoryzacja 3D Secure - wyrenderuj formularz, potem ponów z `threeDsConfirmed: true`

Obsługa 3D Secure (FORM) jest identyczna jak w Karty S2S. Po udanej autoryzacji środki są zablokowane, ale jeszcze nie pobrane - kwota value z rejestracji to maksymalna kwota, którą możesz przechwycić.

Ważność blokady

Blokada środków wygasa po stronie banku wydawcy po określonym czasie (zwykle kilka-kilkanaście dni, zależnie od banku). Wykonaj capture lub cancellation przed wygaśnięciem.

Krok 2a. Przechwycenie (capture)

Aby pobrać zablokowane środki, wywołaj endpoint capture. Możesz przechwycić całość lub część autoryzacji, a także wykonać wiele przechwyceń do sumy nieprzekraczającej autoryzowanej kwoty.

POST https://api-payments.dpay.pl/api/v1_0/cards/payment/{transactionId}/capture
Content-Type: application/json

Parametry zapytania

Pole	Typ	Wymagane	Opis
`amount`	number	Tak	Kwota do przechwycenia w PLN (np. `59.99`). Suma wszystkich przechwyceń nie może przekroczyć kwoty autoryzacji

Przykład

curl -X POST https://api-payments.dpay.pl/api/v1_0/cards/payment/abc-def-123/capture \
  -H "Content-Type: application/json" \
  -d '{ "amount": 59.99 }'

Odpowiedź

{
  "success": true,
  "status": "success",
  "message": { "redirectType": "SUCCESS" }
}

Gdy suma przechwyceń osiągnie pełną kwotę autoryzacji, transakcja przechodzi w stan przechwycony (captured). Wynik każdego przechwycenia otrzymasz również przez IPN.

Przechwycenie częściowe

Jeśli kwota końcowa jest niższa niż autoryzowana (np. część zamówienia niedostępna), przechwyć tylko rzeczywistą kwotę. Pozostałą część możesz przechwycić kolejnym wywołaniem lub anulować (patrz niżej).

Krok 2b. Anulowanie autoryzacji (cancellation)

Aby zwolnić zablokowane środki bez pobrania, wywołaj endpoint anulowania. Działa tylko na autoryzacji, która nie została jeszcze w pełni przechwycona.

POST https://api-payments.dpay.pl/api/v1_0/cards/payment/{transactionId}/cancellation
Content-Type: application/json

Parametry zapytania

Pole	Typ	Wymagane	Opis
`amount`	number	Nie	Kwota do anulowania w PLN. Pominięcie = anulowanie pełne (cała pozostała, nieprzechwycona kwota). Podanie kwoty = anulowanie częściowe

Przykłady

Pełne anulowanie (zwolnienie całej blokady):

curl -X POST https://api-payments.dpay.pl/api/v1_0/cards/payment/abc-def-123/cancellation \
  -H "Content-Type: application/json" \
  -d '{}'

Częściowe anulowanie (zwolnienie części blokady):

curl -X POST https://api-payments.dpay.pl/api/v1_0/cards/payment/abc-def-123/cancellation \
  -H "Content-Type: application/json" \
  -d '{ "amount": 30.00 }'

Odpowiedź

{
  "success": true,
  "status": "success",
  "message": { "redirectType": "SUCCESS" }
}

Pełne anulowanie zamyka autoryzację - kolejne capture/cancellation nie będą już możliwe.

Cykl życia i ograniczenia

Reguła	Opis
Capture wymaga `amount`	Kwota przechwycenia jest obowiązkowa; suma przechwyceń ≤ kwota autoryzacji
Cancellation `amount` opcjonalne	Brak `amount` = pełne anulowanie pozostałej kwoty
Kolejność	Anulować można tylko żywą autoryzację - nie po pełnym przechwyceniu, anulowaniu ani finalizacji
Część przechwycona	Nie podlega anulowaniu - anulować można tylko nieprzechwyconą resztę
Wygaśnięcie	Nieprzechwycona blokada wygasa po stronie banku wydawcy

Obsługa błędów

Komunikat	Przyczyna	Działanie
`Invalid capture amount`	Brak lub nieprawidłowa kwota capture	Podaj dodatnią `amount`
`Capture amount exceeds authorized amount`	Suma przechwyceń > autoryzacja	Zmniejsz kwotę
`Transaction cannot be captured in its current state.`	Autoryzacja już przechwycona/anulowana/sfinalizowana	Sprawdź status transakcji
`Transaction cannot be cancelled in its current state.`	Autoryzacja już przechwycona/anulowana/sfinalizowana	Sprawdź status transakcji
`Cancellation amount exceeds remaining authorized amount`	Kwota anulowania > pozostała blokada	Zmniejsz kwotę
`Missing authorization reference for capture.` / `... for cancellation.`	Transakcja nie ma referencji autoryzacji (nie jest żywą pre-autoryzacją)	Sprawdź czy transakcja to poprawna, niezaksięgowana pre-autoryzacja
`Capture was declined by the card issuer.` / `Cancellation was declined by the card issuer.`	Wydawca odrzucił przechwycenie / anulowanie	Sprawdź stan transakcji i ponów w razie potrzeby

Pozostałe błędy przetwarzania (odmowa autoryzacji, nieprawidłowa karta) opisuje wspólna sekcja Komunikaty przetwarzania płatności. Pole message bywa różne w zależności od sytuacji - dopasowuj logikę luźno.

Testowanie w trybie sandbox

Na serwisie z włączonym trybem testowym cały przepływ pre-autoryzacji jest symulowany po stronie dpay - bez wychodzenia do zewnętrznego procesora kart. Możesz przećwiczyć pełną ścieżkę pre-autoryzacja → capture / cancellation przy użyciu numerów testowych kart.

Krok	Zachowanie w trybie testowym
`card-pre-auth` z numerem sukcesu	Autoryzacja zakończona sukcesem - transakcja przechodzi w stan oczekiwania na `capture`
`card-pre-auth` z numerem odmownym	Autoryzacja odrzucona - transakcja anulowana, zwracany jest błąd symulacji
`capture`	Symulowane przechwycenie środków - po pełnym capture transakcja otrzymuje status `captured`
`cancellation`	Symulowane anulowanie - pre-autoryzacja zostaje zamknięta (status `canceled`)

informacja

Scenariusz autoryzacji (sukces / odmowa) wybierany jest na podstawie numeru karty przekazanego w zaszyfrowanych danych karty - tak samo jak dla płatności card-otp. Numery testowe znajdziesz w sekcji Środowisko testowe.

Kiedy używać​

Jak działa?​

Wymagania​

Krok 1. Rejestracja i pre-autoryzacja​

Parametry zapytania​

Odpowiedź​

Krok 2a. Przechwycenie (capture)​

Parametry zapytania​

Przykład​

Odpowiedź​

Krok 2b. Anulowanie autoryzacji (cancellation)​

Parametry zapytania​

Przykłady​

Odpowiedź​

Cykl życia i ograniczenia​

Obsługa błędów​

Testowanie w trybie sandbox​

Kiedy używać

Jak działa?

Wymagania

Krok 1. Rejestracja i pre-autoryzacja

Parametry zapytania

Odpowiedź

Krok 2a. Przechwycenie (capture)

Parametry zapytania

Przykład

Odpowiedź

Krok 2b. Anulowanie autoryzacji (cancellation)

Parametry zapytania

Przykłady

Odpowiedź

Cykl życia i ograniczenia

Obsługa błędów

Testowanie w trybie sandbox