Inhaltsverzeichnis

Grundlagen

Grundlegende Informationen zur Integration von GiroCheckout.

API Aufruf

Hinweise zu Beispielen

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.

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

Authentifizierung

Die Authentifizierung erfolgt durch:

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.

Hash generieren

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.

Die Reihenfolge der API-Felder muss bei der Stringgenerierung eingehalten werden. An erster Stelle stehen bei Meldungen vom Client an den Server immer merchantId und projectId.

Beispielparameter

Parameter Wert
merchantId 1234567
projectId 1234
parameter1 Wert1
parameter2 Wert2

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

Parameter Wert
merchantId 1234567
projectId 1234
parameter1 Wert1
parameter2 Wert2
hash 4233d4d15a75d651d60ebabe99b3d846

Übermittlung von Daten über einen Schnittstellenaufruf an den Händler

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');

Übermittlung von Daten an den Händler (Notify oder Redirect)

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.