User Tools

Site Tools


Translations of this page:
en:girocheckout:giropay:start

giropay

giropay can only process EURO payments.

Important information
During the coming months, we will be gradually ending our support for the existing giropay API (see legacy giropay documentation). After that, the ONLY valid API will be the one documented here. While planning your transition, please take into consideration our migration guide on our giropay overview web site. There you will also find a comparison of the old and new API.

API change
The following change is being made to the API in the following days:
The parameter merchantReconciliationReferenceNumber is replaced by merchantOrderReferenceNumber, which will continue to be optional but allows only 20 characters. Please also have a look a the allowed characters that are specified below.

Test data giropay

Please exclusively use the test bank specified below for these tests!

Form field Input value
Bank Testbank / Test- und Spielbank AG

You will be directed to a simulation where you can view and even edit the fields that will be sent back to your application. If you don't change anything and simply click “Ausführen”, the transaction will be successful.

Transaction result

ResultCode Response Remark
4000 transaction successful The transaction was completed successfully.
4502 transaction cancelled A cancelled transaction is triggered by clicking the link “Zurück zur Bankensuche” followed by “Zahlung abbrechen”.

Workflow

buyer/ customermerchantGiroCheckoutgiropayonline banking1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 (c)2021 by GiroSolution AG

  1. buyer/ customer chooses giropay/ giropay-ID
  2. merchant initialises giropay/giropay-ID request (initialise giropay payment)
  3. GiroCheckout initialises request at giropay
  4. giropay submits response to GiroCheckout
  5. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  6. merchant sends redirect URL to buyer/ customer
  7. the buyer's/ customer's browser redirects to giropay where the bank is selected (optional, only if bank is not already stored in browser)
  8. giropay redirects to the customer's online banking
  9. bank shows login page
  10. buyer/ customer authorises giropay payment/ giropay-ID
  11. bank processes reqest
  12. bank submits result to giropay
  13. giropay submits result to GiroCheckout
  14. GiroCheckout notifies merchant about the result (payment result notification)
  15. merchant processes result
  16. merchant sends HTTP Statuscode to GiroCheckout
  17. GiroCheckout sends merchants redirect page to giropay
  18. buyer/customer clicks “Zurück zum Shop” and gets redirected to the merchant (buyer redirection)

API functions

Overview

As shown in the workflow there are different API calls during a giropay transaction.

  1. initialise transaction
  2. payment result notification to merchant
  3. buyer redirection to the merchant (triggered by buyer after the payment or automatically after a few seconds)

Initialize giropay payment

The initialization of a giropay can be processed in different ways. This will be distinguished just by the project id.

Towards a successful initialization you receive a reference number and an redirect link. The redirect link leads to the online banking account of the buyer's bank. He has to be redirected to his bank. This can be achieved by a HTTP-Redirect-Header, HTML page with an corresponding Meta-Tag or JavaScript redirect.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: Merchant

POST parameters
Name Mandatory Type Description
merchantId yes Integer merchant ID of a giropay project
projectId yes integer project ID of a giropay project
merchantTxId yes String(255) unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(27) purpose field, characters must comply with the SEPA character set (see SEPA-compliant characters)
shoppingCartType Optional String(19) Type of the shopping cart. The following values are allowed:
PHYSICAL = All goods in the cart are of a physical nature,
DIGITAL = All goods in the cart are of a digital nature (require no shipping),
MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given),
ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary),
AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).
shippingAddresseFirstName (see descr.) String(100) First name of the shipping address. Mandatory for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters: All letters (UTF-8, also foreign), 0-9, the symbols .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] , and blanks as well as line breaks.
shippingAddresseLastName (see descr.) String(100) Last name of the shipping address. Mandatory for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName.
shippingCompany Optional String(100) Company name of shipping address. Permitted characters, see shippingAddresseFirstName.
shippingAdditionalAddressInformation Optional String(100) Additional (street) information of shipping address. Permitted characters, see shippingAddresseFirstName.
shippingStreet Optional String(100) Street of the shipping address. Permitted characters, see shippingAddresseFirstName.
shippingStreetNumber Optional String(10) House number of the shipping address. Permitted characters, see shippingAddresseFirstName.
shippingZipCode (see descr.) String(10) Postcode of shipping address. Mandatory for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName.
shippingCity (see descr.) String(100) City of shipping address. Mandatory for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName.
shippingCountry (see descr.) String(2) 2-letter country code (ISO 3166-1). Mandatory for shopping cart types PPHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT.
shippingEmail (see descr.) String(255) Email address of the buyer. Mandatory for shopping cart type DIGITAL, optional for all others.
merchantOrderReferenceNumber Optional String(20) Additional information for the payment reconciliation that is shown in the purpose on bank statements (only for type=SALE). Characters must comply with the SEPA character set (see SEPA-compliant characters).
cart Optional JSON String All products in the shopping cart in the following format (see below): Description of cart field.
deliveryType Optional String(12) The destination of a shipment. The default value is STANDARD. Possible values:
STANDARD: The goods are delivered to an ordinary postal address.
PACKSTATION: The goods are delivered to a self-service parcel terminal.
STORE_PICKUP: The goods are collected from the store.
urlRedirect yes String(2048) URL, where the buyer has to be sent after payment
urlNotify yes String(2048) URL, where the notification has to be sent after payment
kassenzeichen optional String(255) Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there. Characters must comply with the UTF-8 character set.
hash yes String(32) HMAC MD5 hash (see hash generation)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "shoppingCartType=DIGITAL" \
     -d "shippingAddresseFirstName=Max" \
     -d "shippingAddresseLastName=Mustermann" \
     -d "shippingEmail=mmuster@example.com" \
     -d "urlRedirect=http://www.ihre-domein.de/girocheckout/redirect" \
     -d "urlNotify=http://www.ihre-domein.de/girocheckout/notify" \
     -d "hash=2017e2f4d694e24a3396d83a20b3828b" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Reply

