Onboarding przez API (headless)

Tryb dla partnerów, którzy chcą pełną kontrolę nad UI. Zbierasz dane merchanta we własnym interfejsie i wysyłasz je do dpay segmentami przez API. Akty, które prawnie musi wykonać sama osoba (weryfikacja kontaktu i tożsamości, oświadczenia, podpis umowy), realizuje merchant w krótkim hostowanym hand-offie dpay. Opłatę aktywacyjną możesz natomiast poprowadzić we własnym UI - patrz Opłata aktywacyjna.

Model hybrydowy

Dane strukturalne (firma, rachunek, beneficjenci, dokumenty) wysyłasz przez API i renderujesz we własnym UI. Akty osobiste (weryfikacja tożsamości, oświadczenia PEP, podpis umowy) zostają hostowane przez dpay - to wymóg bezpieczeństwa i zgodności, którego nie da się przenieść do Twojego UI.

Cały przepływ

Krok 1: utwórz draft

Draft wymaga danych kontaktowych osoby zakładającej konto i zaakceptowanych zgód. W odpowiedzi dostajesz ref (Twój partner_external_ref), którym adresujesz wszystkie dalsze wywołania.

Listę zgód do pokazania merchantowi pobierasz z API. W polu consents wyślij ID wszystkich definicji z required: true oraz tych dobrowolnych, które merchant sam zaznaczył. ID zmieniają się przy publikacji nowej wersji treści, więc pobieraj listę przed utworzeniem draftu zamiast wpisywać ID na sztywno. Brak wymaganej zgody albo nieaktualne ID kończy się 422 z listą brakujących pozycji w formacie key (id N).

GET/api/partner/v1/consents→Aktywne definicje zgód (ID do pola consents).Pełny kontrakt w API Reference POST/api/partner/v1/onboarding→Utwórz draft onboardingu (idempotentne po partner_external_ref).Pełny kontrakt w API Reference

Utworzenie draftu jest idempotentne: powtórne POST /onboarding z tym samym partner_external_ref zwróci istniejący draft (200), nie utworzy duplikatu. Odpowiedź nie zawiera adresu hostowanego flow - dostaniesz go z finalize lub GET /onboarding/{ref} w polu next_action.url.

Krok 2: wyślij dane segmentami

Uzupełniasz draft niezależnymi segmentami. Każdy segment możesz wysłać osobno i wielokrotnie (nadpisuje poprzednią wartość). Gdy konto jest już aktywne, segmenty zapisu przestają być edytowalne i zwracają 409.

Dane firmy

Segment rozstrzyga typ podmiotu (osoba fizyczna czy firma) i - dla firmy - zbiera dane rejestrowe oraz adres. Po podaniu NIP dpay pobiera dane z rejestrów publicznych; podmiot wykreślony z rejestru zwraca 422.

PATCH/api/partner/v1/onboarding/{ref}/company→Dane firmy / typ podmiotu.Pełny kontrakt w API Reference

Rachunek bankowy i profil transakcyjny

Rachunek, na który merchant będzie otrzymywał rozliczenia i wypłaty, wraz z profilem działalności wymaganym przez przepisy AML. Segment wymaga wcześniejszego ustalenia typu podmiotu (PATCH /company).

PATCH/api/partner/v1/onboarding/{ref}/bank-account→Rachunek rozliczeniowy i profil transakcyjny (AML).Pełny kontrakt w API Reference

Dane tożsamości i reprezentacji

Prefill tożsamości głównego wnioskodawcy. Dotyczy osoby fizycznej lub właściciela JDG; w spółce wieloosobowej tożsamość reprezentanta ustalana jest w hostowanym flow (ten segment zwróci wtedy 422). Sama weryfikacja tożsamości i oświadczenia PEP zawsze zostają w hand-offie.

PATCH/api/partner/v1/onboarding/{ref}/identity→Prefill tożsamości głównego wnioskodawcy.Pełny kontrakt w API Reference

