Onboarding przez iframe (widżet)

Najprostszy sposób. Osadzasz gotowy, brandowany widżet onboardingu dpay w swojej stronie za pomocą kilku linii JavaScript. Merchant przechodzi całą rejestrację (dane firmy, rachunek, weryfikacja, podpis umowy) bez opuszczania Twojego produktu.

Widżet onboardingu osadzony w produkcie partnera. Merchant nie opuszcza Twojej aplikacji, a jego dane nie przechodzą przez Twój serwer.

Szybki start

Dołącz SDK i zamontuj widżet w wybranym kontenerze. Pierwszy argument to selektor (lub element DOM), drugi to opcje:

<div id="dpay-onboarding"></div>

<script src="https://panel.dpay.pl/sdk/dpay-onboarding-sdk.js"></script>
<script>
  const handle = DpayOnboarding.mount('#dpay-onboarding', {
    ch: 'fakturka',                // Twój kanał
    ref: 'faktura-klient-123',     // Twoja referencja merchanta (opcjonalna, patrz niżej)
    locale: 'pl',
    onEvent: (e) => {
      console.log('dpay event:', e.type, e.payload);
    },
  });
</script>

To wszystko. Widżet renderuje się jako iframe wskazujący na hostowany onboarding dpay. mount zwraca uchwyt { destroy() } - wywołaj destroy(), aby usunąć iframe i odpiąć nasłuchy (np. przy zmianie trasy w SPA).

Opcje mount(target, options)

Opcja	Wymagana	Opis
ch	tak	Twój kanał onboardingu (przekazywany do iframe jako ?ch=).
ref	nie	Twój identyfikator merchanta po stronie ISV (do 128 znaków). Wróci do Ciebie w webhookach, statusie i zdarzeniu completed, ułatwia korelację.
locale	nie	Język widżetu (pl, en, ...).
host	nie	Bazowy adres dpay (domyślnie origin skryptu SDK). Wyznacza też zaufany origin postMessage.
minHeight	nie	Minimalna wysokość iframe w pikselach przed pierwszym resize (domyślnie 600).
loadTimeout	nie	Ile milisekund czekać na pierwsze ready (domyślnie 20000); po przekroczeniu emitowane jest error z reason: 'load_timeout'.
onEvent	nie	Callback wywoływany dla każdego zdarzenia z widżetu - dostaje obiekt { type, payload } (patrz niżej).

Po co ref

ref to Twój własny klucz merchanta (np. ID rekordu w Twojej bazie). dpay zwraca go w webhookach i w statusie onboardingu, więc bez trzymania dodatkowych map wiesz, którego Twojego użytkownika dotyczy zdarzenie.

Zdarzenia (postMessage)

Widżet komunikuje się z Twoją stroną przez postMessage. SDK opakowuje to w callback onEvent, który dostaje { type, payload }. Reaguj na zdarzenia, aby aktualizować swój UI.

type	payload	Kiedy	Typowa reakcja
ready	-	Widżet się załadował.	Ukryj własny spinner.
resize	{ height }	Zmieniła się wysokość treści.	Nic - SDK sam dopasowuje wysokość iframe.
step_changed	{ step }	Merchant przeszedł do kolejnego kroku.	Opcjonalnie pokaż własny progres.
completed	{ ref }	Onboarding zakończony (konto aktywne lub w przeglądzie).	Przenieś merchanta dalej w swoim produkcie.
cookies_blocked	-	Przeglądarka blokuje ciasteczka firm trzecich.	SDK sam renderuje fallback "kontynuuj w nowym oknie"; możesz dodatkowo pokazać wskazówkę lub przełączyć na redirect.
error	{ reason }	Iframe nie załadował się: reason to load_timeout lub iframe_error.	Pokaż komunikat i zaproponuj redirect.
redirect_top	{ url }	Flow wymaga wyjścia z ramki na najwyższy poziom okna.	Nic - SDK sam wykonuje przekierowanie.

Przykład reakcji na zakończenie:

DpayOnboarding.mount('#dpay-onboarding', {
  ch: 'fakturka',
  ref: 'faktura-klient-123',
  onEvent: (e) => {
    if (e.type === 'completed') {
      window.location.href = '/dashboard?onboarding=done';
    }
    if (e.type === 'error') {
      showFallbackToRedirect();
    }
  },
});

Nie polegaj wyłącznie na completed

Zdarzenie completed w przeglądarce jest wygodne dla UX, ale nie jest źródłem prawdy. Ostateczny status konta zawsze potwierdzaj webhookiem lub odczytem statusu po swojej stronie serwera. Użytkownik może zamknąć kartę tuż przed zdarzeniem.

Pozostałe metody SDK

Ten sam skrypt SDK udostępnia także:

• DpayOnboarding.mountResume(target, { token, ... }) - osadza hostowany hand-off onboardingu utworzonego przez API (token z next_action.url).
• DpayOnboarding.mountAccount(target, { token, ... }) - osadza ramkę konta merchanta (token z mintu ramki).

Obie metody przyjmują te same opcje co mount (bez ch - kanał wynika z tokenu) i zwracają ten sam uchwyt { destroy() }.

Domeny (CSP i ramka)

Widżet ładuje iframe z https://panel.dpay.pl. Jeśli używasz Content-Security-Policy, dopuść tę domenę:

frame-src https://panel.dpay.pl;
script-src https://panel.dpay.pl;

Dodatkowo dpay musi znać domenę, na której osadzasz widżet. Podaj ją zespołowi dpay lub dodaj w portalu partnera (sekcja Domeny). To zabezpieczenie przed osadzeniem Twojego kanału na obcej stronie - bez zarejestrowanej domeny iframe zostanie odrzucony przez nagłówek frame-ancestors.

Ciasteczka firm trzecich

Widżet działa w iframe cross-site, więc w niektórych przeglądarkach (domyślne blokowanie ciasteczek 3rd-party) potrzebuje pojedynczego ciasteczka do utrzymania sesji onboardingu. dpay używa mechanizmu współdzielonego ciasteczka dla całej grupy onboardingu.

Gdy przeglądarka blokuje ciasteczka, widżet wyśle zdarzenie cookies_blocked, a SDK wyrenderuje fallback "kontynuuj w nowym oknie". Alternatywą jest przełączenie merchanta na onboarding przez redirect, który nie wymaga ciasteczek 3rd-party.

Kiedy wybrać iframe

• Chcesz gotowy, spójny UI dpay bez budowania własnego.
• Zależy Ci, aby merchant nie opuszczał Twojego produktu.
• Akceptujesz zależność od ciasteczek 3rd-party (z fallbackiem do nowego okna / redirect).

Jeśli wolisz pełną kontrolę nad UI, zobacz onboarding przez API.