IBAN Überprüfungs-API Dokumentation

API Einbindungsbeschreibung

1. Was hat sich in V2 der IBAN Überprüfungs-API geändert?

Wir arbeiten fortlaufend daran, unsere Dienste zu verbessern und so verbesserte Lösungen zur Zahlungsbestätigung anzubieten.
Wir haben eine neue Version unserer IBAN Überprüfungs-API entwickelt, die gegenüber der alten API einige große Vorteile bietet.

Einige der wichtigsten Merkmale der V2-API:

Flexibel - unterstützt die Formate XML und JSON
Modular - Neue inländische Bestätigungen der Kontoebene wurden integriert
Besser strukturiert - Wir haben die Bankdaten und die Bestätigungen getrennt
Statuscodes - Spezifische Statuscodes wurden zur einfacheren Analyse von Fehlern und Bestätigungsergebnissen eingeführt

2. Eigenschaften

Die IBAN Überprüfungs-API V2 ermöglicht folgende Prüfungen:

Überprüfen Sie anhand der Prüfziffern, ob eine IBAN gütig ist
Überprüfen Sie, ob eine IBAN gültige Prüfziffern für die inländische Bankleitzahl und Kontonummer enthält *
Überprüfen Sie die Länge der IBAN für das jeweilige Land
Überprüfen Sie die IBAN-Struktur und -Formatierung für das jeweilige Land

Identifizieren Sie die Bank, die die IBAN ausgegeben hat
Identifizieren Sie das Land und den Ländercode einer IBAN
Rufen Sie die Adresse der Bank ab, die die IBAN ausgegeben hat
Erhalten Sie den BIC der jeweiligen Bank
Erhalten Sie Informationen über die SEPA-Unterstützung der Bank: B2B,COR1,SCC,SCT,SDD

* Die Überprüfung von Bankleitzahl und Kontonummer ist nur für bestimmte Banken und Länder verfügbar.

3. API V2 Anfragen

Das API-System ermöglicht es Ihnen, eine IBAN-Überprüfung über einfache HTTP-Get- oder POST-Anfragen zu automatisieren.
Die akzeptierten Parameter sind in der folgenden Tabelle aufgeführt:

Feldname	Länge	Art	Beschreibung
IBAN	Max 100	String	Die zu überprüfende IBAN
api_key	128	String	Ihr persönlicher API-Schlüssel
format	5	String	Format der Rückmeldung (XML oder JSON)

*Um einen API-Schlüssel zu erhalten, wenden Sie sich bitte an: contact@iban.de oder Sie erwerben ein Abonnement über unsere Bestellseite

BEISPIEL Überprüfung einer IBAN
Nachfolgend finden Sie ein Beispiel für die Verwendung der IBAN Überprüfungs-API mit einer GET-Anforderung:

https://www.iban.com/clients/api/ibanv2.php?api_key=key&format=xml&iban=IBAN

Erläuterung:

key steht fü Ihren API-Schlüssel.
IBAN steht für die jeweilige IBAN, die durch das API-Modul geprüft werden soll.
xml bezeichnet das Format der Antowrt. Auch der Parameter json kann verwendet werden, um Antworten im JSON-Format zu erhalten.

Sobald eine HTTP-Get oder POST-Anfrage mit einem zugelassenen API-Schlüssel gesendet wurde, gibt das System die Ergebnisse im zuvor angegebenen Format aus. Ein Beispiel der Ergebnisse finden Sie im nächsten Abschnitt “API Anwortstruktur”

4. API V2 Antworten

Ein XSD-Schema der API-Antwort finden Sie nachfolgend:

Eine detaillierte Beschreibung der zurückgemeldeten bank_data Objektfelder, können Sie der folgenden Tabelle entnehmen:

