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.

Odczyt przez API

Lista merchantów

GET https://panel.dpay.pl/api/partner/v1/merchants
Authorization: Bearer dpk_twoj_klucz_platformy

Zwraca merchantów Twojego kanału jako {data: [...], next_cursor} (paginacja kursorowa: per_page do 200 i cursor). Każdy wiersz to {ref, channel, status}.

Szczegóły merchanta i saldo

GET https://panel.dpay.pl/api/partner/v1/merchants/faktura-klient-123
Authorization: Bearer dpk_twoj_klucz_platformy

{
  "ref": "faktura-klient-123",
  "channel": "fakturka",
  "status": "completed",
  "balance": {
    "transfer": 3480.50,
    "paysafecard": 0,
    "total": 3480.50,
    "currency": "PLN"
  }
}

balance.total to dostępne saldo merchanta (kwoty w złotych), rozbite na składowe per produkt.

Transakcje

GET https://panel.dpay.pl/api/partner/v1/merchants/faktura-klient-123/transactions
Authorization: Bearer dpk_twoj_klucz_platformy

Zwraca {data: [...], next_cursor}. Parametry zapytania to wyłącznie per_page (do 200) i cursor - lista nie obsługuje filtrów. Każdy wiersz:

{
  "payment_id": "8F2A11C4-...",
  "value": 149.00,
  "status": 1,
  "payment_method": "blik",
  "refunded_amount": 0,
  "created_at": "2026-07-01 10:00:00",
  "paid_at": "2026-07-01 10:05:00"
}

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

GET https://panel.dpay.pl/api/partner/v1/merchants/faktura-klient-123/settlements
Authorization: Bearer dpk_twoj_klucz_platformy

Zwraca {data: [...], next_cursor} (paginacja jak wyżej). Każdy wiersz: {id, state, net, fee, gross, currency, created_at, exported_at} - kwoty wypłacone na rachunek merchanta i ich stan.

Saldo bierz z danych dpay

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.

Ramka konta osadzona w produkcie partnera - saldo, ostatnie transakcje, opt-in wypłat i możliwość cofnięcia dostępu.

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 https://panel.dpay.pl/api/partner/v1/merchants/faktura-klient-123/account-frame
Authorization: Bearer dpk_twoj_klucz_platformy

{
  "embed_url": "https://panel.dpay.pl/connect/account-frame/{token}",
  "expires_at": "2026-07-01T10:15:00+00:00"
}

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_at w 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.

Klucz partnera zostaje na serwerze

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.

Co dalej

• Płatności on-behalf
• Wypłaty on-behalf
• Webhooki