BIC / SWIFT kodo patvirtinimo API

Kaip integruoti BIC patvirtinimo API į savo programinę įrangą

1. Kas yra BIC patvirtinimo API?

Kuomet apdorojami mokėjimai ir tvarkomi su IBAN susiję sandoriai, sėkmingiems mokėjimams būtinas SWIFT / BIC kodas.
Mūsų įmonė licencijavo oficialų BIC katalogą iš S.W.I.F.T SCRL, kad galėtumėte pateikti galingą ir paprastą būdą automatiškai patvirtinti BIC. Ši paslauga leidžia integruoti BIC kodų katalogo paiešką jūsų programinėje įrangoje vidaus tikslams

BIC patvirtinimo API turi SWIFTRef duomenis. BIC duomenys naudojami su S.W.I.F.T. SCRL leidimu. Duomenų bazės teisės saugomos 2019

2. Funkcijos

BIC patvirtinimo API pagrindinės funkcijos:

  • Grąžinti informaciją apie banką pagal BIC.
  • Ieškoti BIC kataloge pagal banko pavadinimą ir šalį.
  • Ieškoti istorinių įrašų BIC kataloge.
  • Lengvesniai integracijai, naudokite tiek pilną, tiek supaprastintą API atsaką.


3. API naudojimas

BIC patvirtinimo API yra REST pagrįsta ir palaiko paprastas HTTP GET arba POST užklausas.

Priimtini parametrai pateikiami toliau esančioje lentelėje:

Pavadinimas Ilgis Tipas Aprašymas
bic 11 String BIC / SWIFT kodas paieškai. Gali būti 8 arba 11 simbolių
bank_name 256 String Banko pavadinimo dalis, skirta atlikti paiešką BIC kataloge.
country 2 String Dviejų raidžių šalies kodas. Reikalinga ieškant pagal banko pavadinimą.
api_key 128 String Jūsų asmeninis API raktas.
format 4 String Būtina nurodyti grąžintų duomenų formatą. Šiuo metu palaikomos vertės: json, xml
limit Integer Neprivaloma: galima naudoti norint apriboti rezultatų skaičių ieškant pagal banko pavadinimą.
hist integer Neprivaloma: galima naudoti, kad būtų rodomi istoriniai įrašai iš duomenų bazės tiek banko, tiek BIC paieškai.
Jūsų internetiniame portale galite rasti API raktą ir užklausos pabaigos URL, kuris naudojamas apsaugoti paieškos užklausas.


4. API XML atsako struktūra

Galite atsisiųsti API atsako XSD schemą.
Išsamus grąžintų laukų aprašymas pateikiamas toliau esančioje lentelėje:

