Grundlegende Informationen zur Integration von GiroCheckout.

• API Aufrufe an GiroCheckout werden als HTTP POST Aufrufe erwartet.
• Daten sind als POST Felder (Content-Type: application/x-www-form-urlencoded) an die jeweilige API URL zu übertragen.
• Alle Daten müssen UTF-8 kodiert übermittelt werden.
• Die Antwort besteht aus einem JSON Objekt.

Für alle Beispiel-Aufrufe werden die folgenden Daten verwendet. Diese Daten dienen als Beispiel. Die zu verwendenden Daten sind im GiroCockpit des entsprechenden Projektes zu finden. Ein API-Aufruf mit diesen Daten wird nicht akzeptiert.

• Händler-ID: 1234567
• Projekt-ID: 1234
• Projekt-Passwort: secure

Alle Beispiele werden als cURL Aufruf dargestellt. Sie sind somit von einer Programmiersprache unabhängig.

Die Authentifizierung erfolgt durch:

• Händler-ID (merchantId)
• Projekt-ID (projectId)
• und einem Passwort zur Hash-Generierung

Diese Daten stehen im GiroCockpit.

Es wird ein HMAC MD5 Hash über alle übergebenen Parameterwerte erstellt und mit einem Passwort verschlüsselt. Der erstellte Hash wird im Parameter hash übermittelt.
Die Felder merchantId, projectId und hash müssen in Meldungen an den Payment-Server immer übermittelt werden.

Der Hash wird über alle Feldinhalte des entsprechenden API-Aufrufs gebildet. Hierbei sind alle Inhalte ohne Trennzeichen und Feldbezeichner in der Reihenfolge der Schnittstellenbeschreibung aneinanderzuhängen. Über diese Zeichenkette wird mit dem Projekt-Passwort ein HMAC MD5 Hash gebildet, der im Parameter hash übermittelt wird.

Beispielparameter

Beispiel-Zeichenkette für die Hash Berechnung:
12345671234Wert1Wert2

PHP Beispiel zur Ermittlung des Parameters hash

$string = '12345671234Wert1Wert2';
$hash = hash_hmac('MD5', $string, 'secure');

Beispielparameter inkl. hash zur Übermittlung

Der Parameter hash befindet sich im Header, wird der Datenübermittlung an den Händler angehängt und dient der Authentifizierung der Übermittlung. Der Hash sollte ausgewertet werden, um sicherzustellen, dass die Übermittlung vom GiroCheckout stammt.

Beispiel Rückantwort mit Header

HTTP/1.1 200 OK
Date: Tue, 01 Jan 1970 00:00:00 GMT
Server: Apache/1.1.11 (****)
Expires: Sun, 01 Jan 1970 00:00:00 GMT
Last-Modified: Tue, 01 Jan 1970 00:00:00 +0000
Cache-Control: no-cache, must-revalidate, post-check=0, pre-check=0
ETag: "1399387400"
hash: 149745c2fb0d3e886b781b592a0c200f
Content-Length: 187
Content-Type: application/json

{"reference":"ee8412f2-3287-4165-b8fe-c9a4bfad2320","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=WM9aoJtti5XEDSZyCortQQ7UJsXGgtcCoggKermQXcKM","rc":"0","msg":""}

Beispiel-JSON-Zeichenkette für die Hash Berechnung:

{"reference":"ee8412f2-3287-4165-b8fe-c9a4bfad2320","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=WM9aoJtti5XEDSZyCortQQ7UJsXGgtcCoggKermQXcKM","rc":"0","msg":""}

PHP Beispiel zur Ermittlung eines Vergleichshashes

$string = '{"reference":"ee8412f2-3287-4165-b8fe-c9a4bfad2320","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=WM9aoJtti5XEDSZyCortQQ7UJsXGgtcCoggKermQXcKM","rc":"0","msg":""}';
$hash = hash_hmac('MD5', $string, 'secure');

Der Parameter gcHash ist bei Antwortmeldungen des Servers an den Client (Händler) als GET-Parameter angehängt und dient der Authentifizierung der Übermittlung. Der Hash sollte ausgewertet werden, um sicherzustellen, dass die Übermittlung von GiroCheckout stammt. Die Generierung geschieht über alle empfangenen gc-Parameter (außer gcHash) hinweg und nach dem gleichen Prinzip wie beim API-Aufruf.

Wichtig: Vom Händler ausgehende Parameter, die evtl. schon bei Initialisierung der Transaktion in den dort enthaltenen NotifyURLs enthalten sind, werden für die Bildung des Hash-Wertes NICHT berücksichtigt! Nur die von GiroCheckout erzeugten Rückgabeparameter, die an diese URL angehängt werden und mit "gc" beginnen, sind über den Hash abgedeckt. Bitte beachten Sie dies bei der Prüfung des Hashes.