API zur Überprüfung von BIC/SWIFT-Codes



Integration der API zur Überprüfung von BICs in Ihre Software


1. Was ist die API zur Überprüfung von BICs?


Bei der Weiterverarbeitung von Banküberweisungen mithilfe des IBAN-Verfahrens, ist der SWIFT bzw. BIC für erfolgreiche Zahlungen zwingend erforderlich.
Unser Unternehmen hat Zugriff auf das offizielle BIC-Verzeichnis der S.W.I.F.T SCRL, um Ihnen eine leistungsstarke aber einfache Möglichkeit zur automatischen Prüfung von BICs zu bieten. Dieser Service ermöglicht es Ihnen, die Prüfung anhand des BIC-Verzeichnisses für interne Zwecke in Ihre Software zu integrieren.

Die API zur Überprüfung von BICs basiert auf SWIFTRef Data. Die BIC-Daten werden mit der Erlaubnis der S.W.I.F.T. SCRL genutzt. Die Rechte an der Datenbank bleiben vorbehalten 2017




2. Kenndaten


Die API zur Überprüfung von BICs ermöglicht Ihnen:




3. Nutzung der API


Die API zur Überprüfung von BICs basiert auf REST und unterstützt einfache HTTP GET- oder POST-Anfragen.

Die zulässigen Parameter können Sie der nachfolgenden Tabelle entnehmen:

Feldname Länge Typ Beschreibung
bic 11 String BIC / SWIFT der gesucht werden soll. 8 bis 11 Zeichen sind möglich.
bank_name 256 String Teil des Banknamens um eine Suche im BIC-Verzeichnis zu starten.
country 2 String Der zweistellige Ländercode wird benötigt, wenn nach dem Banknamen gesucht wird.
api_key 128 String Ihr persönlicher API-Key.
format 4 String Wird benötigt, um das Format der Rückmeldung zu bestimmen. Zulässig sind: json, xml
limit Integer Optional: Kann genutzt werden, um die Anzahl der Suchergebnisse zu begrenzen, wenn nach einem Banknamen gesucht wird.
hist integer Optional: Kann genutzt werden, um historische Aufzeichnungen aus der Datenbank für die Bank- und BIC-Suche abzurufen.
Im Kundenbereich finden Sie Ihren persönlichen API-Key und können Ihre Zugangs-URL beantragen, die benötigt wird, um gesicherte Suchanfragen senden zu können.





4. API XML Antwortstruktur


Ein XSD Schema der API-Rückmeldung steht zum Download bereit.
Eine detaillierte Beschreibung der zurückgemeldeten Felder finden Sie in der nachfolgenden Tabelle:

