====== Basics ======
Basic information about the integration of GiroCheckout.

===== API calls =====
  * API calls to GiroCheckout have to be submitted as HTTPS POST. 
  * All data have to be sent as post fields (Content-Type: application/x-www-form-urlencoded) to the corresponding API URL. 
  * All data have to be submitted UTF-8 encoded.
  * The reply is JSON encoded.

===== Example hints =====
The following data are used for every example. These are just an example. The correct data can be found unter [[https://www.girocockpit.de|GiroCockpit]] in the corresponding project. The API will not accept the example data.

  * Merchant ID: 1234567
  * Project ID: 1234
  * Project Passphrase: secure

The shown examples are cURL calls. They are independent from a particular programming language.

===== Authentication =====
For the correct authentication the following data are needed:
  * Merchant ID
  * Project ID
  * Project Passphrase to generate a hash

These data can be found unter [[https://www.girocockpit.de/ | GiroCockpit]].

It is necessary to submit a HMAC MD5 hash. This generated hash has to be submitted in the hash field. \\
**For a correct authentication the Merchant ID, Project ID and hash fields have to be submitted. **

===== Hash generation =====
The hash has to be generated overall API post fields. Regarding to this the field values have to be linked together without whitespace or delimiters in the correct order referring to the API description. This string has to be hashed using HMAC MD5 and the correct Project Passphrase.

<WRAP center round important 60%>
The correct field order for the string generation has to be strictly adhered. In the first place there has to be the Merchant ID, in the second place the Project ID.
</WRAP>


**Example fields**
^argument     ^value          ^
|merchantId    |1234567       |
|projectId     |1234          |
|parameter1    |Wert1         |
|parameter2    |Wert2         |

**Example string for hash generation:**\\
12345671234Wert1Wert2

**PHP example for hash generation:**\\
<code php>
$string = '12345671234Wert1Wert2';
$hash = hash_hmac('MD5', $string, 'secret');
</code>

**Example fields inkl. hash for submission: **
^argument     ^value          ^
|merchantId    |1234567       |
|projectId     |1234           |
|parameter1    |Wert1         |
|parameter2    |Wert2         |
|hash          |4233d4d15a75d651d60ebabe99b3d846|

===== API call reply to the merchant =====

The parameter hash is located in the Header of the connection. The hash should be compared to a locally created hash. to verify that GiroCheckout sends the data. 

** Reply including the 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>

** Example JSON string used for hash generation **\\
<code>
{"reference":"ee8412f2-3287-4165-b8fe-c9a4bfad2320","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=WM9aoJtti5XEDSZyCortQQ7UJsXGgtcCoggKermQXcKM","rc":"0","msg":""}
</code>

**PHP example for hash generation **\\
<code php>
$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');
</code>

===== Data submission to merchant (Notify or Redirect) =====

Data submission from GiroConnect to the merchant includes HTTP GET parameters. The parameter gcHash is used for authentication by GiroConnect to the merchant. The merchant should check the gcHash value by comparing it to an self generated hash value. The gcHash is generated by the same way as the hash field used for API calls. Any field in the correct order as shown in the API documentation.