API Walidacja Kodów BIC / SWIFT

Jak zintegrować API Walidacji BIC w swoim oprogramowaniu

1. Czym jest API Walidacji BIC?

Przy przetwarzaniu przelewów oraz obsłudze transakcji związanych z IBAN, zapewnienie prawidłowego kodu SWIFT/BIC ma kluczowe znaczenie aby płatność przebiegła pomyślnie.
Nasza firma licencjonowała oficjalny katalog BIC z S.W.I.F.T SCRL w celu zapewnienia potężnego i prostego sposoby automatycznego sprawdzania BIC. Ta usługa umożliwia integrację wyszukiwania katalogów z kodami BIC w Twoim oprogramowaniu w celach wewnętrznych

API Walidacji BIC posiada SWIFTRef Data Inside. Dane BIC użyte wraz z zgodą S.W.I.F.T. SCRL. Prawa do bazy danych zastrzeżone 2019

2. Cechy

API Walidacji BIC główne cechy:

  • Pobieraj informacje o banku na podstawie BIC.
  • Przeszukuj katalog BIC wpisując tylko część nazwy w celu uzyskania pełnej nazwy banku oraz kraju.
  • Przeszukuj katalog BIC w poszukiwaniu historycznych zapisów.
  • Używaj zarówno uzupełnionej, jak i uproszczonej odpowiedzi API w celu łatwiejszej integracji.


3. Użycie API

API Walidacji BIC jest oparty na REST i obsługuje proste zapytania HTTP GET lub POST.

Akceptowalne parametry są wymienione w poniższej tabeli:

Nazwa Pola Długość Typ Opis
bic 11 String Kod BIC / SWIFT do wyszukania. Może miec 8 lub 11 znaków
bank_name 256 String Część nazwy bank aby wykonać wyszukanie w katalogu BIC.
country 2 String Dwuliterowy kod kraju. Wymagany w celu wyszukania nazwy banku.
api_key 128 String Twój indywidualny klucz API.
format 4 String Wymagane do określenia formatu zwracanych danych. Aktualnie obsługiwane wartości: json, xml
limit Integer Opcjonalne: może być użyte w celu ograniczenia liczby wyników otrzymanych podczas wyszukiwania po nazwie banku.
hist integer Opcjonalne: może być użyte w celu wyświetlenia historycznych wpisów z bazy zarówno dla wyszukań banku jak i BIC.
Na swoim Portalu Internetowym możesz znaleźć indywidualny klucz API i URL żądania punktu końcowego, który jest używany do zapezpieczenia wyników wyszukiwania.


4. Struktura Odpowiedzi API XML

Możesz pobrać XSD Schema odpowiedzi API.
Szczegółowy opis zwracanych pól można zobaczyć w poniższej tabeli:

