BIC-/SWIFT-koodin vahvistus-API

Miten BIC-vahvistus-API integroidaan ohjelmistoosi

1. Mikä BIC-vahvistus-API?

Tilisiirtojen ja IBAN-rahansiirtojen käsittelyssä oikean SWIFT-/BIC-koodin syöttäminen on tärkeää onnistuneiden maksujen varmistamiseksi.
Yrityksellämme on S.W.I.F.T SCRL:n virallinen BIC-hakemistolisenssi tarjotaksemme tehokkaan ja yksinkertaisen tavan vahvistaa BIC-koodeja automaattisesti. Tämän palvelun avulla voit integroida BIC-koodihakemiston ohjelmistoosi sisäisiä tarkoituksia varten

BIC-vahvistus-API sisältää SWIFTRef:n tietoja. BIC-tietoja käytetään S.W.I.F.T. SCRL:n suostumuksella. Tietokantaoikeudet pidätetään 2019

2. Ominaisuudet

BIC-vahvistus-API:n tärkeimmät ominaisuudet:

  • Hakee pankkitietoja BIC-koodin perusteella.
  • Etsii pankin nimen ja maan BIC-hakemistosta.
  • Etsii historiallisia tallenteita BIC-hakemistosta.
  • Käyttää sekä täydellistä että yksinkertaistettua API-vastetta helpottaakseen integroimista.


3. API:n käyttö

BIC-vahvistus-API on REST-pohjainen ja se tukee yksinkertaisia HTTP GET- tai POST -pyyntöjä.

Hyväksytyt parametrit on listattu alla olevaan taulukkoon:

Kentän nimi Pituus Tyyppi Kuvaus
bic 11 Merkkijono BIC-/SWIFT-koodin haku. Voi olla 8–11 merkkiä
pankin_nimi 256 Merkkijono Hae BIC-hakemistosta kirjoittamalla osa pankin nimestä.
maa 2 Merkkijono Kaksikirjaiminen maakoodi. Pakollinen etsiessäsi pankin nimellä.
api_avain 128 Merkkijono Henkilökohtainen API-avaimesi.
muoto 4 Merkkijono Pakollinen määrittääksesi paluutietojen muodon. Tuetut arvot: json, xml
rajoita Kokonaisluku Valinnainen: voidaan käyttää rajoittamaan tulosten määrää etsiessäsi pankin nimellä.
hist Kokonaisluku Valinnainen: voidaan käyttää näyttämään tietokantojen historiallisia tallenteita sekä pankin että BIC-koodin haussa.
Voit löytää verkkoportaalista API-avaimesi sekä pyynnön päätepisteen URL-osoitteen, joita käytetään suojaamaan hakupyyntöjä.


4. API XML -vasteen rakenne

Voit ladata API-vasteen XSD Scheman.
Yksityiskohtainen kuvaus paluukentistä on esitetty alla olevassa taulukossa:

