API Call
- API calls to GiroCheckout are expected as HTTP POST requests.
- Data must be transmitted as POST fields (
Content-Type: application/x-www-form-urlencoded) to the respective API URL. - All data must be encoded in UTF-8.
- The response consists of a JSON object.
Notes on Examples
The following data is used for all example calls. This data is for demonstration purposes only. The actual data to be used can be found in the GiroCockpit of the respective project. An API call using this example data will not be accepted.
- Merchant ID: 1234567
- Project ID: 1234
- Project Password: secure
All examples are shown as cURL calls and are therefore independent of any programming language.
Authentication
Authentication is performed using:
- Merchant ID (
merchantId) - Project ID (
projectId) - A password for hash generation
These credentials are available in the GiroCockpit.
An HMAC MD5 hash is generated over all transmitted parameter values and encrypted using the password. The generated hash is transmitted in the hash parameter.
The fields merchantId, projectId, and hash must always be included in messages sent to the payment server.
Generating the Hash
The hash is created from all field values of the corresponding API request. All values must be concatenated without separators or field names, following the order defined in the interface specification.
An HMAC MD5 hash is then generated from this string using the project password and passed in the hash parameter.
The order of API fields must be strictly followed when generating the string. For requests sent from the client to the server, merchantId and projectId must always come first.
Example Parameters
| Parameter | Value |
|---|---|
| merchantId | 1234567 |
| projectId | 1234 |
| parameter1 | Value1 |
| parameter2 | Value2 |
Example String for Hash Calculation
12345671234Value1Value2
PHP Example for Generating the hash Parameter
$string = '12345671234Value1Value2';
$hash = hash_hmac('MD5', $string, 'secure');
Example Parameters Including hash for Transmission
| Parameter | Value |
|---|---|
| merchantId | 1234567 |
| projectId | 1234 |
| parameter1 | Value1 |
| parameter2 | Value2 |
| hash | 4233d4d15a75d651d60ebabe99b3d846 |
Transmission of Data to the Merchant via Interface Call
The hash parameter is included in the header, appended to the data transmission to the merchant, and is used for authentication. The hash should be validated to ensure that the transmission originates from GiroCheckout.
Example Response with 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":""}
Example JSON String for Hash Calculation
{"reference":"ee8412f2-3287-4165-b8fe-c9a4bfad2320","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=WM9aoJtti5XEDSZyCortQQ7UJsXGgtcCoggKermQXcKM","rc":"0","msg":""}
PHP Example for Generating a Comparison Hash
$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');
Transmission of Data to the Merchant (Notify or Redirect)
The gcHash parameter is appended as a GET parameter in server responses to the client (merchant) and is used for authentication. The hash should be validated to ensure that the transmission originates from GiroCheckout.
The hash is generated from all received gc parameters (except gcHash) using the same principle as the API request.
Important: Parameters originating from the merchant (e.g., those already included in the Notify URLs during transaction initialization) are NOT considered when generating the hash. Only the return parameters generated by GiroCheckout that are appended to the URL and begin with "gc" are covered by the hash. Please take this into account when validating the hash.
Response to Notification
The GiroCheckout server expects a defined response to a transmitted notification. Please return the appropriate HTTP status code:
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | The notification was processed successfully. |
| 400 (Bad Request) | The merchant did not process the notification and does not want to be notified again. |
| All others | The notification will be retried up to 10 times every 30 minutes until the merchant returns HTTP status 200 or 400. |