Bankverbindung aus dem Chip der Bankkarte auslesen

Beschreibung

windata SmartCard API (girocard)

Diese COM-Library ermöglicht es jedem Softwarehersteller Bankkarten-Informationen, wie z. B. die Bankverbindung einer EC-Karte aus deren Chip auszulesen. Sämtliche Kartenleser, welche die PC/SC-Schnittstelle unterstützen, können verwendet werden.

Voraussetzungen

• SmartCard-Lesegerät mit PC/SC-kompatiblen Treibern
• Windows 7 SP1 oder höher
  • Version 2.1: Windows Vista oder höher
  • Version 1.0 - 2.0: Windows XP SP3 / Windows Server 2003 SP2 oder höher
• Microsoft Visual C++ 2019 x86 Redistributable (mitgeliefert)
  • Version 2.0 - 2.1: Microsoft Visual C++ 2015 Update 3 x86 Redistributable
  • Version 1.2 - 1.3.1: Microsoft Visual C++ 2013 x86 Redistributable
  • Version 1.0 - 1.1.1: Microsoft Visual C++ 2010 SP1 x86 Redistributable
• JET 4.0 x86 Datenbanktreiber (falls nicht vorhanden)
• Administratorenrechte
  • Setup
  • Aktualisieren der Bankleitzahlen-Datenbank bei fehlenden Schreib- / Änderungsrechten für das entsprechende Verzeichnis
• COM-kompatible Programmiersprache (dual-fähiges Interface vorhanden)

Funktionen / Datentypen

Abfrage

Interface ISmartCardInfoImpl (IID_ISmartCardInfoImpl)

• HRESULT GetCardReaders([out, retval] ISmartCardReaderCol** ppiCardReaders)
  • Zusammenfassung: Listet alle angeschlossenen SmartCard-Leser auf.
  • Eingabeparameter: N/A
  • Rückgabewert [ISmartCardReaderCol**]: Enthält ein Collection-Interface (s.u.), welches die Namen sämtlicher angeschlossener SmartCard-Leser auflistet. Hierbei sind die Leser in jener Reihenfolge aufgelistet, wie sie vom System verwaltet werden.

Implementierung

CoClass CLSID_SmartCardInfoImpl ("SmartCardInfo.SmartCardInfoImpl")

Interface IBankCard (IID_IBankCard)

• HRESULT GetAccountData([in] BSTR bsReaderName, [out, retval] IBankCardData** ppiBankCardData)
  • Zusammenfassung: Liest einen Record aus einer Bankkarte aus.
  • Eingabeparameter:
    • bsReaderName [BSTR]: Der Name des SmartCard-Lesers, welcher zuvor durch die o.g. Funktion GetCardReaders() ermittelt wurde.
  • Rückgabewert [IBankCardData**]: Enthält die PIN, Bankleitzahl, BIC, Kontonummer, IBAN, Aktivierungsdatum, sowie Ablaufdatum der Bankkarte (siehe IBankCardData-Interface).

Implementierung

CoClass CLSID_BankCard ("SmartCardInfo.BankCard")

Ergebnis

Interface ISmartCardReaderCol (IID_ISmartCardReaderCol)

• [propget] HRESULT Count([out, retval] LONG* pVal)
  • [LONG]: Gibt die Anzahl der ermittelten SmartCard-Leser zurück.

• [propget] HRESULT CardReader([in, defaultvalue(0)] LONG lIndex, [out, retval] BSTR* pVal)
  • Eingabeparameter [LONG]: Der Index des gewünschten SmartCard-Lesers. Der erste SmartCard-Leser wird durch den Index 0 referenziert, der zweite durch 1, usw. Dieser Parameter ist bei kompatiblen Programmiersprachen optional. Hierbei wird automatisch der erste SmartCard-Leser für die Datenauswertung verwendet.
  • Rückgabewert [BSTR*]: Der Name des SmartCard-Lesers.

Dieses Interface unterstützt einen COM-Enumerator, welcher in entsprechenden Programmiersprachen durch eine For...Each Syntax verwendet werden kann.

Implementierung

CoClass CLSID_SmartCardReaderCol ("SmartCardInfo.SmartCardReaderCol")

Interface IBankCardData (IID_IBankCardData)

• [propget] HRESULT m_lPAN([out, retval] LONG* pVal)
  • [LONG]: PAN (Kurz-Bankleitzahl)

