Integration
Bluecode
Credit Card
Direct Debit
eps
iDEAL
Klarna
Maestro
Pay by bank
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
Sidebar
de
enen:girocheckout:paybybank:start
Table of Contents
Pay by bank
Test Data
During testing, you will always be redirected to the same form, where the following fields must be filled in depending on the selected case.
Internal Simulation (without redirection):
| Form Field | Input Value |
|---|---|
| IBAN | DE63123456791212121212 |
Then confirm with “Continue” and successfully complete the process.
Deutsche Bank Sandbox:
| Form Field | Input Value |
|---|---|
| IBAN | DE17215730140403340300 [then confirm with OK] |
| Branch (Filiale) | 615 |
| Account (Konto) | 4033403 |
There are no test cases for negative outcomes via cent amounts or similar scenarios.
Workflow
- The buyer selects the “Pay by bank” payment method.
- The shop initiates a Pay-by-bank 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 Pay-by-bank 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) |
| urlRedirect | Yes | String(2048) | URL to which the customer is redirected after payment. |
| urlNotify | Yes | String(2048) | URL to which the payment result is reported. |
| 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 Result
The outcome of a Pay by bank payment is sent to the URL specified in `urlNotify`. This notification informs the merchant of the transaction outcome so the transaction status can be updated accordingly. The result is contained in the `gcResultPayment` field.
Redirecting the Customer to the Merchant
After the payment is completed, the customer is automatically redirected back to the merchant.
URL: redirectUrl from the transaction initialization
Provided by: Merchant
Called by: GiroCheckout
en/girocheckout/paybybank/start.txt · Last modified: 2025/02/28 20:36