Segment reprezentacji dotyczy tylko spółek wieloosobowych (422 w pozostałych przypadkach). Odpowiedź wskazuje tryb reprezentacji i czy wymagane jest zaproszenie lub pełnomocnictwo.

PATCH/api/partner/v1/onboarding/{ref}/representation→Reprezentacja spółki wieloosobowej.Pełny kontrakt w API Reference

Dokumenty, beneficjenci, zaproszenia

Dokumenty przesyłasz jako plik (multipart lub base64) z typem dokumentu i podmiotem, albo jako dokument działalności regulowanej. Odpowiedź zwraca document_id - zachowaj go, aby dołączyć pełnomocnictwo do zaproszenia reprezentanta-pełnomocnika. Duplikat dokumentu regulowanego zwraca 409.

POST/api/partner/v1/onboarding/{ref}/documents→Prześlij dokument (multipart lub base64).Pełny kontrakt w API Reference

Beneficjenci rzeczywiści dotyczą spółek wieloosobowych - dodajesz ich wraz z tożsamością, adresem, dokumentem i oświadczeniami. Dodany wpis możesz też usunąć.

POST/api/partner/v1/onboarding/{ref}/beneficiaries→Dodaj beneficjenta rzeczywistego.Pełny kontrakt w API Reference DELETE/api/partner/v1/onboarding/{ref}/beneficiaries/{uuid}→Usuń beneficjenta.Pełny kontrakt w API Reference

Jeśli akty osobiste ma dokończyć inna osoba (członek zarządu lub beneficjent), zapraszasz ją - dostanie własny link do hostowanego flow. Zaproszenie jest idempotentne po external_ref (powtórka nie wyśle drugiego SMS-a), a odpowiedzi oraz lista zaproszeń są wolne od danych osobowych zaproszonego. Możesz też ponowić wysyłkę (cooldown - zbyt szybka powtórka zwraca 429) lub anulować zaproszenie (link przestaje działać).

POST/api/partner/v1/onboarding/{ref}/invitations→Zaproś drugą osobę (reprezentant / beneficjent).Pełny kontrakt w API Reference GET/api/partner/v1/onboarding/{ref}/invitations→Lista zaproszeń (bez danych osobowych).Pełny kontrakt w API Reference POST/api/partner/v1/onboarding/{ref}/invitations/{id}/resend→Ponów wysyłkę zaproszenia.Pełny kontrakt w API Reference DELETE/api/partner/v1/onboarding/{ref}/invitations/{id}→Anuluj zaproszenie.Pełny kontrakt w API Reference

Prefill z rejestrów

Nie musisz zbierać wszystkiego ręcznie. Po podaniu NIP dpay potrafi uzupełnić dane firmy i beneficjentów z rejestrów publicznych. W praktyce często wystarczy wysłać NIP i rachunek, a resztę merchant tylko potwierdza w hand-offie.

Krok 3: finalize

Gdy komplet danych jest wysłany, wywołujesz finalize. To operacja tylko do odczytu: sprawdza kompletność danych i zwraca hostowany hand-off - zawsze z kodem 200, także gdy czegoś brakuje.

POST/api/partner/v1/onboarding/{ref}/finalize→Sprawdź kompletność i pobierz hostowany hand-off.Pełny kontrakt w API Reference

• next_action.url to hostowany adres wznowienia: loguje merchanta (tokenem w ścieżce) i przenosi go do właściwego kroku.
• next_action.embeddable mówi, czy możesz osadzić ten adres w iframe: true, gdy Twoja domena jest zarejestrowana do osadzania. Przy false przekieruj merchanta na next_action.url na najwyższym poziomie okna.
• missing to lista kodów braków danych. Pusta lista oznacza komplet danych - merchant nadal musi wykonać akty osobiste pod next_action.url.

Kody braków (missing[])

