# Płatności Powtarzalne BLIK w SimPay Adnotacja Jeśli w tekście będzie informacja o *Subskrypcji*, to chodzi o **Płatności Powtarzalne BLIK**. ## Co to są Płatności Powtarzalne BLIK? Płatności Powtarzalne BLIK to mechanizm pozwalający sklepowi lub usługodawcy realizować kolejne obciążenia rachunku użytkownika w ramach uprzednio zaakceptowanej zgody. Po utworzeniu płatności powtarzalnej użytkownik nie musi wpisywać ręcznie kodu BLIK przy każdej kolejnej płatności — kolejne transakcje są inicjowane przez sprzedawcę i realizowane w zależności od wybranego modelu: automatycznie lub po potwierdzeniu w aplikacji bankowej. ## Dlaczego warto korzystać z Płatności Powtarzalnych BLIK? - **Wygoda dla użytkowników** – brak konieczności każdorazowego wpisywania kodu BLIK. - **Wyższa konwersja** – łatwiejszy proces płatności zwiększa szansę na finalizację transakcji. - **Przewidywalność przychodów** – idealne rozwiązanie dla modeli subskrypcyjnych i cyklicznych usług. - **Elastyczność** – możliwość korzystania zarówno w modelach o stałej, jak i zmiennej kwocie. - **Bezpieczeństwo** – płatności są realizowane w oparciu o oficjalny standard BLIK i autoryzację w aplikacji bankowej. - **Kontrola użytkownika** – każda zgoda jest widoczna w aplikacji bankowej i może być w dowolnym momencie odwołana. ## Dostępne modele Płatności Powtarzalne BLIK udostępniają kilka modeli działania — poniżej opisane w ujęciu możliwym do wykorzystania w dokumentacji integracji. ### Model A — stała kwota, pobranie bez dodatkowego potwierdzenia - Przeznaczenie: subsktransakcjarypcje / raty / usługi o stałej kwocie i stałej częstotliwości. - Jak działa: pierwsza wymaga wpisania 6-cyfrowego kodu BLIK i potwierdzenia w aplikacji bankowej; po utworzeniu płatności powtarzalnej kolejne pobrania wykonuje sprzedawca bez dodatkowego potwierdzania przez użytkownika. - Cechy: prostota, przewidywalność dla użytkownika; okres obowiązywania rekurencji może być określony z góry (w praktyce istnieją ograniczenia czasu trwania rekurencji – np. model A bywa limitowany maksymalnym okresem ważności). **Przykład użycia:** miesięczny abonament streamingowy z identyczną opłatą co miesiąc. ### Model M — kwota zmienna, każdorazowe potwierdzenie przez użytkownika - Przeznaczenie: przypadki, gdy wysokość lub termin kolejnych opłat może się zmieniać (rachunki, opłaty o zmiennej wysokości). - Jak działa: pierwsza transakcja inicjuje zgodę (kod BLIK); kolejne transakcje są inicjowane przez sprzedawcę, ale każda z nich wymaga, aby użytkownik potwierdził ją w aplikacji bankowej. - Cechy: większa kontrola użytkownika nad pojedynczymi pobraniami; zgoda może być określona terminowo lub jako bezterminowa (do odwołania). **Przykład użycia:** opłacanie rachunków o zmiennej wysokości lub system darowizn, gdzie kwota może się zmieniać. ### Model O — kwota zmienna, pobranie bez dodatkowego potwierdzenia - Przeznaczenie: przypadki wymagające realizacji płatności o zmiennej kwocie, ale bez konieczności każdorazowego potwierdzenia przez użytkownika. - Jak działa: podobnie do modelu M pod względem zmiennej kwoty i częstotliwości, z tą różnicą, że kolejne obciążenia mogą być pobierane bez interakcji użytkownika (sprzedawca inicjuje pobranie i transakcja jest wykonana bez dodatkowego potwierdzenia w aplikacji banku). - Cechy: łączy elastyczność co do kwoty z wygodą automatycznego pobierania. **Przykład użycia:** usługi, gdzie kwota może się różnić, ale użytkownik wyraził zgodę na automatyczne obciążenia (np. konta rozliczeniowe, niektóre modele subskrypcji z elastycznym rozliczeniem). ## Wymagania BLIK W celach zobaczenia wymagań oraz modeli zachęcamy do przejścia na stronę BLIK ## Częstotliwość subskrypcji Model A wymaga określenia częstotliwości. Model M pozwala na przesłanie, ale nie jest on wymagany. Częstotliwość określa co jaki czas możliwa jest następna Płatność Powtarzalna. Wartość pola częstotliwości dzielimy na 2 bloki: 1. Pierwszy blok określa długość okresu podaną w jednostkach miary określonych polem drugim i zawiera od 1 do 3 znaków, gdzie: - Pierwszy znak z zakresu: [1-9] - Drugi znak z zakresu: [0-9] (opcjonalny, może wystąpić lub nie) - Trzeci znak z zakresu: [0-9] (opcjonalny, może wystąpić lub nie) 1. Drugi blok określa w jednym znaku jednostkę miary okresu płatności: - `D` - dziennie, - `W` – tygodniowo, - `M` - miesięcznie, - `Y` – rocznie. Gdy dzień realizacji Płatności Powtarzalnej przypada na dzień, którego nie ma w danym miesiącu (np. 31 dzień września), Płatność Powtarzalna powinna zostać wysłana ostatniego dnia tego miesiąca (np. 30 września). Dla okresu płatności `M` (miesiąc) rekomendujemy wyznaczenie daty pierwszej płatności `options.​initiationDate` przypadającej w przedziale 1-28 dnia miesiąca, po to, aby uniknąć realizacji Płatności Powtarzalnej w kolejnym okresie płatności (Płatność Powtarzalna może zostać błędnie skierowana do potwierdzenia przez płacącego w aplikacji mobilnej banku). Jeśli częstotliwość zostanie przekroczona, bank wymaga od użytkownika potwierdzenia Płatności Powtarzalnej w aplikacji mobilnej banku. ## Rejestracja subskrypcji przez autoryzację SimPay umożliwia utworzenie pierwszej transakcji tworzącą subskrypcję na kwotę `0 PLN`. W takim przypadku płacący nie zostanie obciążony akceptując Płatność Powtarzalną w aplikacji mobilnej banku. Wystarczy ustawić pole `amount` przy generowaniu transakcji na `0`. Pole `amount` może być ustawione na `0` tylko podczas rejestracji subskrypcji w SimPay. Następne próby obciążenia Płatności Powtarzalnej kwotą 0 zł zakończą się błędem. ## Tworzenie subskrypcji 1. Podczas generowania transakcji należy: - ustawić pole `directChannel` na wartość `blik-recurrent`, - przesłać antifraud.useragent płacącego, - przesłać customer.email płacącego, - przesłać customer.ip płacącego, - przesłać customer.countryCode płacącego (obecnie obsługiwany tylko PL), - ustawić walutę transakcji na PLN (BLIK obecnie wspiera tylko PLN), - musisz przesyłać `antifraud.systemId` - jest to identyfikator płacącego w Twoim systemie (np. ID konta) - ID systemowe musi być unikalne dla pojednczego użytkownika. Jeśli użytkownik posiada kilka subskrypcji, systemId musi być zawsze taki sam. 1. Drugim etapem będzie wysłanie requesta tworzenia Płatności Powtarzalnej. Wymagane opcje według modelu: ### Model A (AUTO): - `options.expiresAt` - data wygaśnięcia subskrypcji. Pole wymagane, maksymalna wartość to +10 lat od chwili obecnej, - `options.frequency` - zobacz wyżej (Częstotliwość subskrypcji), - `options.​amountLimitPerTransaction` - Limit obciążenia kwotowego przez pojednyczą Płatność Powtarzalną (jedną transakcję), - `options.initiationDate` - data pierwszej Płatności Powtarzalnej (pole musi być bezwzględnie przestrzegane) - data, kiedy zostanie wykonane pierwsze obciążenie konta, - `options.amountLimitTotal` - Limit obciążenia kwotowego w całym okresie Subskrypcji, - `options.​transactionsCountLimit` - Pole opcjonalne. Obecnie nie wykorzystywane przez banki. ### Model O (OPEN): - `options.​initiationDate` - Pole opcjonalne. Kiedy przesłane, to data pierwszej Płatności Powtarzalnej (pole musi być bezwzględnie przestrzegane) - data, kiedy zostanie wykonane pierwsze obciążenie konta, - `options.expiresAt` - Pole opcjonalne. Data wygaśnięcia subskrypcji. Pole wymagane, maksymalna wartość to +10 lat od chwili obecnej, ### Model M (MANUAL): - `options.​initiationDate` - Pole opcjonalne. Kiedy przesłane, to data pierwszej Płatności Powtarzalnej (pole musi być bezwzględnie przestrzegane) - data, kiedy zostanie wykonane pierwsze obciążenie konta, - `options.expiresAt` - Pole opcjonalne. Data wygaśnięcia subskrypcji. Pole wymagane, maksymalna wartość to +10 lat od chwili obecnej, - `options.frequency` - Pole opcjonalne. Częstotliwość subskrypcji, W przypadku, kiedy 6-cyfrowy kod BLIK jest błędny zostanie zwrócona odpowiedź analogiczna jak w przypadku BLIK Level 0. Prosimy o zapoznanie się z dokumentacją BLIK Level 0 w celu zapoznana się z działaniem. Kiedy kod BLIK jest prawidłowy zostaną zwrócone 2 parametry: - subscriptionId - ID subskrypcji SimPay, przez to ID będzie możliwe dokonywanie kolejnych obciążeń, - aliasId - ID aliasu SimPay, jego zapisanie nie jest obowiązkowe. **Zwrócenie subscriptionId nie znaczy, że subskrypcja jest już aktywna.** Musisz poczekać na event IPN `subscription:status_changed`. Zostaną również wysłane eventy `transaction_blik_level0:code_status_changed`, `transaction:status_changed` oraz `blik:alias_status_changed`. Jeśli użytkownik nie będzie miał wystarczających środków na koncie, lub wystąpi inny niepożądany błąd po stronie BLIK/płacącego, to będzie to zawarte w komunikacie `transaction_blik_level0:code_status_changed`. Po więcej szczegółów zobacz zakładkę IPN v2. Wysłanie przez SimPay eventu `subscription:status_changed` ze statusem subskrypcji `subscription_active` oznacza aktywację subskrypcji. Od teraz jest możliwe obciążanie płacącego zgodnie z danym Modelem. ## Dokonywanie Płatności Powtarzalnej (Kolejna transakcja w aktywnej subskrypcji) 1. Podczas generowania transakcji należy: - ustawić pole `directChannel` na wartość `blik-recurrent`, - przesłać customer.email płacącego, - przesłać customer.countryCode płacącego (obecnie obsługiwany tylko PL), - ustawić walutę transakcji na PLN (BLIK obecnie wspiera tylko PLN), - musisz przesyłać `antifraud.systemId` - jest to identyfikator płacącego w Twoim systemie (np. ID konta) - ID systemowe musi być unikalne dla pojednczego użytkownika. Jeśli użytkownik posiada kilka subskrypcji, systemId musi być zawsze taki sam. W każdej kolejnej transakcji do danej Płatności Powtarzalnej nie wysyłasz do SimPay adresu IP ani UserAgent. 1. Drugim etapem będzie wysłanie requesta do dokonania Płatności Powtarzalnej. - Jeśli wywołujesz kolejny raz próbę obciążenia za tą samą transakcje to przesyłaj poprawną wartość pola `attempt` - Wartości od 0-9, gdzie 0 jest pierwszą próbą, a każda kolejna wartość musi być większa o 1 od poprzedniej. - Parametr `alias.noDelay` dotyczy się transakcji w modelu A i O. Parametr noDelay = true oznacza, że oczekujesz na niezwłoczną odpowiedź dot. autoryzacji. Jeśli nie zostanie przesłany, autoryzacja Transakcji Powtarzalnej może trwać do 72h. W odpowiedzi zostanie wysłane pole `needsUserConfirmation`. To pole oznacza, czy transakcja została od razu przekazana do BLIK, czy najpierw oczekuje na potwierdzenie transakcji przez płacącego. W takim przypadku na adres e-mail płacącego zostanie wysłana wiadomość. Wartość `true` oznacza, że oczekuje na potwierdzenie transakcji przez płacącego, Wartość `false` oznacza, że Płatność Powtarzalna została wysłana bezpośrednio do BLIK. W sytuacji dokonywania Płatności Powtarzalnej wysłany zostaje tylko 1 event IPN: - `transaction:status_changed` Jeśli status transakcji === `transaction_paid` to płacący został prawidłowo obciążony, a środki trafiają do Ciebie. ## System AntiFraud (przeciwdziałanie wyłudzeniom) SimPay posiada system AntiFraud dla Płatności Powtaralnych. Oparty jest na analizie poprzednich transakcji dokonanych przez płacącego. System obecnie wprowadzony tylko dla modelu O. Jeśli system wykryje nieprawidłowość to płacący dostaje wiadomość e-mail z linkiem do potwierdzenia płatności. Płacący ma 7 dni na potwierdzenie transakcji.