====== Grundlagen ======
Grundlegende Informationen zur Integration von GiroCheckout.

===== API Aufruf =====
  * API Aufrufe an GiroCheckout werden als HTTPS POST Aufrufe erwartet. 
  * Daten sind als POST Felder an die jeweilige API URL zu übertragen. 
  * Alle Daten müssen UTF-8 kodiert übermittelt werden.
  * Die Antwort besteht aus einem JSON Objekt.

===== Hinweise zu Beispielen =====

Für alle Beispiel-Aufrufe werden die folgenen Daten verwendet. Diese Daten dienen als Beispiel. Die zu verwendenden Daten sind im [[https://www.girocockpit.de|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.


===== Authentifizierung =====
Die Authentifizierung erfolgt durch:
  * Händler-ID (merchantId)
  * Projekt-ID (projectId) 
  * und einem Passwort zur Hash-Generierung

Diese Daten stehen im [[https://www.girocockpit.de/ | 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 immer übermittelt werden.**
===== Hash Generierung =====
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.

<WRAP center round important 60%>
Die Reihenfolge der API-Felder muss bei der Stringgenerierung eingehalten werden. An erster Stelle stehen immer merchantId und projectId.
</WRAP>


**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**\\
<code php>
$string = '12345671234Wert1Wert2';
$hash = hash_hmac('MD5', $string, 'secure');
</code>

**Beispielparameter inkl. hash zur Übermittlung**
^Parameter     ^Wert          ^
|merchantId    |1234567       |
|projectId     |1234           |
|parameter1    |Wert1         |
|parameter2    |Wert2         |
|hash          |4233d4d15a75d651d60ebabe99b3d846|


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

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 Anfrage mit Header**
<code>
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":""}
</code>

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

Der Parameter gcHash ist als GET-Parameter angehengt und dient der Authentifizierung der Übermittlung. Der Hash sollte ausgewertet werden, um sicherzustellen, dass die Übermittlung vom GiroCheckout stammt. Die Generierung geschieht über alle Parameter hinweg. Die Hashgenerierung geschieht hier nach dem gleichen Prinzip wie beim API-Aufruf.