• [propget] HRESULT m_lBankCode([out, retval] LONG* pVal)
  • [LONG]: Bankleitzahl

• [propget] HRESULT m_bsBIC([out, retval] BSTR* pVal)
  • [BSTR]: BIC

• [propget] HRESULT m_cyAccountNo([out, retval] CY* pVal)
  • [CY]: Kontonummer

• [propget] HRESULT m_bsIBAN([out, retval] BSTR* pVal)
  • [BSTR]: IBAN

• [propget] HRESULT m_dtActivationDate([out, retval] DATE* pVal)
  • [DATE]: Aktivierungsdatum

• [propget] HRESULT m_dtExpiryDate([out, retval] DATE* pVal)
  • [DATE]: Ablaufdatum

Implementierung

CoClass CLSID_BankCardData ("SmartCardInfo.BankCardData")

Aktualisierung

Interface IBankCardUpdate (IID_IBankCardUpdate)

• HRESULT CheckForBankMasterUpdate([out, retval] VARIANT_BOOL* pvbNewBankMasterAvailable)

• Zusammenfassung: Vergleicht den Versionsstand der lokalen Bankleitzahlen-Datenbank mit der Server-Version.
  • Eingabeparameter: N/A
  • Rückgabewert [VARIANT_BOOL*]: Falls eine neuere Version der BLZ-Datenbank verfügbar ist, gibt die Funktion 'VARIANT_TRUE' zurück. Andernfalls wird 'VARIANT_FALSE' zurückgegeben.

• HRESULT UpdateBankMaster()
  • Zusammenfassung: Lädt die aktuelle Bankleitzahlen-Datenbank vom windata-Server herunter und aktualisiert die lokale Version. Es wird empfohlen diese Funktion aufzurufen, falls der Aufruf der o.g. Funktion "CheckForBankMasterUpdate()" zu einem postiven Ergebnis führt. Diese Funktion benötigt evtl. Administratorrechte.
  • Eingabeparameter: N/A
  • Rückgabewert: N/A

Implementierung

CoClass CLSID_BankCardUpdate ("SmartCardInfo.BankCardUpdate")

Class Factory

Interface ISmartCardInfoFct (IID_ISmartCardInfoFct)

• HRESULT CreateInstance([in] BSTR bsProgID, [out, retval] IDispatch** ppiDisp)
  • Zusammenfassung: Erzeugt eine neue Instanz. Instanzen der Library können ausschließlich mittels dieses Interfaces angefordert werden. Eine Instanziierung mittels Standardfunktionen (CoCreateInstance(), new(), etc.) ist nicht vorgesehen.
  • Eingabeparameter:
    • bsProgID [BSTR]: ProgID der angeforderten Instanz.
  • Rückgabewert [IDispatch**]: Neue Instanz.

Implementierung

CoClass CLSID_SmartCardInfoFct ("SmartCardInfo.SmartCardInfoFct")

Events

Interface _IBankCardUpdateEvents (IID__IBankCardUpdateEvents)

• HRESULT DownloadProgress([in] LONG lProgress)
  • Zusammenfassung: Zeigt den Fortschritt des Downloads beim Aktualiseren der Bankleitzahlen-Datenbank an.
  • Eingabeparameter:
    • lProgress [LONG]: Fortschritt des Downloads in Prozent.
  • Rückgabewert: N/A

Implementierung

CoClass CLSID_BankCardUpdate

Library

Library LIBID_SmartCardInfoLib

Einbindung

Hinweise zur Implementierung sind im Download-Paket vorhanden. Hier finden Sie beispielhafte Lösungen für C++, C#, VB6 und VBA. Skriptsprachen können mittels IDispatch ebenfalls auf die Library zugreifen. Hierzu ist im Demo-Verzeichnis ein VBS-, sowie JScript-Beispiel hinterlegt. Der Einsatz weiterer Programmiersprachen ist problemlos möglich, sofern diese die COM-Umgebung unterstützen (z.B. Java, Python, Delphi).

Anwendung

Nach dem Auslesen einer Girocard kann als visuelles Ergebnis beispielsweise Folgendes angezeigt werden:

Fehlerrückmeldung

Die Fehlerrückmeldungen lassen sich in folgende Kategorien unterteilen:

