Obsłuż challenge 3-D Secure
Na tej stronie wybierzesz, jak płatnik potwierdzi płatność kartą u banku, gdy Payment API
odpowie 202 Accepted z nextAction: przekierowaniem na stronę Paymentic (domyślnie) albo
w nakładce w Twoim checkoucie przez Challenge SDK.
Wybierz sposób prezentacji
Sposób wybierasz w bloku challenge żądania
POST /transactions/{transactionId}/cards.
Bez tego bloku challenge jest prezentowany przekierowaniem.
challenge.type | nextAction | Płatnik | Po Twojej stronie |
|---|---|---|---|
REDIRECT (domyślny) | type: REDIRECT, method: GET | Przechodzi na stronę challenge.paymentic.com, potem wraca na Twój adres. | Przekierowanie i strona powrotu. |
3DS_SDK | type: 3DS_SDK, method: POST | Zostaje w checkoucie; challenge otwiera się w nakładce na Twojej stronie. | Challenge SDK na stronie checkoutu. |
Blok challenge dotyczy płatności z udziałem płatnika. Przy obciążeniu zapisanej karty (tokenType: CARD,
initiationType: MIT) płatnika nie ma, więc pola challenge nie wysyłaj.
Niezależnie od sposobu prezentacji wynik płatności niesie webhook
PAYMENT.TRANSACTION_STATUS_CHANGED.
Ani powrót płatnika, ani zdarzenie z Challenge SDK nie mówią, czy płatność się udała.
Przekierowanie (REDIRECT)
Krok 1. Podaj adres powrotu
W żądaniu płatności możesz podać challenge.returnUrl (http lub https, do 2048 znaków):
{
"tokenType": "SDK_CARD",
"token": "eyJhbGciOiJFUzI1NiJ9...",
"cardHolder": "Jan Kowalski",
"browser": {
"...": "..."
},
"challenge": {
"type": "REDIRECT",
"returnUrl": "https://shop.example/payment/return?order=123"
}
}
returnUrl jest opcjonalny. Bez niego płatnik wraca na adresy z transakcji (redirect.success,
redirect.failure), a gdy ich nie ma, na adresy ustawione w punkcie płatności. Jeśli nie podasz
returnUrl, a ani transakcja, ani punkt nie mają adresu sukcesu, API odrzuca płatność błędem
400 TRANSACTION_MISSING_DATA z polem challenge.returnUrl, zanim karta zostanie obciążona.
Sam adres porażki nie wystarczy. Nie dotyczy to SDK_APPLE_PAY: płatność Apple Pay nie wymaga
challenge'u.
| Skąd adres | Kiedy płatnik na niego wraca |
|---|---|
challenge.returnUrl | Zawsze, niezależnie od wyniku. |
| adres sukcesu transakcji lub punktu | Po ukończonym challenge'u, także gdy wynik jest jeszcze przetwarzany. |
| adres porażki transakcji lub punktu | Po nieudanym challenge'u. Bez adresu porażki płatnik wraca na adres sukcesu. |
Krok 2. Przekieruj płatnika
Z odpowiedzi 202 Accepted przekaż nextAction.url do przeglądarki i przekieruj na niego płatnika
w całym oknie:
{
"data": {
"actionId": "01kaqf5trc82bk6cqqanjcjwnq",
"status": "PENDING",
"nextAction": {
"type": "REDIRECT",
"method": "GET",
"url": "https://challenge.paymentic.com/01kaqf5trc82bk6cqqanjcjwnq",
"form": null,
"contentType": null,
"raw": null
}
}
}
window.location.assign(nextAction.url);
Strony z REDIRECT nie da się osadzić w iframe. Link jest jednorazowy: ponowne wejście (np. odświeżenie) albo wejście
po wygaśnięciu odsyła płatnika na adres powrotu.
Krok 3. Obsłuż powrót płatnika
Do adresu powrotu Paymentic dokleja parametr transactionId z identyfikatorem transakcji,
na przykład https://shop.example/payment/return?order=123&transactionId=ABCD-123-XYZ-9876.
Adres nie niesie wyniku płatności. Na stronie powrotu pokaż stan z webhooka albo odpytaj
GET /v1_2/payment/points/{pointId}/transactions/{transactionId}. Płatnik może wrócić, zanim
płatność zostanie rozliczona, więc obsłuż też stan oczekiwania.
Nakładka w checkoucie (3DS_SDK)
Challenge SDK otwiera stronę challenge'u w pełnoekranowej nakładce na Twojej stronie, pilnuje, czy się załadowała, i zamyka ją po zakończeniu. Płatnik nie opuszcza checkoutu.
Krok 1. Zażądaj prezentacji przez SDK
W żądaniu płatności wyślij "challenge": { "type": "3DS_SDK" }. Pola returnUrl nie podawaj:
przy 3DS_SDK płatnik nigdzie nie wraca, a API odrzuca je błędem walidacji.
Krok 2. Wczytaj Challenge SDK
<script src="https://challenge.paymentic.com/assets/sdk/paymentic-challenge.js"></script>
W sandboxie użyj https://challenge.sandbox.paymentic.com/assets/sdk/paymentic-challenge.js.
Skrypt definiuje jedną zmienną globalną: window.Paymentic. Nie koliduje z Card SDK (window.PaymenticCard), więc oba
skrypty mogą być na tej samej stronie.
Krok 3. Otwórz challenge
Gdy Twój backend dostanie 202 Accepted z nextAction.type równym 3DS_SDK, przekaż
nextAction.url do przeglądarki i otwórz nakładkę:
const challenge = Paymentic.mountChallenge({
url: nextAction.url,
onComplete: () => {
// challenge zakończony; wynik płatności przyjdzie webhookiem
showPendingState();
},
onError: (error) => {
// error.code: LOAD_TIMEOUT lub CHALLENGE_ERROR; wynik i tak sprawdź w statusie transakcji
showChallengeError(error.code);
},
});
Nie wysyłaj nextAction.url samodzielnie do iframe ani nie otwieraj go w nowym oknie: strona
challenge'u w trybie 3DS_SDK przyjmuje tylko żądanie POST wysłane do ramki przez SDK.
| Opcja | Typ | Wymagane | Opis |
|---|---|---|---|
url | string | tak | Pełny adres https:// z nextAction.url. |
onComplete | function | nie | Wywoływana, gdy płatnik zakończy challenge, a nakładka się zamknie. |
onError | function | nie | Wywoływana, gdy challenge się nie załaduje albo zakończy się błędem. Dostaje obiekt błędu. |
timeoutMs | number | nie | Ile milisekund czekać, aż strona challenge'u się załaduje. Domyślnie 20000. |
mountChallenge zwraca obiekt z metodą close(), która zamyka nakładkę bez wywoływania
onComplete ani onError.
Nakładka zajmuje cały ekran i blokuje przewijanie strony. Klawisz Esc jej nie zamyka: płatnik
kończy challenge na stronie banku, przyciskiem „Anuluj” albo kliknięciem w tło nakładki.
Anulowanie kończy challenge tak samo jak bank: nakładka się zamyka, wywołuje onComplete,
a o wyniku płatności decyduje bank. SDK nie ma osobnego zdarzenia anulowania.
nextAction.url można otworzyć raz, w obu trybach. Po odświeżeniu strony nie wywołuj
mountChallenge ponownie z tym samym adresem; sprawdź status transakcji.
Krok 4. Obsłuż wynik
onComplete oznacza tylko, że challenge się zakończył. Wynik płatności poznasz z webhooka
PAYMENT.TRANSACTION_STATUS_CHANGED albo z GET /v1_2/payment/points/{pointId}/transactions/{transactionId}.
onError dostaje obiekt błędu:
| Pole | Opis |
|---|---|
code | LOAD_TIMEOUT: strona challenge'u nie załadowała się w timeoutMs; nakładka pokazuje komunikat, a onError następuje po kliknięciu „Zamknij”. CHALLENGE_ERROR: challenge zakończył się błędem po stronie Paymentic, np. nie udało się przekazać wyniku do przetworzenia. |
message | Opis błędu dla programisty. Nie pokazuj go płatnikowi. |
errorCode | Dodatkowy kod błędu, jeśli jest dostępny. Przy LOAD_TIMEOUT go nie ma. Nie jest to kod odrzucenia karty. |
Po błędzie sprawdź status transakcji, zanim pozwolisz płatnikowi zapłacić ponownie.
Content Security Policy
Jeśli Twoja strona wysyła nagłówek CSP, przy 3DS_SDK dopuść challenge.paymentic.com
w script-src (skrypt SDK) i w frame-src (strona challenge'u), a w style-src dodaj
'unsafe-inline' dla stylów nakładki. Jeśli ustawiasz form-action, dopisz tam też
challenge.paymentic.com. Gotową politykę znajdziesz na stronie
Content Security Policy. Przy REDIRECT
płatnik opuszcza Twoją stronę, więc te wpisy nie są potrzebne.
Integracja bez Challenge SDK
SDK wysyła formularz POST na nextAction.url do własnej ramki i odbiera od strony challenge'u
komunikaty postMessage o typach paymentic:challenge:3ds.ready, paymentic:challenge:3ds.complete
i paymentic:challenge:3ds.error. Rekomendujemy SDK. Jeśli mimo to obsługujesz komunikaty
samodzielnie, przyjmuj je tylko wtedy, gdy event.source to Twoja ramka challenge'u,
a event.origin to origin z nextAction.url.
Co dalej
- Zrealizuj płatność tokenem: pełne żądanie i odpowiedzi.
- Testowanie kart: karty wymuszające challenge 3-D Secure w sandboxie.