Kentän nimi Tyyppi Pituus Aina näkyvissä Kuvaus
MUUTOSLIPPU Aakkosellinen 1 Kyllä Delta-tiedostoissa:
• A (lisäys)
• M (muutos)
• P (poisto) kokonaisissa tiedostoissa Kokonaisissa tiedostoissa:
• A (lisäys)
MUUTETTU KENTTÄ Numeerinen 186 Ei Kirjaa kentän (tai TUNNISTEEN), jota on muutettu joko tallenteen muutoksen tai uuden TAPAHTUMAN johdosta.
Yksi tai useampi sarake esitetään numerojonona, jossa jokainen numero edustaa muutettua saraketta edellisestä kirjauksesta tai TAPAHTUMASTA.
Esimerkiksi "6,7,8,9"
Tämä tarkoittaa, että TAPAHTUMAN TYYPPI, TAPAHTUMAN PÄIVÄMÄÄRÄ, BIC8 ja HAARAKONTTORIN BIC ovat
muuttuneet.
Seuraavia KENTTIÄ ei kirjata MUUTETUIKSI KENTIKSI:
• KIRJAUSAVAIN
• MUUTETTU KENTTÄ
• MUUTOSLIPPU
KIRJAUSAVAIN Aakkosellinen 12 Kyllä Kentän kirjauksen ainutlaatuinen avain
Jokainen kirjaus edustaa BIC-syklin tapahtumaa.
KIRJAUSAVAIN ei muutu sen määrittämisen jälkeen.
EDELLINEN KIRJAUSAVAIN Aakkosellinen 12 Ei Aiemmin liitetyn TAPAHTUMAN KIRJAUSAVAIN
Kaikki liittyvät tiedot liitetään ja paikannetaan näiden tietojen avulla.
SEURAAVA KIRJAUSAVAIN Aakkosellinen 12 Ei Seuraavan liitetyn tapahtuman KIRJAUSAVAIN
Kaikki liittyvät tiedot liitetään ja paikannetaan näiden tietojen avulla
TAPAHTUMAN TYYPPI Aakkosellinen 32 Kyllä Kuvaus BIC-koodiin liittyvästä TAPAHTUMASTA tai muutoksesta, joka on tapahtunut menneisyydessä, nykyhetkessä tai tapahtuu tulevaisuudessa.
Tapahtumatyypit:
• BIC MYÖNNETTY
• BIC VANHENTUNUT
• BIC AKTIVOITU FIN:SSA
• BIC AKTIVOITU FA:SSA
• BIC AKTIVOITU IA:SSA
• BIC DEAKTIVOITU FIN:SSA
• BIC DEAKTIVOITU FA:SSA
• BIC DEAKTIVOITU IA:SSA
• BIC DEAKTIVOITU
• BIC LAKKAUTETTU
• BIC AKTIVOITU UUDELLEEN
• BIC JULKISTETTU
• BIC OIKEUDELLINEN NIMI MUUTETTU
• BIC INSTITUUTION NIMI MUUTETTU
• BIC OSOITE MUUTETTU
• FIN PALVELUKOODI MUUTETTU
Viimeisin päivityspäivämäärä on BIC-jonon viimeinen rivi (kyseessä on viimeisin kirjaus).
Kun uusi TAPAHTUMA lisätään, MUUTOSLIPPU- ja MUUTETTU
KENTTÄ -sarakkeet päivitetään välittömästi edelliseen liittyvään TAPAHTUMAAN.
TAPAHTUMAN PÄIVÄMÄÄRÄ Aakkosellinen 8 Kyllä TAPAHTUMAN päivämäärä
BIC8 Aakkosellinen 8 Kyllä BIC (instituutio, maa ja osapuolen tunniste), jossa:
• Osapuolen tunniste (4 merkkiä)
• Maakoodi (2 merkkiä)
• Osapuolen tunniste (2 merkkiä)
HAARAKONTTORIN BIC Aakkosellinen 3 Kyllä 8-merkkiseen BIC-koodiin liittyvä haarakonttorin BIC-tunniste. Mikäli haarakonttorilla ei ole tunnistetta, käytetään tunnusta XXX.
BIC Aakkosellinen 11 Kyllä Täydellinen BIC: 8-merkkinen BIC ja haarakonttorin tunniste
KIRJAUKSEN TILA Aakkosellinen 1 Kyllä Ilmaisee kirjauksen tilan:
• [N] = Nykyinen edustaa ketjun viimeisintä tapahtumaa julkaisupäivään asti, pois lukien [t]ulevat tapahtumat
• [H] = Tapahtumaketjun historialliset kirjaukset
• [T] = Hakemiston julkaisupäivän jälkeen tapahtuvat tulevat tapahtumat. Aiemmin esitetyt [n]ykyiset tapahtumat ovat voimassa [t]ulevissa tapahtumissa määritettyyn päivään asti.
TULEVIEN tapahtumien osalta päivämäärä ilmaisee, milloin muutos tulee VOIMAAN.
TOIMINNALLISESTI AKTIIVINEN KIRJAUS Aakkosellinen 1 Kyllä Samalle BIC-koodille on useita kirjauksia. Tämä kenttä ilmaisee, mitkä samaa BIC-koodia koskevat kirjaukset ovat toiminnallisesti aktiivisia ja käytettävissä.
• [Y] Toiminnallisesti aktiivinen
• [N] Toiminnallisesti passiivinen
Jokaiselle ainutlaatuiselle BIC-koodille on oma tietueensa, joka ilmaisee AKTIIVISEN tilan (Y).
[H]istoriallisten tilojen kirjaukset ilmaisevat aina PASSIIVISEN tilan [N].
[N]ykyiset kirjaukset voivat ilmaista joko aktiivisen [Y] tai passiivisen [N] tilan.
[T]ulevat kirjaukset ilmaisevat aina passiivisen [N] tilan.
ALATYYPIN ILMAISIN Mikä tahansa tyyppi 4 Kyllä Yksikön liiketoimintatyyppi. Alatyypin ilmaisin ilmoitetaan ainoastaan BIC-koodillisiin kirjauksiin.
SWIFT FIN Aakkosellinen 1 Kyllä Yksikön FIN-yhteyden tila:
• [Y] liitetty FIN:n
• [N] ei liitetty FIN:n
SWIFT FA Aakkosellinen 1 Kyllä Yksikön saavutettavuuden tila FileActin kautta:
• [Y] liitetty FileActiin
• [N] ei liitetty FileActiin
SWIFT IA Aakkosellinen 1 Kyllä Yksikön saavutettavuuden tila InterActin kautta:
• [Y] liitetty InterActiin
• [N] ei liitetty InterActiin
OIKEUDELLINEN NIMI Mikä tahansa 105 Ei Instituution oikeudellinen nimi
INSTITUUTION NIMI Mikä tahansa 105 Kyllä Instituution kauppanimi (julkistettu nimi)
INSTITUUTION TYYPPI Aakkosellinen 12 Kyllä Organisaatio, joka harjoittaa pääasiassa rahoituksen välittämistä ja/tai rahoitustoiminnassa avustamista
Instituution tyyppi:
• RAHOITUS
• EI-RAHOITUS
YKSIKÖN TYYPPI Aakkosellinen 16 Kyllä Ilmaisee rahoituslaitoksen tyypin:
• Oikeudellinen yksikkö
• Haarakonttori
• Toiminnallinen
REKISTERÖITY KATUOSOITE 1 Mikä tahansa 35 Ei [Rekisteröity] katuosoite
REKISTERÖITY KATUOSOITE 2 Mikä tahansa 35 Ei [Rekisteröity] katuosoite
REKISTERÖITY KATUOSOITE 3 Mikä tahansa 35 Ei [Rekisteröity] talo, talon nimi, kerros
REKISTERÖITY KATUOSOITE 4 Mikä tahansa 35 Ei [Rekisteröity] alue
REKISTERÖITY KAUPUNKI Mikä tahansa 35 Ei [Rekisteröity] instituution/haarakonttorin kaupungin nimi
RE MMK Mikä tahansa 90 Ei [Rekisteröity] Maa, maakunta, kunta tai muu instituution/haarakonttorin hallinnollinen alue
REKISTERÖITY POSTINUMERO Mikä tahansa 15 Ei [Rekisteröity] Instituution/haarakonttorin postinumero
REKISTERÖITY POSTILAATIKON NUMERO Mikä tahansa 35 Ei Pilkulla eroteltu kenttä instituution/haarakonttorin postilaatikon numerosta ja postinumerosta.
Esimerkki
"postilaatikko 103352, 40024"
Tämän ansiosta asiakkaat voivat käyttää täydellistä postilaatikko-osoitetta:
Postilaatikko 103352
40024, DUESSELDORF (KAUPUNKI)
TO KATUOSOITE 1 Mikä tahansa 35 Ei [Toiminnallinen] Kadun nimi
TO KATUOSOITE 2 Mikä tahansa 35 Ei [Toiminnallinen] Kadun numero
TO KATUOSOITE 3 Mikä tahansa 35 Ei [Toiminnallinen] Rakennus, rakennuksen nimi, kerros
TO KATUOSOITE 4 Mikä tahansa 35 Ei [Toiminnallinen] Alue
TO KAUPUNKI Mikä tahansa 35 Ei [Toiminnallinen] Instituution/haarakonttorin kaupungin nimi
TO MMK Mikä tahansa 90 Ei [Toiminnallinen] Maa, maakunta, kunta tai muu instituution/haarakonttorin hallinnollinen alue
TO POSTINUMERO Mikä tahansa 15 Ei [Toiminnallinen] Instituution/haarakonttorin postinumero
TO POSTILAATIKON NUMERO Mikä tahansa 35 Ei Pilkulla eroteltu kenttä instituution/haarakonttorin postilaatikon numerosta ja postinumerosta.
Esimerkki
"Postilaatikko 103352, 40024"
Tämän ansiosta asiakkaat voivat käyttää täydellistä postilaatikko-osoitetta:
Postilaatikko 103352
40024, DUESSELDORF (KAUPUNKI)
HK KATUOSOITE 1 Mikä tahansa 35 Ei [Haarakonttori] Kadun nimi
HK KATUOSOITE 2 Mikä tahansa 35 Ei [Haarakonttori] Kadun numero
HK KATUOSOITE 3 Mikä tahansa 35 Ei [Haarakonttori] Rakennus, rakennuksen nimi, kerros
HK KATUOSOITE 4 Mikä tahansa 35 Ei [Haarakonttori] Alue
HK KAUPUNKI Mikä tahansa 35 Ei [Haarakonttori] Instituution/haarakonttorin kaupungin nimi
HK MMK Any 90 No [Branch] Maa, maakunta, kunta tai muu instituution/haarakonttorin hallinnollinen alue
HK POSTINUMERO Mikä tahansa 15 Ei [Haarakonttori] Instituution/haarakonttorin postinumero
HK POSTILAATIKON NUMERO Mikä tahansa 35 Ei Pilkulla eroteltu kenttä instituution/haarakonttorin postilaatikon numerosta ja postinumerosta.
Esimerkki
"Postilaatikko 103352, 40024"
Tämän ansiosta asiakkaat voivat käyttää täydellistä postilaatikko-osoitetta:
Postilaatikko 103352
40024, DUESSELDORF (KAUPUNKI)
HAARAKONTTORIN TIEDOT Mikä tahansa 70 Ei Haarakonttorin tiedot
Tämä on rahoituslaitoksen tarjoama ilmainen tekstikuvaus haarakonttoristaan. Toistaiseksi tämä tarjotaan vain BIC-koodillisille tietuille, mikäli rahoituslaitos haluaa antaa näitä lisätietoja. Tiedot ovat peräisin BIC-hakemistosta.
MAAN NIMI Mikä tahansa 70 Kyllä Instituution/haarakonttorin maan nimi ISO 3166 -standardin mukaisesti
ISO-MAAKOODI Aakkosellinen 2 Kyllä Instituution/haarakonttorin ISO 3166-1 -standardin alfa-2-maakoodi
SIJAINTIKOODI Mikä tahansa tyyppi 1 Kyllä Sisältää sijainnin (muodollisesti BIC-standardin: 2009 sijalla 7)
Esimerkit:
• FR:ssa, BIC:t Pariisissa = P
• BE:ssa, BIC:t Brysselissä = B
• US:ssa, BIC:t Itä-rannikolla = 3
FIN-PALVELUKOODIT Mikä tahansa tyyppi 60 Ei FIN-palvelukoodit (kutsutaan myös lisäarvopalvelukoodeiksi). Palvelukoodit ilmoitetaan vain BIC-koodeja sisältäviin tietueisiin.
Kenttä voi sisältää enintään 20 kolmemerkkistä koodia aakkosjärjestyksessä.
TIETUEAVAIN BDP Aakkosellinen 12 Ei Tiedoston Bank Directory Plus -tietueen ainutlaatuinen avain.
KENTTÄ A Mikä tahansa 1 Ei Varattu tulevaan käyttöön
KENTTÄ B Mikä tahansa 64 Ei Varattu tulevaan käyttöön
KENTTÄ C Mikä tahansa 128 Ei Varattu tulevaan käyttöön
KENTTÄ D Mikä tahansa 256 Ei Varattu tulevaan käyttöön
KENTTÄ E Mikä tahansa 11 >E>i Varattu tulevaan käyttöön
KENTTÄ F Mikä tahansa 12 Ei Varattu tulevaan käyttöön
API-järjestelmä palauttaa tulokset XML-muodossa, joka on helppo jäsentää useilla ohjelmistokielillä ja -alustoilla.

API-järjestelmän luoma XML-vastausmalli BIC-haussa olisi:


<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-virheet

API palauttaa virhetilanteessa virheviestin sisältävän XML-vasteen.

XML-tunnisteet palautetaan XML-vasteessa ilman mitään muita kenttiä.

Alla on lueteltu kaikki mahdolliset virheviestit:

Tilakoodi Tyyppi Kuvaus
301 Tilivirhe API-avain on virheellinen
302 Tilivirhe Tilaus päättynyt
303 Tilivirhe Kyselyitä ei ole saatavilla
304 Tilivirhe Sinulla ei ole käyttöoikeutta tähän API:n
401 Syöttövirhe SWIFT:n hyväksytty pituus 8 tai 11 merkkiä
402 Syöttövirhe Virheellinen pankin nimi! Pankkihaun on oltava vähintään 4 merkkiä pitkä.
Sallitut merkit a-z, A-Z, 0-9, [välilyönti]!
403 Syöttövirhe Virheellinen maakoodi! Maakoodin on oltava 2 merkkiä. Esimerkki: UK, DE, FR