Nazwa Pola Typ Długość Zawsze obecny Opis
MODIFICATION FLAG Alfabetycznie 1 Tak W plikach delta:
• A (dodanie)
• M (modyfikacja)
• D (usunięcie) w pełnych plikach W pełnych plikach:
• A (dodanie)
CHANGED FIELD Numeryczne 186 Nie Zapiuje pole (albo TAG) które się zmieniło ze względu na modyfikacje wpisu lub z powodu nowego EVENT.
Jedna lub więcej kolumn jest oznaczonych jako ciąg liczb, przy czym każda liczba reprezentująca kolumnę została zmieniona w stosunku do poprzedniej instancji rekordu lub poprzedniego EVENT.
Przykładowo "6,7,8,9"
To oznacza, że EVENT TYPE, EVENT DATE, BIC8, i BRANCH BIC
uległy zmianie.
Poniższe FIELDS zostały wykluczone z zapisywania w CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alfanumerycznie 12 Tak Unikalny klucz wpisu w pliku
Każdy wpis reprezentuje wydarzenie w cyklu życia BIC.
Raz przypisany, RECORD KEY nigdy się nie zmienia.
PREVIOUS RECORD KEY Alfanumerycznie 12 Nie RECORD KEY poprzednio powiązanego EVENT
Wszystkie powiązane zdarzenia są połączone i można je zlokalizować za pomocą tych informacji.
NEXT RECORD KEY Alfanumerycznie 12 Nie RECORD KEY następnego połączonego wydarzenia
Wszystkie powiązane zdarzenia są połączone i można je zlokalizować za pomocą tych informacji.
EVENT TYPE Alfabetycznie 32 Tak EVENT lub zmiana opisu powiązana z BIC która miała miejsce w przeszłości, teraźniejszości, lub będzie miała miejsce w przyszłości.
Typy wydarzeń (Event):
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
Ostatnia aktualizacja danych jest ostatnią lilnijka w sekwencji BIC (chodzi o ostatni wpis).
Kiedy nowy EVENT jest dodany, kolumna MODIFICATION FLAG oraz CHANGED
FIELD zostanie zaktualizowana w bezpośrednim poprzednim powiązanym EVENT.
EVENT DATE Alfanumerycznie 8 Tak Data EVENT
BIC8 Alfanumerycznie 8 Yes BIC (instytucja, kraj i przyrostek strony), gdzie:
• Przedrostek grupy (4 znaki)
• Kod kraju (2 znaki)
• Przyrostek grupy (2 znaki)
BRANCH BIC Alfanumerycznie 3 Tak Identyfikator Oddziału BIC powiązany z 8-znakowym BIC. Jeśli nie istnieje identyfikator oddziału, wtedy użyty jest XXX.
BIC Alfanumerycznie 11 Tak Pełny BIC: 8-znakowy BIC oraz identyfikator oddziału
RECORD STATUS Alfabetycznie 1 Tak Wskazuje status wpisu:
• [A] = Aktualnie przedstawiający ostatnie wydarzenie w serii, aż do daty opublikowania, wyłączając [P]rzyszłe wydarzenia
• [H] = Historyczne wpisy w serii wydarzeń
• [P] = Przyszłe wydarzenia które będa miały miejsce po dacie publikacji katalogu. Wczesniej wskazane [A]ktualne wydarzenie będzie ważne aż do daty wsazanej w [P]rzyszłym wydarzeniu
Dla wydarzeń FUTURE, data wskazuje od kiedy zmiana będzie VALID FROM.
OPERATIONALLY ACTIVE RECORD Alpha 1 Tak Istnieje wiele wpisów dla tego samego BIC. To pole wskazuje które wpisy do tego samego BIC są funkcjonująca aktywne BIC i powinny być użyte.
• [Y] Funkcjonująco Aktywny
• [N] Funkcjonująco Nieaktywny
Dla każdego unikalnego BIC, jest jeden wpis rekordu wskazujący na status ACTIVE (Y).
Wpisy z statusem [H]istoryczne będą zawsze wskazywały [N].
Wpisy z [A]ktualne mogą wskazywać [Y] lub [N].
Wpisy z [P] zawsze będą wskazywać [N].
SUBTYPE INDICATOR Każdy typ 4 Tak Rodzaj działalności podmiotu. Wskaźnik Podtypu jest dostarczany tylko dla rekordów z BIC.
SWIFT FIN Alfabetycznie 1 Tak Status połączenia podmiotu z FIN:
• [Y] połączony z FIN
• [N] niepołączony z FIN
SWIFT FA Alfabetycznie 1 Tak Status osiągalności podmiotu poprzez FileAct:
• [Y] połączony z FileAct
• [N] niepołączony z FileAct
SWIFT IA Alpha 1 Tak Status osiągalności podmiotu poprzez InterAct:
• [Y] połączony z InterAct
• [N] niepołączony z InterAct
LEGAL NAME Dowolna 105 Nie Nazwa prawna instytucji
INSTITUTION NAME Dowolna 105 Tak Nazwa handlowa instytucji (opublikowana nazwa)
INSTITUTION TYPE Alfabetycznie 12 Tak Organizacja, która zajmuje się głównie pośrednictwem finansowym i/lub pomocniczą działalnością finansową
Typ instytucji:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Alfabetycznie 16 Tak Określa typ podmiotu finansowego:
• Podmiot prawny
• Oddział
• Funkcjonujący
RE STREET ADDRESS 1 Dowolna 35 Nie [Rejestracja] Nazwa ulicy
RE STREET ADDRESS 2 Dowolna 35 Nie [Rejestracja] Numer ulicy
RE STREET ADDRESS 3 Dowolna 35 Nie [Rejestracja] Budynek, nazwa budynku, piętro
RE STREET ADDRESS 4 Dowolna 35 Nie [Rejestracja] Rejon
RE CITY Dowolna 35 Nie [Rejestracja] Nazwa miasta instytucji/oddziału
RE CPS Dowolna 90 Nie [Rejestracja] Powiat, prowincja, stan lub inny region administracyjny instytucji/oddziału właściciela
RE ZIP CODE Dowolna 15 Nie [Rejestracja] Kod pocztowy instytucji/oddziału
RE POB NUMBER Dowolna 35 Nie Pole rozdzielone przecinkami z numerem POB instytucji/oddziału i powiązanym kodem pocztowym.
Przykład
"POB 103352, 40024"
To pozwala klientom użyć pełnego adresu POB:
POB 103352
40024, DUESSELDORF (MIASTO)
OP STREET ADDRESS 1 Dowolna 35 Nie [Funkcjonujący] Nazwa ulicy
OP STREET ADDRESS 2 Dowolna 35 Nie [Funkcjonujący] Numer ulicy
OP STREET ADDRESS 3 Dowolna 35 Nie [Funkcjonujący] Budynek, nazwa budynku, piętro
OP STREET ADDRESS 4 Dowolna 35 No [Funkcjonujący] Rejon
OP CITY Dowolna 35 Nie [Funkcjonujący] Nazwa miasta instytucji/oddziału
OP CPS Dowolna 90 Nie [Funkcjonujący] Powiat, prowincja, stan lub inny region administracyjny właściciela instytucji/oddziału
OP ZIP CODE Dowolna 15 Nie [Funkcjonujący] Kod pocztowy instytucji/oddziału
OP POB NUMBER Dowolna 35 Nie Pole rozdzielone przecinkami z numerem POB instytucji/oddziału i powiązanym kodem pocztowym.
Example
"POB 103352, 40024"
To pozwala klientom użyć pełnego adresu POB:
POB 103352
40024, DUESSELDORF (MIASTO)
BR STREET ADDRESS 1 Dowolna 35 Nie [Oddział] Nazwa ulicy
BR STREET ADDRESS 2 Dowolna 35 Nie [Oddział] Numer ulicy
BR STREET ADDRESS 3 Dowolna 35 Nie [Oddział] Budynek, nazwa budynku, piętro
BR STREET ADDRESS 4 Dowolna 35 Nie [Oddział] Rejon
BR CITY Dowolna 35 Nie [Oddział] Nazwa miasta instytucji/oddziału
BR CPS Dowolna 90 Nie [Oddział] Powiat, prowincja, stan lub inny region administracyjny właściciela instytucji/oddziału
BR ZIP CODE Dowolna 15 Nie [Oddział] Kod pocztowy instytucji/oddziału
BR POB NUMBER Dowolna 35 Nie Pole rozdzielone przecinkami z numerem POB instytucji/oddziału i powiązanym kodem pocztowym.
Przykład
"POB 103352, 40024"
To pozwala klientom użyć pełnego adresu POB:
POB 103352
40024, DUESSELDORF (MIASTO)
BRANCH INFORMATION Dowolna 70 Nie Informacje Oddziału
Jest to bezpłatny opis tekstowy oddziału dostarczony przez instytucję finansową, do której należy. Na razie będzie to możliwe tylko w przypadku wpisów z BIC i tylko wtedy, gdy dana instytucja finansowa chce przekazać dodatkowe informacje. Informacje pochodzą z katalogu BIC.
COUNTRY NAME Dowolna 70 Tak Nazwa kraju instytucji/ oddziału zgodnie z tym co wskazano w ISO 3166
ISO COUNTRY CODE Alfabetycznie 2 Tak Kod ISO 3166-1 alfa-2 kraju instytucji/oddziału
LOCATION CODE Każdy typ 1 Yes Zawiera lokalizację (formalnie na pozycji 7 standardu BIC:2009)
Przykładowo:
• W FR, BIC w Paryżu = P
• W BE, BIC w Brukseli = B
• W US, BIC w Wschodnim Wybrzeżu = 3
FIN SERVICE CODES Każdy typ 60 Nie Kody Serwisowe FIN (również zwane udoskonalonymi kodami serwisowymi). Kody Serwisowe są zapewniane tylko dla wpisów zawierających BIC.
To pole może zawierać aż do 20 trzy-znakowych kodów w kolejności alfabetycznej.
RECORD KEY BDP Alfanumerycznie 12 Nie Ten unikalny klucz do wpisu Bank Directory Plus w pliku.
FIELD A Dowolna 1 Nie Zarezerwowane do przyszłego użytku
FIELD B Dowolna 64 Nie Zarezerwowane do przyszłego użytku
FIELD C Dowolna 128 Nie Zarezerwowane do przyszłego użytku
FIELD D Dowolna 256 Nie Zarezerwowane do przyszłego użytku
FIELD E Dowolna 11 Nie Zarezerwowane do przyszłego użytku
FIELD F Dowolna 12 Nie Zarezerwowane do przyszłego użytku
System API zwraca wyniki w formacie XML, który można łatwo analizować w różnych językach programowania i na różnych platformach.

Przykładowa odpowiedź XML od API dla wyszukania BIC będzie wyglądać następująco:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. Błędy API

W przypadku błędu, API zwraca odpowiedź XML zawierającą wiadomość z blędem.

Tagi XML są zwracane bez żadnych innych poł zawartych w odpowiedzi XML.

Poniżej możesz znaleźć opis wszystkich możliwych wiadomości o błędach, które mogą być zwrócone:

Status Kodu Typ Opis
301 Błąd Konta Klucz API jest niewłaściwy
302 Błąd Konta Subskrypcja wygasła
303 Błąd Konta Brak dostępnych zapytań
304 Błąd Konta Nie masz dostępu do tego API
401 Błąd Wprowadzania Akceptowany SWIFT o długości 8 lub 11 znaków'
402 Błąd Wprowadzania Nieprawidłowa Nazwa Banku! Przy Wyszukiwaniu Banku należy wprowadzić minimum 4 znaki.
Dopuszczalne znaki a-z, A-Z, 0-9, [spacja]!
403 Błąd Wprowadzania Kod Kraju nieprawidłowy! Dopuszczalny jest 2 literowy kod kraju. Przykład: UK, DE, FR