Onboarding partnera

Zanim zaczniesz onboardować merchantów, dpay skonfiguruje Twoje konto partnera. Ten rozdział opisuje co dostajesz i jak działa uwierzytelnianie.

Co otrzymujesz od dpay

Element	Opis
Klucz API (dpk_...)	Jeden klucz platformy. Uwierzytelnia wszystkie wywołania API partnera. Pokazywany raz przy generacji.
Scope'y	Zakres uprawnień klucza (patrz niżej).
Kanał (channel)	Identyfikator Twojego kanału onboardingu. Wiąże każde konto merchanta z Tobą i determinuje szablon umowy oraz stawki.
Sekret webhooka	Do weryfikacji podpisu HMAC przychodzących webhooków.

Klucz API pokazywany jest raz

Zapisz dpk_... w bezpiecznym miejscu (menedżer sekretów, zmienna środowiskowa). dpay przechowuje tylko hash - jeśli zgubisz klucz, trzeba go zregenerować, a stary przestanie działać.

Uwierzytelnianie wywołań

Każde wywołanie API partnera wysyłasz z nagłówkiem:

Authorization: Bearer dpk_twoj_klucz_platformy

Bazowy adres API partnera:

https://panel.dpay.pl/api/partner/v1

Wyjątkiem jest rejestracja płatności on-behalf - to tryb klasycznego endpointu rejestracji na domenie płatności (https://api-payments.dpay.pl).

Scope'y

Klucz ma przypisane scope'y. Wywołanie poza zakresem klucza dostaje odpowiedź 403.

Scope	Pozwala na
onboarding:read	Odczyt statusu onboardingów Twoich merchantów.
onboarding:write	Tworzenie i uzupełnianie onboardingów (draft, segmenty, finalize).
account:read	Odczyt konta merchanta on-behalf (transakcje, rozliczenia, saldo, ramka konta).
payments:write	Rejestrowanie płatności w imieniu merchanta.
payouts:write	Zlecanie wypłat w imieniu merchanta.

Podwójna bramka uprawnień

Scope na kluczu to warunek konieczny, ale nie wystarczający. Do akcji on-behalf potrzebna jest także zgoda merchanta (delegacja) obejmująca dany zakres. Sam scope payouts:write nie wystarczy, jeśli merchant nie wyraził opt-in na wypłaty. Patrz sekcja niżej.

Kanał onboardingu

Twój kanał (np. fakturka) to sposób, w jaki dpay rozpoznaje że dane konto należy do Ciebie. Kanał determinuje:

• szablon umowy podpisywanej przez merchanta,
• stawki (MDR) obowiązujące merchantów w Twoim kanale,
• przypisanie konta do Twojego partnera (model captive).

W onboardingu iframe kanał przekazujesz opcją ch. W API i redirect kanał jest wywiedziony z Twojego klucza (gdy klucz ma kilka kanałów, wskazujesz go polem channel).

Mechanizm zgody merchanta (delegacja)

Aby działać w imieniu merchanta, potrzebujesz jego wyraźnej zgody. Zgoda dzieli się na dwa poziomy i każdą merchant potwierdza kodem SMS (to jedyny kanał OTP):

1. Odczyt + płatności - nadawane automatycznie w momencie podpisania przez merchanta umowy Twojego kanału (podpis kodem SMS w onboardingu). Nie ma osobnego wywołania API "poproś o zgodę" - delegacja jest częścią umowy kanału, a podpis jest silnym uwierzytelnieniem osoby uprawnionej.
2. Wypłaty - osobny, świadomy opt-in merchanta w ramce konta, także potwierdzany kodem SMS. Nigdy nie wynika z samej umowy.

Merchant widzi dokładnie na co się zgadza (osobno wypłaty) i potwierdza kodem SMS. dpay nigdy nie przekazuje Ci danych logowania merchanta.

Jak przebiega delegacja

Zasady delegacji

• Wypłaty wymagają osobnej zgody. Nawet jeśli merchant podpisał umowę (odczyt + płatności), wypłaty (payouts:write) to oddzielny, świadomy opt-in w ramce konta, z własnym kodem SMS.
• Wypłata zawsze na rachunek merchanta. Zgoda na wypłaty nie oznacza, że możesz wskazać dowolny rachunek. dpay wypłaca wyłącznie na zweryfikowany rachunek merchanta - zawsze całe dostępne saldo.
• Cofnięcie jest natychmiastowe i całkowite. Merchant cofa dostęp w ramce konta (kod SMS). Cofnięcie obejmuje wszystkie zakresy naraz - od tej chwili wywołania on-behalf zwracają 403 (fail-closed). Dostajesz o tym webhook authorization.revoked.

Następny krok

Wybierz sposób onboardingu merchantów:

• Onboarding przez iframe - gotowy widżet dpay osadzony u Ciebie.
• Onboarding przez redirect - hostowane flow dpay.
• Onboarding przez API - headless, własny UI.