• Fehler, welche vom SmartCard-Leser bzw. der unterliegenden PC/SC-Schnittstelle generiert werden. Eine Liste möglicher Fehlercodes finden sich hier.
• Fehler, welche durch die Bankkarte ausgelöst werden (E_APDU_RESPONSE = 0xE0040300). Zur Unterstützung und Behebung dieser Fehlerklasse wenden Sie sich bitte an den Support Ihrer Bank.
• Alle sonstigen Fehler, welche durch einen bekannten HRESULT gemeldet werden.

Versionshistorie

Version 2.2.1 (20210122)

• Aktualisierte CoFIS Library
• Aktualisierte BLZ-Datenbank

Version 2.2 (20200516)

• Diverse Optimierungen
• Compiler-Update: MSVC2019
• Aktualisierte CoFIS Library
• Aktualisierte BLZ-Datenbank
• Eingliederung der Visual C++ Runtime in das Setup
• Setup-Routine verbessert

Version 2.1 (20170322)

• Windows XP & Windows Server 2003 werden nicht mehr unterstützt
• Aktualisierte CoFIS Library
• .NET Framework 4.0 als Installationsvoraussetzung entfernt
• Die Visual C++ Runtime ist nicht mehr Teil des Setup. Falls nicht vorhanden, muss diese manuell installiert werden.
• Setup-Routine verbessert

Version 2.0 (20170104)

• Komplette Überarbeitung der Library: Portierung der Funktionen in natives COM-Interface
• Zusammenführung bisheriger Produktversionen
• Aufnahme zusätzlicher Properties aus der Bankkarte
• Compiler-Update: MSVC 2015

Version 1.3.1 (20150113)

• Bugfix bei der IBAN-Berechnung (betrifft nur die SmartCardInfo Extended Library

Version 1.3 (20141211)

• Bugfix bei der Erkennung der neuen IBAN-Bankkarten
• Optimierungen
• Namensänderung: "SmartCardInfo", statt "SmartCard Info"
• Die Entwicklung der Library erfolgt zukünftig in zwei unterschiedlichen Versionen:
  • SmartCardInfo.dll (PAN): Diese Version wandelt die ermittelte PAN nicht um. Sie repräsentiert somit den Versionsstand der Library vor der Version 1.2.
  • SmartCardInfoEx.dll (PAN zu BLZ Umwandlung): Diese Library verwendet die windata CoFIS Library, um die PAN in ihre zugehörige BLZ umzuwandeln. Dies stellt den Versionsstand der Library 1.2 und später dar.

Version 1.2.1 (20141201)

• Diverse Optimierungen

Version 1.2 (20141111)

• Die PAN wird nun direkt mittels der zugehörigen windata CoFIS Library in ihre zugehörige Bankleitzahl umgewandelt. Dieser Prozess erfolgt transparent im Hintergrund. Dadurch ist der Rückgabewert der "GetAccountData()"-Funktion nun wie folgt definiert: <Bankleitzahl>;<KontoNr.>;<Ablaufdatum>.
• Zwei neue Funktionen sind verfügbar:
  • CheckForBankMasterUpdate(): Vergleicht den Versionsstand der lokalen Bankleitzahlen-Datenbank mit der Server-Version
  • DownloadCurrentBankMaster(): Lädt die aktuelle Bankleitzahlen-Datenbank vom windata-Server herunter
• Compiler-Update: MSVC 2013. Die zugehörige Runtime ist erforderlich, um die Library verwenden zu können
• Weitere Stabilitäts- und Performanceverbesserungen

Version 1.1.1 (20140612)

• Diverse Optimierungen

Version 1.1 (20140408)

• Bereitstellung einer Header- und Lib-Datei, um die DLL einfacher einbinden zu können
• Kompatibilität des zurückgegebenen BSTR verbessert
• Die MSVC 2010-Runtime ist nun zwingend erforderlich, um die DLL verwenden zu können
• Unicode-Unterstützung
• Diverse Optimierungen

Version 1.0 (20130423)

• Ursprüngliche Version

Download (Trial-Version)

Eine Trial-Version der Library steht zu Evaluierungszwecken zur Verfügung. Führen Sie hierzu die Datei "setup.exe" aus, um die Library auf Ihrem System zu installieren (Administratorrechte erforderlich).

Lizenzierung

Zur Lizenzierung dieser Library wenden Sie sich bitte an den Vertrieb der windata GmbH & Co.KG unter info@windata.de.