Przejdź do głównej zawartości

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.typenextActionPłatnikPo Twojej stronie
REDIRECT (domyślny)type: REDIRECT, method: GETPrzechodzi na stronę challenge.paymentic.com, potem wraca na Twój adres.Przekierowanie i strona powrotu.
3DS_SDKtype: 3DS_SDK, method: POSTZostaje 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 adresKiedy płatnik na niego wraca
challenge.returnUrlZawsze, niezależnie od wyniku.
adres sukcesu transakcji lub punktuPo ukończonym challenge'u, także gdy wynik jest jeszcze przetwarzany.
adres porażki transakcji lub punktuPo 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.

OpcjaTypWymaganeOpis
urlstringtakPełny adres https:// z nextAction.url.
onCompletefunctionnieWywoływana, gdy płatnik zakończy challenge, a nakładka się zamknie.
onErrorfunctionnieWywoływana, gdy challenge się nie załaduje albo zakończy się błędem. Dostaje obiekt błędu.
timeoutMsnumbernieIle 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:

PoleOpis
codeLOAD_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.
messageOpis błędu dla programisty. Nie pokazuj go płatnikowi.
errorCodeDodatkowy 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​