Płatność i potwierdzenie rachunku

Dwa cele sesji, które odpowiadają na jedno pytanie: czy ten rachunek bankowy naprawdę należy do tej osoby lub firmy.

Cel sesji	Co robi	Czego dowodzi
activation_payment	Inicjuje przelew z rachunku klienta (PIS)	Klient ma dostęp do rachunku i zlecił z niego przelew
account_ownership	Loguje klienta do jego banku (AIS)	Nazwa właściciela rachunku i numer rachunku

Cele są niezależne - możesz użyć jednego albo obu. Razem dają najmocniejszy dowód: pieniądze wyszły z rachunku, a rachunek należy do właściwej osoby.

Nie podajesz dostawcy

Dla obu celów nie przekazujesz pola provider - hub sam dobiera dostawcę na podstawie celu. Dzięki temu zmiana dostawcy po naszej stronie nie wymaga zmian po Twojej.

Krok 1: pobierz listę banków

Zwracamy wyłącznie banki dostępne w danej chwili - wyłączone i chwilowo niesprawne są już odfiltrowane. Lista zmienia się rzadko, więc warto ją cache'ować.

GET/api/v1/banks→Banki dostępne dla danego celu sesji.Pełny kontrakt w API Reference

curl "https://hub.dpay.pl/api/v1/banks?purpose=activation_payment&country=PL" \
  -H "Authorization: Bearer deid_live_xxx"

Pokrycie banków może się różnić między celami, więc pytaj o listę dla tego celu, którego faktycznie użyjesz.

Krok 2: pokaż obie kategorie bankowości

Banki różnią się tym, gdzie obsługują firmy. Część prowadzi konta firmowe w zwykłej bankowości internetowej, część ma osobny system dla firm. Nie da się tego wywnioskować z formy prawnej klienta - pokaż obie kategorie i pozwól wybrać:

metadata.account_variant	Etykieta dla klienta	Kiedy
retail	Bankowość indywidualna	Zwykłe logowanie; w wielu bankach także konta firmowe
company	Bankowość firmowa	Osobny system dla firm

Domyślnie retail. Zły wariant kończy się tym, że klient nie widzi swojego rachunku.

Płatność weryfikacyjna (activation_payment)

curl -X POST https://hub.dpay.pl/api/v1/verifications \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "activation_payment",
    "external_id": "klient-12345",
    "redirect_url": "https://twoja-aplikacja.pl/powrot",
    "metadata": {
      "bank_id": "mbank",
      "account_variant": "retail",
      "amount": "10.00",
      "title": "Oplata aktywacyjna nr 12345",
      "recipient_account_number": "PL61109010140000071219812874",
      "recipient_name_address": "Twoja Firma sp. z o.o. Warszawa",
      "expected_iban": "PL27114020040000300201355387"
    }
  }'

Parametry płatności

Pole metadata	Wymagane	Opis
bank_id	tak	Z listy banków
amount	tak	Kwota w złotych, format d.dd
title	tak	Tytuł przelewu, 5-140 znaków
recipient_account_number	tak	Rachunek odbiorcy
recipient_name_address	tak	Nazwa i adres odbiorcy
account_variant	nie	retail (domyślnie) lub company
expected_iban	nie	Rachunek, z którego klient ma zapłacić - patrz niżej

Polskie znaki w tytule i nazwie odbiorcy

Wartości przekazujemy dostawcy nagłówkami HTTP, które nie unoszą znaków spoza ASCII. Hub koduje je za Ciebie - przekazuj zwykły tekst. Pamiętaj tylko o limicie 5-140 znaków po stronie tytułu i o tym, że dozwolone są litery, cyfry, spacja i _ - . : / , +.

Zawężenie rachunku nadawcy

expected_iban mówi, z którego rachunku klient ma zapłacić. Działa dwustopniowo:

1. Przed płatnością - część banków ograniczy wybór do tego rachunku. Które, poznasz po fladze supports_sender_account na liście banków.
2. Po płatności - zawsze porównujemy rachunek nadawcy z expected_iban i zwracamy sam werdykt.

Traktuj punkt 1 jako usprawnienie dla klienta, a nie jako mechanizm kontrolny - kontrolą jest punkt 2.

Potwierdzenie właściciela rachunku (account_ownership)

curl -X POST https://hub.dpay.pl/api/v1/verifications \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "account_ownership",
    "external_id": "klient-12345",
    "redirect_url": "https://twoja-aplikacja.pl/powrot",
    "metadata": {
      "bank_id": "mbank",
      "account_variant": "retail",
      "expected_iban": "PL27114020040000300201355387"
    }
  }'

Klient loguje się do banku i wyraża zgodę na jednorazowy odczyt danych rachunku. Zgoda jest jednorazowa - nie korzystamy z niej ponownie.

Wyniki

Po zakończeniu sesji pobierz wynik.

GET/api/v1/verifications/{id}/result→Wynik sesji: stan płatności albo dane właściciela rachunku.Pełny kontrakt w API Reference

activation_payment

Pole verified_data	Opis
payment_status	initiated, pending, done, rejected, cancelled
sender_account_last_four	Cztery ostatnie znaki rachunku nadawcy
iban_match	Werdykt porównania z expected_iban
amount, bank_id	Kwota i bank

account_ownership

Pole verified_data	Opis
name_address	Nazwa i adres właściciela rachunku, tak jak zwrócił je bank
full_name, first_name, last_name, address	Rozdzielone best-effort; name_address jest wartością źródłową
account_number_last4	Cztery ostatnie znaki rachunku
iban_match	Werdykt porównania z expected_iban
consent_expires_at	Termin ważności zgody

null to nie false

iban_match może przyjąć trzy wartości. true znaczy zgodny, false znaczy realną niezgodność, a null znaczy „nie ustalono" - nie podałeś expected_iban albo bank nie zwrócił numeru rachunku. Potraktowanie null jak false da fałszywe odrzucenia.

Pełny numer rachunku nie opuszcza huba. Otrzymujesz werdykt porównania i cztery ostatnie znaki - tyle, ile trzeba, żeby klient rozpoznał swój rachunek.

Dopasowanie nazwy właściciela

name_address to jeden sklejony ciąg: nazwa i adres razem, w formacie zależnym od banku. Ta sama firma bywa zapisana na wiele sposobów, a nazwa ulicy potrafi wyglądać jak nazwisko. Jeśli porównujesz to z własnymi danymi, nie polegaj na porównaniu dosłownym.

Cel sesji - konsekwencje

Oba cele zachowują się tak samo:

• TTL sesji: 60 minut - logowanie do banku i autoryzacja przelewu trwają dłużej niż skan dokumentu
• Dostępne tryby: tylko single - jedna płatność i jedno logowanie
• Pole provider: nie podajesz go

Czas i przebieg

• Czas: od kilku sekund do kilku godzin
• Potwierdzenie płatności: przychodzi z bardzo różnym opóźnieniem, zależnie od banku

Każdy stan nieterminalny traktuj jako „czekamy", nie jako niepowodzenie. Ustaw webhooki, a odpytywanie statusu zostaw jako zabezpieczenie na wypadek niedostarczonej notyfikacji.