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.
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ę
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.
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ć.
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.
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 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ę |
Error during capture / Error during cancellation | Odrzucenie po stronie operatora | Sprawdź stan transakcji i ponów w razie potrzeby |
Testowanie w trybie sandbox
Tryb testowy serwisu obejmuje płatności card-otp oraz portfele (Apple Pay, Google Pay). Zapytania card-pre-auth, capture i cancellation nie mają symulacji - nawet na serwisie z włączonym trybem testowym trafiają do realnego procesora kart. Nie testuj pre-autoryzacji numerami testowymi - użycie ich zakończy się odrzuceniem po stronie procesora. Testy pre-autoryzacji uzgodnij z BOK dpay.