Odczyt konta i ramka konta
Masz dwa sposoby pokazania merchantowi jego konta: odczyt danych przez API (budujesz własny widok) albo osadzenie gotowej ramki konta dpay (zero pracy nad UI). Oba wymagają scope account:read i delegacji merchanta (powstaje przy podpisie umowy - patrz mechanizm zgody).
Merchanta wskazujesz jego referencją (ref) w ścieżce - osobny nagłówek nie jest potrzebny. Listy są stronicowane kursorowo: iteruj po kursorze, aż go zabraknie.
Odczyt przez API
Lista merchantów
Zwraca merchantów Twojego kanału - punkt wyjścia, gdy synchronizujesz stan portfela klientów po swojej stronie.
GET/api/partner/v1/merchantsLista merchantów Twojego kanału (paginacja kursorowa).Pełny kontrakt w API Reference
Szczegóły merchanta i saldo
Zwraca dostępne saldo merchanta (w złotych), rozbite na składowe per produkt. Saldo bierz zawsze stąd - patrz uwaga niżej.
GET/api/partner/v1/merchants/{ref}Szczegóły merchanta i jego dostępne saldo.Pełny kontrakt w API Reference
Transakcje
GET/api/partner/v1/merchants/{ref}/transactionsTransakcje merchanta (paginacja kursorowa).Pełny kontrakt w API Reference
Pole status to numeryczny status transakcji dpay (ten sam, który dostajesz w webhookach payment.*) - znaczenie opisują statusy transakcji. Korelację z Twoimi obiektami prowadź po payment_id (zwracanym przy rejestracji płatności) - lista nie zawiera Twoich własnych identyfikatorów.
Rozliczenia
Zwraca kwoty wypłacone na rachunek merchanta wraz z ich stanem.
GET/api/partner/v1/merchants/{ref}/settlementsRozliczenia wypłacone na rachunek merchanta.Pełny kontrakt w API Reference
Nie licz salda po stronie klienta z sumy transakcji - saldo z API uwzględnia zwroty, prowizje i zaklepane wypłaty. Zawsze bierz balance z dpay.
Osadzalna ramka konta
Zamiast budować własny widok, możesz osadzić gotową, brandowaną ramkę konta dpay. Merchant widzi w niej swoje saldo i transakcje, może wyrazić opt-in na wypłaty (kod SMS) oraz cofnąć dostęp Twojej aplikacji - wszystko wewnątrz Twojego produktu, bez logowania do dpay.
Jak osadzić
Ramka używa tokenu czasowego, aby merchant nie musiał logować się do dpay. Adres ramki mintujesz po swojej stronie serwera (scope account:read + delegacja), a następnie przekazujesz token do SDK.
Krok 1 - zamintuj adres ramki (serwer):
GET/api/partner/v1/merchants/{ref}/account-frameZamintuj krótkotrwały adres osadzalnej ramki konta.Pełny kontrakt w API Reference
Krok 2 - zamontuj ramkę (przeglądarka):
Token to ostatni segment ścieżki embed_url:
<div id="dpay-account"></div>
<script src="https://panel.dpay.pl/sdk/dpay-onboarding-sdk.js"></script>
<script>
DpayOnboarding.mountAccount('#dpay-account', {
token: '<token z embed_url>',
locale: 'pl',
onEvent: (e) => {
if (e.type === 'revoked') {
// merchant cofnął dostęp - zaktualizuj swój UI
}
},
});
</script>
Token ramki - zasady
- Ważność: 15 minut (
expires_atw odpowiedzi mintu). Token jest krótkotrwały - generuj go tuż przed osadzeniem, przy wejściu merchanta na stronę konta. - Mintuj po stronie serwera. Nigdy nie wystawiaj klucza
dpk_...w przeglądarce. Adres ramki pobierasz na backendzie i przekazujesz token do front-endu. - Jeden token na sesję ramki. Po wygaśnięciu zamintuj nowy.
Do przeglądarki trafia wyłącznie krótkotrwały token ramki, nigdy Twój klucz dpk_.... Klucz partnera daje dostęp do wszystkich Twoich merchantów - musi pozostać po stronie serwera.
Zdarzenia ramki
Ramka emituje zdarzenia przez postMessage (jak widżet onboardingu) - callback dostaje { type, payload }:
| Zdarzenie | Kiedy |
|---|---|
ready | Ramka się załadowała. |
resize | Zmiana wysokości treści (SDK dopasowuje iframe). |
cookies_blocked | Przeglądarka blokuje ciasteczka - SDK renderuje fallback "kontynuuj w nowym oknie". |
error | Iframe nie załadował się (reason: load_timeout / iframe_error). |
revoked | Merchant cofnął dostęp Twojej aplikacji (wszystkie zakresy). Zareaguj i przestań wykonywać akcje on-behalf. |