Kod	Znaczenie
account_type.missing	Nie wybrano typu podmiotu (najpierw PATCH /company).
company.nip_missing	Brak NIP / danych rejestrowych firmy.
bank.account_missing	Brak rachunku / profilu transakcyjnego.
identity.pesel_missing	Brak tożsamości głównego wnioskodawcy (osoba fizyczna / JDG).
representation.required	Brak decyzji o reprezentacji (spółka wieloosobowa).
beneficiaries.required	Brak beneficjenta rzeczywistego i brak oczekującego zaproszenia.
documents.required	Zaległe dokumenty (w tym bazowe dokumenty firmowe).

Krok 4: hand-off aktów osobistych

Przekieruj merchanta na next_action.url (albo osadź go przez SDK), aby dokończył akty, których nie da się wykonać przez API:

• weryfikacja kontaktu (kody SMS + e-mail),
• weryfikacja tożsamości,
• oświadczenia (m.in. PEP),
• podpis umowy (kod SMS),
• opłata aktywacyjna - jedyny z tych kroków, który możesz poprowadzić we własnym UI: patrz Opłata aktywacyjna.

Po każdej zmianie statusu dostajesz webhook merchant.updated.

Wznawianie i osadzanie (token wznowienia)

Token wznowienia to ostatni segment ścieżki next_action.url (48 znaków, bez przedrostka). Możesz osadzić hand-off w swojej stronie przez SDK:

<script src="https://panel.dpay.pl/sdk/dpay-onboarding-sdk.js"></script>
<script>
  DpayOnboarding.mountResume('#dpay-onboarding', {
    token: '<token z next_action.url>',
    ref: 'faktura-klient-123',
    onEvent: function (e) { /* { type, payload } */ },
  });
</script>

Katalog zdarzeń i pozostałe opcje opisuje onboarding przez iframe. Jeśli next_action.embeddable jest false, zamiast osadzać przekieruj merchanta na next_action.url.

Token wznowienia jest wrażliwy i ograniczony czasowo

Token daje dostęp do dokończenia onboardingu tego merchanta - traktuj go jak sekret (nie loguj, nie osadzaj w URL współdzielonych). Link jest ważny 45 dni i przestaje działać po aktywacji konta - w obu przypadkach zwraca 410 Gone. Powtórny POST /onboarding z tym samym ref zwraca istniejący draft bez wymiany tokenu - po wygaśnięciu linku skontaktuj się z dpay.

Status onboardingu

Status pojedynczego onboardingu odczytasz w każdej chwili. next_action jest zawsze obiektem (jego url może być null), a lista invited nie zawiera danych osobowych zaproszonych.

GET/api/partner/v1/onboarding/{ref}→Status pojedynczego onboardingu.Pełny kontrakt w API Reference

Listę wszystkich onboardingów Twojego kanału zwraca osobny endpoint z paginacją kursorową. Znaczenie statusów opisuje cykl życia konta.

GET/api/partner/v1/onboarding→Lista onboardingów kanału (paginacja kursorowa).Pełny kontrakt w API Reference

Źródło prawdy

Do reakcji na zmiany używaj webhooków (push), a GET /onboarding/{ref} traktuj jako uzupełniające sprawdzenie (pull). Nie odpytuj statusu w pętli co sekundę.

Kody błędów

Kod	Znaczenie
401	Brak / nieprawidłowy / cofnięty klucz partnera albo klucz testowy dp_test_ konta produkcyjnego.
403	Klucz nie ma wymaganego scope.
404	Nieznany ref w Twoich kanałach.
409	Onboarding już aktywny - dane nie są już edytowalne (lub duplikat dokumentu regulowanego).
410	Link wznowienia wygasł lub konto jest już aktywne (trasa hostowana).
422	Błąd walidacji albo segment nie dotyczy tego typu podmiotu.
429	Cooldown ponownej wysyłki zaproszenia.