Integration
Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
Sidebar
de
enen:girocheckout:direktubw:start
Table of Contents
Direktüberweisung
Test Data
Workflow
- The buyer selects the “Direktüberweisung” payment method.
- The shop initiates a Direktüberweisung transaction with GiroCheckout (Initialization)
- GiroCheckout initializes the transaction with the data center.
- The data center transmits the result to GiroCheckout.
- The shop receives feedback on the initialization outcome (with a redirect URL in case of success; if there is an error, the transaction is terminated).
- The shop sends the redirect URL to the customer's browser.
- The customer's browser redirects to the data center.
- The customer enters the data in the payment form.
- Depending on the customer's bank, the data center forwards the request to the bank.
- The customer's bank displays the login page, the customer logs in, and authorizes the transaction.
- The bank processes the transfer.
- The bank transmits the result to the data center.
- The data center transmits the result to GiroCheckout.
- GiroCheckout notifies the shop of the transaction outcome (Notification)
- The shop processes the transaction outcome.
- The shop sends an HTTP status code to GiroCheckout (as a response to the notification).
- GiroCheckout redirects the customer back to the shop (Redirect)
- The shop displays the transaction result.
API Functions
Initializing a Payment
A successful initialization creates a reference number and provides a redirect link to the merchant. The provided link leads to a form at the data center, where payment data is entered and usually forwarded to the buyer's bank, depending on the bank's process. Additional information may be requested, and confirmations obtained. The buyer must be redirected to this URL, which can be done via an HTTP redirect header, an HTML page with a corresponding meta tag, or JavaScript.
Request
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Provided by: GiroCheckout
Called by: Merchant
POST Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| merchantId | Yes | Integer | Merchant ID of the shop |
| projectId | Yes | Integer | Project ID of a Direktüberweisung project |
| merchantTxId | Yes | String(255) | Unique transaction ID of the merchant (e.g., order number). Allowed characters: any letters (including special characters), 0-9, & = + , : ; . _ ! ? # / |
| amount | Yes | Integer | Amount in cents |
| currency | Yes | String(3) | Currency of the transaction \ EUR = Euro (default) |
| purpose | Yes | String(27) | Purpose of the transfer (appears on the bank statement) |
| type | optional | String(4) | Transaction type (see Transaction types) SALE = Immediate booking (default and only allowed option) |
| urlNotify | Yes | String(2048) | URL to which the payment result is reported. |
| urlRedirect | Yes | String(2048) | URL to which the customer is redirected after payment. |
| kassenzeichen | Optional | String(255) | Optional field for transmitting a case number. It is displayed in the GiroCockpit transaction details, exported with the transaction data, and searchable. Allowed characters are all UTF-8 characters. |
| hash | Yes | String(32) | HMAC MD5 hash of all call values. See hash generation |
Example
curl -d "merchantId=1234567" \
-d "projectId=1234" \
-d "merchantTxId=1234567890" \
-d "amount=100" \
-d "currency=EUR" \
-d "purpose=Beispieltransaktion" \
-d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
-d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
-d "hash=256b7bb16edbc76871c830d0d623c303" \
https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Response
The response contains a JSON object. The `rc` field returns an error code. If `rc = 0`, the transaction was successfully initialized. The response includes a transaction number and a redirect URL to the buyer's online banking.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| rc | Yes | Integer | Error number |
| msg | Yes | String(255) | Additional information in case of an error |
| reference | Yes | String(36) | Unique GiroCheckout transaction ID |
| redirect | Yes | String(2048) | Redirect URL to direct the customer to online banking |
| HEADER Parameter | |||
| hash | Yes | String(32) | HMAC MD5 hash of all response values. See hash generation |
Successful Example
hash : 177a0db9c9745b94e1b8d31b22cc7876
{"reference":"c6edadaa-b507-49f1-a548-013675fb5c83","redirect":"https://test-payform.girocheckout.de/web-api/de_DE/R.po?n=wUcNog4zKHgZcO6_Psg6N7KHiemkJSnAg7v0lyh4eKo54k","rc":"0","msg":""}
Error Example
hash : 98d9d8b133acf97eb92601fa72d804a0
{"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":"Fehler beim Zahlungsabwickler"}
Notification of Payment Outcome
The outcome of a direct transfer payment is transmitted to the URL specified in the urlNotify parameter. This notification is used to inform the merchant about the transaction result. Based on this information, the transaction status can be updated on the merchant's system. The payment outcome of the transaction is provided in the gcResultPayment field.
Request
URL: notifyUrl from the transaction initialization
Provided by: Merchant
Called by: GiroCheckout
GET Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| gcReference | Yes | String(36) | GiroCheckout transaction ID |
| gcMerchantTxId | Yes | String(255) | Merchant transaction ID |
| gcBackendTxId | Yes | String(8) | Payment processor transaction ID |
| gcAmount | Yes | Integer | For decimal currencies, specify the amount in the smallest currency unit, e.g., cents |
| gcCurrency | Yes | String(3) | Currency (typically EUR) |
| gcResultPayment | Yes | Integer | Payment result codes |
| gcHash | Yes | String(32) | HMAC MD5 hash of all request values. See hash generation |
Response
One of the following HTTP status codes is expected in response to the GET request.
| HTTP Status Code | Description |
|---|---|
| 200 (OK) | The notification was successfully processed. |
| 400 (Bad Request) | The merchant did not process the notification but 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 code 200 or 400. |
Redirecting the Customer to the Merchant
After the payment is completed, the customer is automatically redirected back to the merchant.
Request
URL: redirectUrl from the transaction initialization
Provided by: Merchant
Called by: GiroCheckout
GET Parameters
| Name | Required | Type | Description |
|---|---|---|---|
| gcReference | Yes | String(36) | GiroCheckout transaction ID |
| gcMerchantTxId | Yes | String(255) | Merchant transaction ID |
| gcBackendTxId | Yes | String(8) | Payment processor transaction ID |
| gcAmount | Yes | Integer | For decimal currencies, specify the amount in the smallest currency unit, e.g., cents |
| gcCurrency | Yes | String(3) | Currency (typically EUR) |
| gcResultPayment | Yes | Integer | Payment result |
| gcHash | Yes | String(32) | HMAC MD5 hash of all request values. See hash generation |
en/girocheckout/direktubw/start.txt · Last modified: 2025/04/01 02:59