The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the online banking account of the buyer's bank.

Parameter
name mandatory type description
rc yes Integer response code
msg yes String(255) additional information about the response code
reference optional String(36) unique GiroCheckout transaction ID
redirect optional String(2048) redirect URL to the buyer's online banking account
HEADER parameter
hash yes String(32) HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : f56b5f91094cd22ace93b76ef250aa62

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
Example in case of error

hash : baf3c9b7217f362c29dd5cf6f098320c

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}

SEPA compliant characters

In SEPA payments, according to Annex 3 of this document, only characters of the limited SWIFT Latin characters set are allowed:

  • a b c d e f g h i j k l m n o p q r s t u v w x y z
  • A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
  • 0 1 2 3 4 5 6 7 8 9
  • ' : ? , - ( + . ) / |
  • Space

cart field

JSON array with item objects:

Name Mandatory Type Description
name Yes String(100) Article name
ean Optional String(100) International artical number (EAN or GTIN)
quantity Yes Integer Article quantity (integer)
grossAmount Optional Integer Gross amount of the article (price of each unit, if more than one), Bruttobetrag des Artikels, for currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
Example
[ {
    "name" : "Bobbycar",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helm",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

Notification about the payment result

The result of a initialised transaction will be submitted to the prior in the urlNotify parameter specified URL. This notification should be used to update the payment status in the merchant's system.

The result of a giropay payment is contained in the field gcResultPayment.

At the end of the payment process on giriopay-side, an automatic redirect back to the shop is done after 5 seconds.

Request

URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
name mandatory type description
giropaygiropay-IDgiropay+giropay-ID
gcReference yes yes yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes yes yes String(255) merchant transaction ID
gcBackendTxId yes yes yes String(36) payment processor transaction ID
gcAmount yes yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny
gcCurrency yes yes String(3) currency
gcResultPayment yes yes Integer payment result codes
gcHash yes yes yes String(32) HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
all others The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

Redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. After 5 seconds, there is an automatic redirect.

Request

URL: redirectUrl of the prior init transaction call
Provided by: merchant
Called by: GiroCheckout

GET parameter
name mandatory type description
giropaygiropay-IDgiropay+giropay-ID
gcReference yes yes yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes yes yes String(255) merchant transaction ID
gcBackendTxId yes yes yes String(36) payment processor transaction ID
gcAmount yes yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny
gcCurrency yes yes String(3) currency
gcResultPayment yes yes Integer payment result codes
gcHash yes yes yes String(32) HMAC MD5 hash (see hash generation)

Retrieve sender information

This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. This information may be used for a refund to the original payer.

API call

URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters
Name Mandatory Type Description
merchantId Yes Integer merchant ID of a giropay project
projectId Yes Integer project ID of a giropay project
reference Yes String(36)GiroCheckout transaction ID
hash Yes String(32)HMAC MD5 hash of the full JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \
     -d "hash=246d1fa2ed97ecff895de974c560f9ec" \
     https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo

Response

The response is a JSON object. The rc field returns an error code. If rc = 0 is returned, the corresponding fields contain the sender information.

JSON Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code in case of error
accountholder Optional String(255) Account holder of the sender account
iban Optional String(36) IBAN of the sender account
bic Optional String(11) BIC of the sender account
HEADER parameter
hash yes String(32) HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : cde71b6b98e8dae709fdc1e17aef885f

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
Example in case of error

hash : f1d186103b8c4cb59c54ae7b987a9d4c

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
en/girocheckout/giropay/start.txt · Last modified: 2023/05/07 07:51

Page Tools