Pavadinimas Tipas Ilgis Ar visada egzistuoja Aprašymas
MODIFICATION FLAG Alfabetinis 1 Taip Delta failuose:
• A (papildymas)
• M (modifikacija)
• D (ištrynimas) pilnuose failuose Pilnuose failuose:
• A (papildymas)
CHANGED FIELD Skaitmeninis 186 Ne Įrašo lauką (arba TAG), kuris pasikeitė dėl įrašo pakeitimo ar naujo EVENT.
Vienas ar daugiau stulpelių nurodomi kaip eilių seka, kiekvienas skaičius nurodo stulpelį, kuriame kažkas pakito lyginant su ankstesniu įrašu ar ankstesniu EVENT.
Pavyzdys: "6,7,8,9"
Tai reiškia, kad EVENT TYPE, EVENT DATE, BIC8 ir BRANCH BIC
pakito.
Šie FIELDS neįtraukiami į CHANGED FIELD įrašą:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Raidinis skaitmeninis 12 Taip Unikalus failo įrašo raktas
Kiekvienas įrašas atspindi BIC gyvavimo ciklo įvykį.
Paskyrus RECORD KEY, jis niekada nepasikeis
PREVIOUS RECORD KEY Raidinis skaitmeninis 12 Ne Ankstesnio susieto EVENT RECORD KEY
Visi susiję įvykiai yra sujungti ir gali būti rasti naudojant šią informaciją.
NEXT RECORD KEY Raidinis skaitmeninis 12 Ne Kito susijusio įvykio RECORD KEY
Visi susiję įvykiai yra sujungti ir gali būti rasti naudojant šią informaciją
EVENT TYPE Alfabetinis 32 Taip EVENT arba keitimo aprašymas, susijęs su BIC, kuris įvyko praeityje, dabartyje ar ateityje.
Įvykių tipai:
• 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
Paskutinė atnaujinimo data yra paskutinė BIC sekos eilutė (t.y. naujausias įrašas).
Įtraukus naują EVENT, stulpelis MODIFICATION FLAG ir CHANGED
FIELD bus atnaujintas artimiausiame susijusiame EVENT.
EVENT DATE Raidinis skaitmeninis 8 Taip EVENT data
BIC8 Raidinis skaitmeninis 8 Taip BIC (institucija, šalis ir šalies priesaga), kur:
• Šalies prefiksas (4 char)
• Šalies kodas (2 char)
• Šalies priesaga (2 char)
BRANCH BIC Raidinis skaitmeninis 3 Taip BIC filialo identifikatorius, susijęs su 8 simbolių BIC. Jei nėra filialo identifikatoriaus, naudojama XXX.
BIC Raidinis skaitmeninis 11 Taip Visas BIC: 8 simbolių BIC ir filialo identifikatorius
RECORD STATUS Alfabetinis 1 Taip Nurodo įrašo būseną:
• [C] = Dabartinė dalis, kurioje yra naujausias grandinės įvykis iki paskelbimo datos, Neįskaitant [F] (ateities) įvykių
• [H] = Istoriniai įrašai įvykių grandinėje
• [F] = Būsimas įvykis, kuris įvyks po katalogo paskelbimo datos. Anksčiau nurodytas [C] (dabartinis) įvykis galios iki [F] (ateities) įvykio datos.
FUTURE įvykiams, data nurodo kada pasikeitimas bus VALID FROM.
OPERATIONALLY ACTIVE RECORD Alfa 1 Taip Yra keletas to paties BIC įrašų. Šiame lauke nurodoma, kuris iš tų pačių BIC įrašų yra aktyviai veikiantis BIC ir turėtų būti naudojamas.
• [Y] Veikia aktyviai
• [N] Veikia neaktyviai
Kiekvienam unikaliam BIC yra vienas įrašas, esantis ACTIVE (Y).
Įrašai su [H] (istorine) būsena visada bus [N].
Įrašai su [C] (dabartine) būsena gali būti [Y] arba [N].
Įrašai su [F] (ateities) būsena visada bus [N].
SUBTYPE INDICATOR Bet kokio tipo 4 Taip Įmonės verslo tipas. Potipio rodiklis pateikiamas tik įrašams su BIC.
SWIFT FIN Alfabetinis 1 Taip Įmonės prisijungimo prie FIN statusas:
• [Y] prijungtas prie FIN
• [N] neprijungtas prie FIN
SWIFT FA Alfabetinis 1 Taip Subjekto pasiekiamumo per FileAct būsena:
• [Y] prijungtas prie FileAct
• [N] neprijungtas prie FileAct
SWIFT IA Alfa 1 Taip Subjekto pasiekiamumo per InterAct būsena:
• [Y] prijungtas prie InterAct
• [N] neprijungtas prie InterAct
LEGAL NAME Bet koks 105 Ne Institucijos juridinis pavadinimas
INSTITUTION NAME Bet koks 105 Taip Institucijos prekybos pavadinimas (paskelbtas pavadinimas)
INSTITUTION TYPE Alfabetinis 12 Taip Organizacija, kuri daugiausia užsiima finansiniu tarpininkavimu ir (arba) pagalbine finansine veikla
Institucijos tipas:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Alfabetinis 16 Taip Nurodo finansinio subjekto tipą:
• Juridinis asmuo
• Filialas
• Eksploatacinis
RE STREET ADDRESS 1 Bet koks 35 Ne [Registracija] Gatvės pavadinimas
RE STREET ADDRESS 2 Bet koks 35 Ne [Registracija] Gatvės numeris
RE STREET ADDRESS 3 Bet koks 35 Ne [Registracija] Pastatas, pastato pavadinimas, aukštas
RE STREET ADDRESS 4 Bet koks 35 Ne [Registration] Rajonas
RE CITY Bet koks 35 Ne [Registracija] Institucijos/filialo miesto pavadinimas
RE CPS Bet koks 90 Ne [Registracija] Apygarda, provincija, valstija ar kitas administravimo regionas savininko institucijoje/filiale
RE ZIP CODE Bet koks 15 Ne [Registracija] Institucijos/filialo pašto kodas
RE POB NUMBER Bet koks 35 Ne Laukas, kuriame duomenys atskiriami kableliais, su įstaigos/filialo POB numeriu ir susijusiu pašto kodu.
Pavyzdys:
"POB 103352, 40024"
Tai leidžia klientams naudoti visą POB adresą:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 Bet koks 35 Ne [Veikia] Gatvės pavadinimas
OP STREET ADDRESS 2 Bet koks 35 Ne [Veikia] Gatvės numeris
OP STREET ADDRESS 3 Bet koks 35 Ne [Veikia] Pastatas, pastato pavadinimas, aukštas
OP STREET ADDRESS 4 Bet koks 35 Ne [Veikia] Rajonas
OP CITY Bet koks 35 Ne [Veikia] Institucijos/filialo miesto pavadinimas
OP CPS Bet koks 90 Ne [Veikia] Apygarda, provincija, valstija ar kitas administravimo regionas savininko institucijoje/filiale
OP ZIP CODE Bet koks 15 Ne [Veikia] Institucijos/filialo pašto kodas
OP POB NUMBER Bet koks 35 Ne Laukas, kuriame duomenys atskiriami kableliais, su įstaigos/filialo POB numeriu ir susijusiu pašto kodu.
Pavyzdys:
"POB 103352, 40024"
Tai leidžia klientams naudoti visą POB adresą:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Bet koks 35 Ne [Filialas] Gatvės pavadinimas
BR STREET ADDRESS 2 Bet koks 35 Ne [Filialas] Gatvės numeris
BR STREET ADDRESS 3 Bet koks 35 Ne [Filialas] Pastatas, pastato pavadinimas, aukštas
BR STREET ADDRESS 4 Bet koks 35 Ne [Filialas] Rajonas
BR CITY Bet koks 35 Ne [Filialas] Institucijos/filialo miesto pavadinimas
BR CPS Bet koks 90 Ne [Filialas] Apygarda, provincija, valstija ar kitas administravimo regionas savininko institucijoje/filiale
BR ZIP CODE Bet koks 15 Ne [Filialas] Institucijos/filialo pašto kodas
BR POB NUMBER Bet koks 35 Ne Laukas, kuriame duomenys atskiriami kableliais, su įstaigos/filialo POB numeriu ir susijusiu pašto kodu.
Pavyzdys:
"POB 103352, 40024"
Tai leidžia klientams naudoti visą POB adresą:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Bet koks 70 Ne Filialo informacija
Tai laisvas filialo aprašymas, kurį teikia finansų įstaiga, kuriai ji priklauso. Kol kas tai bus numatyta tik įrašams su BIC ir tik tada, kai atitinkama finansų įstaiga nori pateikti šią papildomą informaciją. Informacija gaunama iš BIC katalogo.
COUNTRY NAME Bet koks 70 Taip Institucijos / filialo šalies pavadinimas, kaip nurodyta ISO 3166
ISO COUNTRY CODE Alfabetinis 2 Taip Institucijos / filialo šalies ISO 3166-1 alfa-2 kodas
LOCATION CODE Bet kokio tipo 1 Taip Saugo vietą (oficialiai BIC standarto 7 pozicijoje: 2009 m.)
Pavyzdžiai:
• In FR, BICs in Paris = P
• In BE, BICs in Brussels = B
• In US, BICs in East Cost = 3
FIN SERVICE CODES Bet kokio tipo 60 Ne FIN paslaugų kodai (taip pat vadinami pridėtinės vertės paslaugų kodais). Paslaugų kodai pateikiami tik įrašams, kuriuose yra BIC.
Lauke gali būti iki 20 kartų, po tris ženklus abėcėlės tvarka.
RECORD KEY BDP Raidinis skaitmeninis 12 Ne Unikalus „Bank Directory Plus“ įrašo raktas faile.
FIELD A Bet koks 1 Ne Rezervuota ateičiai
FIELD B Bet koks 64 Ne Rezervuota ateičiai
FIELD C Bet koks 128 Ne Rezervuota ateičiai
FIELD D Bet koks 256 Ne Rezervuota ateičiai
FIELD E Bet koks 11 Ne Rezervuota ateičiai
FIELD F Bet koks 12 Ne Rezervuota ateičiai
API sistema grąžina rezultatus XML formatu, kurį lengva analizuoti įvairiose programavimo kalbose ir platformose.

BIC paieškos užklausos XML atsakymas būtų toks:


<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. API Klaidos

Klaidos atveju, API grąžina XML atsakymą, kuriame yra klaidos pranešimas.

XML žymės grąžinamos be jokių kitų laukų XML atsakyme.

Žemiau rasite visų galimų klaidų pranešimų, kuriuos gali grąžinti, aprašymą::

Būsenos kodas Tipas Aprašymas
301 Paskyros klaida API raktas negaliojantis
302 Paskyros klaida Prenumerata pasibaigė
303 Paskyros klaida Nėra užklausų
304 Paskyros klaida Jūs neturite prieigos prie šios API
401 Įvesties klaida Priimtas SWIFT ilgis 8 arba 11 simbolių
402 Įvesties klaida Banko pavadinimas netinkamas! Banko paieška turėtų būti ne mažesnė kaip 4 simbolių.
Leidžiami simboliai yra a-z, A-Z, 0-9, [tarpas]!
403 Įvesties klaida Šalies kodas neteisingas! Leidžiamas dviejų raidžių šalies kodas. Pavyzdys: UK, DE, FR