Feldname	Länge	Art	Beschreibung
BIC	Max 11	String	Der BIC der ausstellenden Bank/Filiale oder Institution.
BANK	Max 256	String	Der Bankcode zur Identifizierung der Bank, die die IBAN ausgegeben hat.
BRANCH	Max 256	String	Name der jeweiligen Bankfiliale, falls verfügbar.
COUNTRY	Max 32	String	Vollständiger Name des jeweiligen Landes, z.B. “United States”
COUNTRY_ISO	2	String	Die Abkürzung des Ländercodes, bestehend aus zwei Buchstaben, z.B. US, UK, AU, FR … etc.
CITY	Max 128	String	Der Name der Stadt, in dem die ausstellende Bank liegt.
STATE	Max 128	String	Der Name des Bundeslandes, in dem sich die Bank/Filiale befindet.
ZIP	Max 11	String	Der Postcode bzw. die Postleitzahl der Stadt.
ADDRESS	Max 128	String	Die Adresse der ausstellenden Bank.
Phone	Max 128	String	Die Haupttelefonnummer der jeweiligen Bank.
FAX	Max 128	String	Die FAX-Nummer der jeweiligen Bank bzw. Filiale.
WWW	Max 128	String	Die Internetpräsenz der jeweiligen Bank bzw. Institution.
EMAIL	Max 128	String	Die E-Mail-Adresse zur Kontaktaufnahme mit der ausstellenden Bank.
ACCOUNT	Max 128	String	Die inländische Kontonummer, die in der IBAN enthalten ist.

Eine detaillierte Beschreibung der sepa_data Objektfelder können Sie der nachfochfolgenden Tabelle entnehmen:

Feldname	Länge	Art	Beschreibung
SCT	Max 3	String	Inwiefern die Bank SEPA-Überweisungen unterstützt.
SDD	Max 3	String	Inwieweit die Bank SEPA-Lastschriften unterstützt.
COR1	Max 3	String	Ob die Bank SEPA COR1 unterstützt.
B2B	Max 3	String	Ob die Bank SEPA Business to Business unterstützt.
SCC	Max 3	String	Ob die Bank SEPA Card Clearing unterstützt.

Ein Beispiel für eine XML-Rückantwort der API zu einer IBAN-Überprüfung wäre:


	
		BARCGB22
		CHELTENHAM
		BARCLAYS BANK PLC
		
		Leicester
		
		LE87 2BB
		0345 7345345
		
		
		
		United Kingdom
		GB
		30093459
	
	
		YES
		YES
		YES
		YES
		NO
	
	
		
			002
			Prüfziffer der Kontonummer ist korrekt.
		
		
			001
			IBAN-Prüfziffer ist korrekt.
		
		
			005
			IBAN-Struktur ist korrekt.
		
		
			003
			IBAN-Länge ist korrekt.

5. API V2 Statuscodes

Mathematische Überprüfungen der Prüfziffern werden im Objekt “validations” ausgegeben

Statuscode	Art	Beschreibung
301	Kontofehler	Der API-Schlüssel ist nicht korrekt.
302	Kontofehler	Das Abonnement ist abgelaufen.
303	Kontofehler	Keine Anfragen vorhanden.
304	Kontofehler	Sie haben keinen Zugriff auf diese API.
201	Überprüfung fehlgeschlagen	Die Prüfziffer der Kontonummer ist nicht korrekt.
202	Überprüfung fehlgeschlagen	Die Prüfziffer der IBAN ist nicht korrekt.
203	Überprüfung fehlgeschlagen	Die Länger der IBAN ist nicht korrekt.
205	Überprüfung fehlgeschlagen	Die Struktur der IBAN ist nicht korrekt.
001	Überprüfung erfolgreich	Die Prüfziffer der IBAN ist korrekt.
002	Überprüfung erfolgreich	Die Prüfziffer der Kontonummer ist korrekt.
003	Überprüfung erfolgreich	Die Länge der IBAN ist korrekt.
004	Überprüfung erfolgreich	Die Kontonummer unterstützt die Prüfung der Prüfziffer nicht.
005	Überprüfung erfolgreich	Die IBAN-Struktur ist korrekt.