Wymagania Santander (potrzeba biznesowa)
Ze strony Modułu Weryfikacji Dochody wymagane są następujące zmiany:
APIHub powinien wrzucić na kolejkę RabbitMQ event potwierdzający fakt:
zaciągnięcia historii operacji z ostatnich „X” miesięcy dla wszystkich rachunków agregowanych w ramach jednej sesji PSD2 oraz możliwości pobrania powyższych historii w widokach zmaterializowanych dostępnych dla Tribe Risk Engineering (TRE ) - event generowany per sesja PSD2 a nie rachunek.
parametr „X” miesięcy powinien być parametryzowany, wyjściowo przyjmujemy że będzie to 13 miesięcy
event powinien być generowany także dla rachunków dla których historia operacji jest krótsza niż X miesięcy
event powinien zawierać identyfikator pozwalający „dopasować” go do zakończonej po stronie MWD sesji PSD2 (np. CIF klienta + id sesji PSD2? – tutaj wymagane jest jeszcze doszczegółowienie, MWD może mieć problem z dostaniem się do id sesji PSD2)
Dodatkowo, MWD powinien być poinformowany o możliwości pobrania listy rachunków zagregowanych w ramach sesji PSD2 – ApiHUB Core powinien wrzucić na kolejkę RabbitMQ event potwierdzający fakt:
możliwości pobrania listy rachunków agregowanych wraz z saldami w ramach danej sesji PSD2
event powinien zawierać identyfikator pozwalający „dopasować” go do zakończonej po stronie MWD sesji PSD2 ( np. CIF klienta + id sesji PSD2? – tutaj wymagane jest jeszcze doszczegółowienie, MWD może mieć problem z dostaniem się do id sesji PSD2)
Dodatkowe wymagania dotyczące obsługi sesji inicjowanych przez MWD (02.06.2021)
sesje AIS inicjowane przez MWD będą oznaczane z wykorzystaniem dodatkowego identyfikatora kontekstu sesji (session context). Dodatkowy identyfikator zostanie dodany w parametrach wywołania metody authorize jako zmiana opisana w zgłoszeniu https://bankup.atlassian.net/servicedesk/customer/portal/38/SAN-12
Na kolejki MWD wysyłane będą komunikaty jedynie dla sesji oznaczonej przez MWD z wykorzystaniem dedykowanej wartości (string) kontekstu sesji. Zmiana: https://bankup.atlassian.net/servicedesk/customer/portal/38/SAN-13
Zgody wydane w ramach sesji AIS inicjowanych przez MWD obsługiwane są następnie (po zakończeniu sesji zainicjowanej przez MWD) dokładnie tak samo jak wszystkie inne zgody, w szczególności:
dane są widoczne w kanałach
zgoda jest wykorzystywana do odświeżania danych (RAA=true) i to odświeżenie nie powoduje już generowania komunikatów na kolejki MWD
sesje MWD wywoływane powinny być z api-clientId=santander
wykorzystanie wspólnego api-clientId nie pozwala na zwracanie różnej listy ASPSP (lista jest jedna przypisana do api-clientId=santander)
Uwaga:
w przypadku kiedy użytkownik miał aktywną zgodę i rachunki pobrane z banku X i następnie uruchomił proces MWD dla banku X to:
istniejąca zgoda i dane zostaną usunięte (komponent SNT wywołuje delete-consent przed nowym authorize)
jeżeli sesja AIS zakończy się błędem (accounts lub wcześniej) , użytkownik nie zobaczy rachunków z banku X jakie były wcześniej pobrane
jeżeli sesja AIS zakończy się błędem (transactions), użytkownik zobaczy rachunki wybrane w ramach zgody inicjowanej przez MWD ale bez transakcji. Jest też możliwość (tymczasowy błąd po stronie ASPSP) że transakcje zostaną pobrane przy kolejnym odświeżeniu, wtedy jednak MWD już≥ nie dostanie tej informacji (sesja odświeżająca była zainicjowana już nie przez MWD ale przez RAA=true)
Specyfikacja zmiany
modyfikacja zgłoszone 29.04 oznaczone zostały na zielono
Dodane zostaną 3 (4) zdarzenia:
informacja o rozpoczęciu sesji agregacji (po otrzymaniu code po SCA)- nazwa komunikatu AccountsSyncStarted
informacja, że w API dostępne są szczegóły konta do pobrania
informacja, że zakończyła się w danej sesji synchronizacja X miesięcy transakcji i jest dostępna w reporting-service
informacja o zakończeniu sesji i zapisaniu wszystkich danych do RS (zdarzenie do usunięcia)
informacja o wystąpieniu błędu w sesji agregującej. Komunikat ' ProcessFailed', rozbity jest na dwa oddzielne, odpowiadające kolejnym stage sesji:
agregacji kont (AccountsSyncFailed)
agregacja transakcji (TransactionsSyncFailed)
Parametr X parametryzowalny w docker-compose. Parametryzujemy pierwsze zdarzenie liczbą miesięcy możliwą do ustawienia w konfiguracji.
Ograniczamy wyzwalanie tych zdarzeń do zdefiniowanego apiclientid
Komunikaty są wysyłane w kontekście sesji (nie per konto w ramach agregacji)
Santander interpretuje tylko pola:
sessionId
externalSessionId
userId
Inne pola typu numer rachunku/IBAN powinny być ignorowane (stanowią one część standardowego komunikatu)
Potwierdzamy że zaimplementowana logika sprawdzenia długości historii dla zagregowanych rachunków odpowiada specyfikacji przedstawionej przez zespół MWD (poniżej).
Postać zdarzeń
TransactionsSyncFinished:
{
sessionId: "ABC"
sessionExternalId: "XYZ"
userId: "ABC",
noMonths: 13,
}
AccountsSyncFinished:
{
sessionId: "ABC"
userId: "ABC",
sessionExternalId: "XYZ"
}
Na podstawie powyższego przekazana jest informacją, że można pobrać:
listę kont usera ABC w związku z agregacją XYZ
listę transakcji z widoku w związku z agregacją XYZ.
Szczegóły sesji są dostępne poprzez endpoint API /api/v2/bank/session/{sessionId}
Sposób weryfikacji działającego mechanizmu
Przykładowe body dla 1 /authorize na podstawie którego widać, jak przekazywane są wartości.
curl --location --request POST 'https://143-20210226-4-gateway.psd2hub.banqware.com/api/v2/bank/75/authorize' \
--header 'Content-Type: application/json' \
--header 'api-clientId: sandbox' \
--header 'Accept-Language: en-gb' \
--header 'IP: 121.1.0.1' \
--data-raw '{
userId:"regression_AISP_BPKOPLPW_2021-03-02T13:58:32.910Z",
"sessionExternalId": "xxxxxxxxxxxxxxxxxxxxxxxx",
values:[
]
}
Message na kolejce:
{
"messageId": "00290000-ac13-0242-258c-08d8dd83ca7f",
"conversationId": "000e0000-ac18-0242-57ae-08d8dd83ca70",
"sourceAddress": "rabbitmq://node1/143-20210226-4/PushService_SessionUpdated",
"destinationAddress": "rabbitmq://node1/143-20210226-4/reporting",
"messageType": [
"urn:message:Psd2Hub.Services.PushService.Models.Reporting:AccountsSyncFinished"
],
"message": {
"sessionId": "d24b7502-a3f5-4d0d-fd0c-08d8dd7f7b0c",
"sessionExternalId": "xxxxxxxxxxxxxxxxxxxxxxxx",
"userId": "b439960d-f006-4863-9189-f0e8f51dadfa"
},
"sentTime": "2021-03-02T14:02:18.0709772Z",
"headers": {
"ExecutionData": "{\"IgnoreLog\":false,\"ExternalUserId\":null,\"Id\":\"4c6dbd69-0a6d-4625-8734-8c31857c5222\",\"LogId\":\"74a5204a-1881-413c-b877-ec845e0cdd73\",\"TenantId\":null,\"IsMultitenancyMode\":false,\"Invoker\":12,\"Context\":{\"UserId\":\"regression_AISP_BPKOPLPW_2021-03-02T13:58:32.910Z\",\"ConsentId\":\"277086b7-675e-4763-a378-88ea4f5c6020\",\"AccountId\":\"PL61000123450000000009040575\",\"PaymentId\":null,\"SessionId\":\"d24b7502-a3f5-4d0d-fd0c-08d8dd7f7b0c\"},\"ExtraData\":null,\"BuildId\":\"40962\"}",
"Execution-Id": "4c6dbd69-0a6d-4625-8734-8c31857c5222"
},
"host": {
"machineName": "7e81564d75c2",
"processName": "Psd2Hub.Services.PushService.Api",
"processId": 1,
"assembly": "Psd2Hub.Services.PushService.Api",
"assemblyVersion": "1.0.0.0",
"frameworkVersion": "3.1.12",
"massTransitVersion": "6.3.2.0",
"operatingSystemVersion": "Unix 3.10.0.1127"
}
}
Instalacja - czynności administracyjne
Stworzenie Queue (PL: „kolejka") w zakładce Queues.
Parametry:
Virtual host: [należy wybrać środowisko, z dostępnej listy]
Name: reporting
Durability: Durable
Node: [node 1]
Reszta ustawień defaultowa
Stworzenie Exchange (PL: „centrala wiadomości") w zakładce Exchanges.
Parametry:
Virtual host: [należy wybrać środowisko, z dostępnej listy]
Name: reporting
Type: fanout
Durability: Durable
Reszta ustawień defaultowa
Binding exchange i queue
W sekcji „Add binding from this exchange" wybrać opcję 'to queue', wpisać nazwę kolejki „reporting", a następnie kliknąć przycisk „Bind". W rezultacie powinien pojawić wpis w sekcji Bindings (na rysunku zaznaczone na żółto).
Wynik:
Dodatkowe uwagi/doprecyzowania wymagań od zespołu MWD
Mechanizm generowania przez APIHUB komunikatów na kolejki RabbitMQ na potrzeby Modułu Weryfikacji Dochodu – wymagania i wyniki testów*SNT powinien korzystać z 3 pól:
sessionId
externalSessionId
userId
Dodatkowe pola to metadata (std. mechanizm) na który nie powinien Bank patrzeć
Nie powinien być wysyłany jeden komunikat 2 razy
Wszystko idzie w kontekście sesji
Nie są generowane informacje o sesji failed.
Tło biznesowe
Komponent RETAILCASES_MWD wywoływany z poziomu wniosku o produkt kredytowy może m.in. zainicjować zmiany w agregacjach kont, którymi mogą być następujące ścieżki:
[dodaj bank] wywołanie BZWBK24_API_PS_AGGREGATOR w kontekście nowa agregacja (new-consent w rozumieniu APIHUB) – gdzie klient nie ma zagregowanego żadnego konta z danego banku
[dodaj kolejne konto] wywołanie BZWBK24_API_PS_AGGREGATOR w kontekście edycji istniejącej agregacji w konkretnym banku (zmiana konfiguracji kont rozumiana przez APIHUB jako delete-consent i new-consent wywołane sekwencyjnie po sobie z użyciem jednego unikalnego "sessionExternalId" prowadząca do zmiany liczby kont w konkretnym banku) - z poziomu MWD użytkownik przechodzi do ekranu zgód w agregatorze później do wybranego banku,
[odśwież zgodę] wywołanie BZWBK24_API_PS_AGGREGATOR w kontekście odświeżenie 90-dniowej zgody w konkretnym banku (rozumiane przez APIHUB jako operacja na istniejącej zgodzie mająca na celu wydłużenie jej daty ważności lub liczby kont w danym banku) - z poziomu MWD użytkownik przechodzi do wybranego banku
Wszystkie te zmiany skutkują widocznością wprowadzonych zmian również z poziomu bankowości internetowej SAN (BZWBK24_PS_AGGREGATOR).
Celem nadrzędnym MWD jest pozyskanie z banków zewnętrznych historii transakcji kont pozwalających na wyznaczenie na ich podstawie estymowanego dochodu przez mechanizmy silnika decyzyjnego SAN.
MWD po zainicjowaniu zmian w agregacjach (wykonywanych za pośrednictwem komponentu OMNI BZWBK24_API_PS_AGGREGATOR) potrzebuje zatem informacji o statusie kolejnych kroków procesu realizacji tych zmian bezpośrednio z APIHUB. Celem biznesowym jest pozyskanie informacji, czy efektem zainicjowanych zmian jest spłynięcie do widoków udostępnionych przez Reporting Services długości historii pozwalającej na wyznaczenie estymowanego dochodu.
Oprócz tego MWD wymaga dodatkowej informacji o wystąpieniu błędów podczas procesu agregacji bezpośrednio z APIHUB.
Szczegółowe wymagania
MWD otrzymuje od BZWBK24_API_PS_AGGREGATOR (komponent bankowości elektronicznej) wartość "sessionExternalId", która oznacza dla niego sesję biznesową, w ramach której wykonywany jest konkretny proces zmian w agregacji (new-consent, edit-consent, renewal-consent inicjowany w ramach BZWBK24_PS_AGGREGATOR) dla wielu kont. MWD nie zna liczby zmienianych kont, posiada tylko ten id sesji. Wszystkie komunikaty powinny być więc produkowane przez APIHUB per "sessionExternalId" w kontekście danego banku. Znaczy to, że przykładowo dla wykonywanej w jednej sesji agregacji 3 kont w banku X na kolejce powinien pojawić się jeden komunikat generowany wtedy, gdy agregacja wszystkich trzech kont się zakończyła.
Rysunek 1 Diagram sekwencji generowania komunikatów
2. MWD potrzebuje 4 rodzajów komunikatów z APIHUB na kolejce RMQ-APIHUB, informujących o:
a) starcie procesu realizacji zmian w agregacji [Rysunek 1 - AccountsSyncStarted]:
komunikat dotyczy 3 typów zmian w obszarze agregacji rozumianych przez APIHUB:
nowa agregacja (new-consent),
edycja agregacji (zmiana konfiguracji kont rozumiana przez APIHUB jako delete-consent i new-consent wywołane sekwencyjnie po sobie z użyciem jednego "sessionExternalId"),
edycja agregacji w celu wydłużenia jej aktywności
pozwala MWD na identyfikację sytuacji, że przekierowanie do Banku zewnętrznego w celu realizacji zmian w agregacjach zakończyło się interakcją z API HUB
w treści komunikatu oprócz jego typu konieczne zawarcie:
"sessionExternalId",
komunikat powinien być generowany w momencie powrotu klienta z ASPSP do aplikacji bankowości elektronicznej (BZWBK24_API_PS_AGGREGATOR) co skutkuje rozpoczęciem pobierania danych związanych z kontami wraz z transakcjami dla klienta w ramach udzielonej zgody.
b) zaciągnięcie informacji o rachunkach z banku zewnętrznego - [Rysunek 1 - AccountsSyncFinished]:
komunikat dotyczy 3 typów zmian w obszarze agregacji rozumianych przez APIHUB:
nowa agregacja (new-consent),
edycja agregacji (zmiana konfiguracji kont rozumiana przez APIHUB jako delete-consent i new-consent wywołane sekwencyjnie po sobie z użyciem jednego "sessionExternalId"),
edycja agregacji w celu wydłużenia jej aktywności
w treści komunikatu oprócz jego typu konieczne zawarcie:
"sessionExternalId",
numery IBAN wszystkich kont, które były agregowane w ramach danej sesji (tylko do celów audytowych, nice to have)
komunikat pojawia się po pobraniu wszystkich kont z pojedynczej agregacji dla danego sessionExternalId
c) pozyskaniu z banku obcego transakcji dla wszystkich kont za ostatnie X miesięcy lub krótszej historii w przypadku braku wystarczającej historii [Rysunek 1 - TransactionsSyncFinished]:
komunikat dotyczy 3 typów zmian w obszarze agregacji rozumianych przez APIHUB:
nowa agregacja (new-consent),
edycja agregacji (zmiana konfiguracji kont rozumiana przez APIHUB jako delete-consent i new-consent wywołane sekwencyjnie po sobie z użyciem jednego "sessionExternalId"),
edycja agregacji w celu wydłużenia jej aktywności
pozwala MWD na identyfikację sytuacji, że w trakcie trwającej synchronizacji transakcji z banku obcego dla wszystkich kont została pobrana historia z X miesięcy (X – parametr systemowy APIHUB) i historia ta jest dostępna w Reporting Services,
jeżeli dla zbioru kont (pod jednym "sessionExternalId") przynajmniej jedno konto nie zawiera historii transakcji dłuższej lub równej oczekiwany okres, komunikat jest generowany w momencie zaciągnięcia całej dostępnej historii (dotyczy wszystkich kont) – Rysunek 2
w treści komunikatu oprócz jego typu konieczne zawarcie:
"sessionExternalId"
Rysunek 2 Logika sprawdzenia długości historii dla zagregowanych rachunków
Rysunek 2 Logika sprawdzenia długości historii dla zagregowanych rachunków
d) wystąpieniu błędu w procesie agregacji lub synchronizacji danych [Rysunek 3 - AccountsSyncFailed/TransactionsSyncFailed ]:
AccountsSyncFailed - informujący o błędzie podczas procesu pobierania danych o kontach
TransactionsSyncFailed - informujący o błędzie podczas pobieranie trnasakcji
komunikat dotyczy 3 typów zmian w obszarze agregacji rozumianych przez APIHUB:
nowa agregacja (new-consent),
edycja agregacji (zmiana konfiguracji kont rozumiana przez APIHUB jako delete-consent i new-consent wywołane sekwencyjnie po sobie z użyciem jednego "sessionExternalId"),
edycja agregacji w celu wydłużenia jej aktywności
pozwala MWD na identyfikację sytuacji, gdzie w APIHUB wystąpił błąd na dowolnym etapie procesu agregacji lub synchronizacji kont w ramach danego "sessionExternalId",
w treści komunikatu oprócz jego typu konieczne zawarcie:
"sessionExternalId"
Rysunek 3 Diagram sekwencji generowania komunikatów o błędzie
Przykładowe komunikaty
Komunikat MWD Expand source
Powyższy format komunikatu będzie identyczny dla wszystkich komunikatów wystawianych do MWD.
Zmienna będzie część:
TransactionsSyncFinished:
{
sessionId: "ABC"
sessionExternalId: "XYZ"
userId: "ABC",
noMonths: 13,
}
AccountsSyncFinished:
{
sessionId: "ABC"
userId: "ABC",
sessionExternalId: "XYZ"
}
SyncFinished:
{
sessionId: "ABC"
userId: "ABC",
sessionExternalId: "XYZ"
}
AccountSyncStarted:
{
sessionId: "ABC"
sessionExternalId: "XYZ"
userId: "ABC"
}
TransactionsSyncFailed:
{
sessionId: "ABC"
sessionExternalId: "XYZ"
userId: "ABC"
}
AccountsSyncFailed:
{
sessionId: "ABC"
userId: "ABC",
sessionExternalId: "XYZ"
}