Feldname Typ Länge Immer enthalten Beschreibung
MODIFICATION FLAG alphabetisch 1 Ja In Delta-Daten:
• A (Zusatz)
• M (Änderung)
• D (Löschung) in allen Daten. In allen Daten:
• A (Zusatz)
CHANGED FIELD numerisch 186 nein Zeichnet das Feld (oder die Markierung) auf, dass durch eine Datenänderung oder aufgrund eines neuen Ereignisses geändert wurde..
Eine oder mehrere Spalten werden als Zahlenfolge dargestellt. Jede Zahl steht dabei für die Spalte, die in der vorherigen Aufzeichnung oder durch ein Ereignis geändert wurde.
Beispiel "6,7,8,9"
Steht dafür, dass EVENT TYPE, EVENT DATE, BIC8, und BRANCH BIC geändert
wurden.
Die folgenden Felder sind von der Änderungsverfolgung in CHANGED FIELD ausgenommen:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY alphanumerisch 12 Ja Der einzigartige Schlüssel für den Eintrag in der Datei.
Jeder Eintrag steht für ein Ereignis in der Laufzeit des BIC.
Einmal zugewiesen, wird dieser Schlüssel nicht mehr geändert.
PREVIOUS RECORD KEY alphanumerisch 12 nein Der eingetragene Schlüssel für das vorher verknüpfte Ereignis.
Alle entsprechenden Ereignisse sind verknüpft und können über diese Information aufgefunden werden.
NEXT RECORD KEY alphanumerisch 12 nein Der RECORD KEY für das nächste verknüpfte Ereignis.
Alle relevanten Ereignisse sind verknüpft und können mit dieser Information gefunden werden.
EVENT TYPE alphabetisch 32 Ja Das Ereignis (EVENT) oder die Änderung in Verbindung mit dem BIC, die zurückliegt, gerade stattgefunden hat oder stattfinden wird.
Mögliche Ereignisse bzw. Änderungen:
• 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
Das letzte Änderungsdatum befindet sich i der letzten Zeile der BIC-Folge (aktuellster vorhandener Eintrag).
Wenn ein neues Ereignis (EVENT) hinzugefügt wird, werden das Feld MODIFICATION FLAG und CHANGED FIELD in Abhängigkeit von vorherigen Ereignis (EVENT) aktualisiert.
EVENT DATE alphanumerisch 8 Ja Das Datum eines Ereignisses (EVENT)
BIC8 alphanumerisch 8 Ja BIC (Institution, Land und Zusatz) mit:
• Institution (4 Zeichen)
• Land (2 Zeichen)
• Zusatz (2 Zeichen)
BRANCH BIC alphanumerisch 3 Ja Der Filialidentifikationscode, der an den 8-stelligen BIC angehängt wird. Wenn kein Code vorhanden ist, wird XXX genutzt.
BIC alphanumerisch 11 Ja Der vollständige BIC aus 8 Zeichen inklusive Bankidentifikation
RECORD STATUS alphabetisch 1 Ja Zeigt den Status des Eintrags an:
• [C] = Zeigt das letzte Ereignis in der Folge bis zum Datum der Veröffentlichung an, ausgenommen [F] zukünftige Ereignisse
• [H] = Historischer Eintrag in der Ereigniskette
• [F] = Zukünftiges Ereignis, das erst nach Veröffentlichung des Verzeichnisses eintreten wird. Das zuvor angezeigte [C] aktuelle Ereignis wird bis zum hinterlegten Datum des [F] zukünftigen Ereignisses gültig sein.
Für zukünftige Ereignisse zeigt das Datum an, ab wann diese gültig sind (VALID FROM).
OPERATIONALLY ACTIVE RECORD Alpha 1 Ja Hierfür sind zahlreiche Einträge verfügbar. Dieses Feld zeigt an, welche der Einträge für dieselbe BIC die aktive BIC ist und genutzt werden sollte.
• [Y] aktiv in Nutzung.
• [N] wird nicht genutzt.
Für jede Einzelne BIC existiert ein einzelner Eintrag, der den Status „AKTIV“ anzeigt (Y).
Einträge mit [H]istorischem Eintrag werden immer mit [N] angezeigt.
Einträge mit [C] können mit [Y] oder [N] markiert sein.
Einträge mit [F] werden immer mit [N] angezeigt.
SUBTYPE INDICATOR beliebig 4 Ja Das Geschäftsmodell der jeweiligen Institution. Dieser Indikator ist nur für Einträge mit einem BIC verfügbar.
SWIFT FIN alphabetisch 1 Ja Status der Verbindung des Instituts mit FIN:
• [Y] Mit FIN verbunden
• [N] Nicht mit FIN verbunden
SWIFT FA alphabetisch 1 Ja Status der Verfügbarkeit des Instituts per FileAct:
• [Y] mit FileAct verbunden
• [N] nicht mit FileAct verbunden
SWIFT IA Alpha 1 Ja Status der Erreichbarkeit per InterAct:
• [Y] erreichbar mit InterAct
• [N] nicht ereichbar mit InterAct
LEGAL NAME beliebig 105 nein Die rechtliche Bezeichnung des Instituts.
INSTITUTION NAME beliebig 105 Ja Handelsname des Instituts (veröffentlichter Name).
INSTITUTION TYPE alphabetisch 12 Ja Organisationen, die grundsätzlich in der Finanzvermittlung und/oder im Bereich finanzieller Hilfestellungen tätig sind.
Mögliche Arten sind:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE alphabetisch 16 Ja Identifiziert die Art des Finanzinstituts:
• Rechtsform
• Filiale
• Betriebliche Informationen
RE STREET ADDRESS 1 beliebig 35 nein [Registereintrag] Straßenname
RE STREET ADDRESS 2 beliebig 35 nein [Registereintrag] Hausnummer
RE STREET ADDRESS 3 beliebig 35 nein [Registereintrag] Gebäude, Gebäudename, Stockwerk
RE STREET ADDRESS 4 beliebig 35 nein [Registereintrag] Gebiet
RE CITY beliebig 35 nein [Registereintrag] Name der Stadt des Instituts bzw. der Filiale.
RE CPS beliebig 90 nein [Registereintrag] Bundesland, Stand oder andere hoheitliche Region des Inhabers bzw. der Filiale.
RE ZIP CODE beliebig 15 nein [Registereintrag] Postleitzahl des Instituts/der Filiale
RE POB NUMBER beliebig 35 nein Kommata getrenntes Feld mit der Postfachnummer der Bank/der Filiale und der zugehörigen Postleitzahl.
Beispiel
"POB 103352, 40024"
Diese Angabe ermöglicht Kunden die Nutzung der vollständigen Postfachadresse:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 beliebig 35 nein [Betrieblich] Straßenname
OP STREET ADDRESS 2 beliebig 35 nein [Betrieblich] Hausnummer
OP STREET ADDRESS 3 beliebig 35 nein [Betrieblich] Gebäude oder Stockwerk
OP STREET ADDRESS 4 beliebig 35 nein [Betrieblich] Gebiet
OP CITY beliebig 35 nein [Betrieblich] Name der Stadt des Instituts/der Fililale.
OP CPS beliebig 90 nein [Betrieblich] Bundesland, Staat oder andere hoheitliche Region des jeweiligen Instituts bzw. der Filiale
OP ZIP CODE beliebig 15 nein [Betrieblich] Postleitzahl des Instituts bzw. Der Filiale.
OP POB NUMBER beliebig 35 nein Kommata getrenntes Feld mit der Postfachnummer der Bank/der Filiale und der zugehörigen Postleitzahl.
Beispiel
"POB 103352, 40024"
Diese Angabe ermöglicht Kunden die Nutzung der vollständigen Postfachadresse:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 beliebig 35 nein [Filiale] Straßenname
BR STREET ADDRESS 2 beliebig 35 nein [Filiale] Hausnummer
BR STREET ADDRESS 3 beliebig 35 nein [Filiale] Gebäude oder Stockwerk
BR STREET ADDRESS 4 beliebig 35 nein [Filiale] Gebiet
BR CITY beliebig 35 nein [Filiale] Name der Stadt der Institution / Filiale
BR CPS beliebig 90 nein [Filiale] Bundesland, Staat oder sonstige hoheitliche Region der zugehörigen Bank / Institution
BR ZIP CODE beliebig 15 nein [Filiale] Postleitzahl
BR POB NUMBER beliebig 35 nein Kommata getrenntes Feld mit dem Postfach und der Postleitzahl der jeweiligen Institution bzw. Bank.
Beispiel
"POB 103352, 40024"
Dadurch können Kunden die vollständige Postfachanschrift nutzen:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION beliebig 70 nein Informationen zur Filiale Hierbei handelt es sich um ein freies Textfeld mit der Beschreibung der Filiale, die vom Finanzinstitut zur Verfügung gestellt wird. Die Beschreibung wird nur ausgegeben, wenn ein BIC-Eintrag vorhanden ist und wenn das Institut diese Informationen zur Verfügung stellen will. Die Daten stammen direkt aus dem BIC-Verzeichnis.
COUNTRY NAME beliebig 70 Ja Der Name des Landes in dem die Bank oder Filiale ihren Sitz hat im ISO 3166-Format.
ISO COUNTRY CODE alphabetisch 2 Ja Der Ländercode für die Institution/Filiale im ISO 3166-1 Alpha-2 Format
LOCATION CODE beliebig 1 Ja Enthält den Ort (bislang auf Position 7 des BIC nach dem Standard für 2009)
Beispiele:
• In FR, BICs in Paris = P
• In BE, BICs in Brüssel = B
• In US, BICs an der Ostküste = 3
FIN SERVICE CODES beliebig 60 nein FIN Service Codes (auch als zusätzliche Service-Codes bekannt). Service Codes sind nur für Einträge mit einem BIC vorhanden.
Dieses Feld kann bis zu 20 dreistellige Codes in alphabetischer Reihenfolge enthalten.
RECORD KEY BDP alphanumerisch 12 nein Der einzigartige Schlüssel des Bank Directory Plus-Eintrags aus der Datei.
FIELD A beliebig 1 nein Für zukünftige Verwendungen vorgesehen.
FIELD B beliebig 64 nein Für zukünftige Verwendungen vorgesehen.
FIELD C beliebig 128 nein Für zukünftige Verwendungen vorgesehen.
FIELD D beliebig 256 nein Für zukünftige Verwendungen vorgesehen.
FIELD E beliebig 11 nein Für zukünftige Verwendungen vorgesehen.
FIELD F beliebig 12 nein Für zukünftige Verwendungen vorgesehen.
Das API-System liefert die Ergebnisse im XML-Format, das einfacher in eine Vielzahl von Programmiersprachen und Plattformen eingebunden werden kann.

Eine beispielhafte XML-Antwort der API für eine BIC-Suche kann wie folgt aussehen:


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


Bei Fehlern sendet das API-System eine XML-Antwort, die Fehlermeldungen enthält.

Die XML-Tags wegen ohne weitere Felder in der XML-Antwort zurückgemeldet.

Nachfolgend finden Sie eine Beschreibung der möglichen Fehlermeldungen, die retourniert werden können:

Status-Code Typ Beschreibung
301 Zugangsfehler Der API-Schlüssel ist ungültig.
302 Zugangsfehler Der Zugang ist abgelaufen.
303 Zugangsfehler Keine Anfragen verfügbar.
304 Zugangsfehler Sie haben keinen Zugriff auf die API.
401 Eingabefehler Der SWIFT muss eine Länge von 8 oder 11 Zeichen aufweisen.
402 Eingabefehler Der Bankname ist ungültig! Die Banksuche erfordert mindestens 4 Zeichen. Erlaubte Zeichen: a-z, A-Z, 0-9, [Leerzeichen]
403 Eingabefehler Die Länderkennung ist falsch. Zulässig ist ein Ländercode mit zwei Buchstaben. Zum Beispiel: UK, DE, FR