User Tools

Site Tools

Translations of this page:

Java SDK

The GiroCheckout SDK for Java allows for an easy integration of our GiroCheckout API into all sorts of Java-based applications. The SDK includes all interfaces that the GiroCheckout API by GiroSolution GmbH offers for the creation of requests and the processing of their responses. The SDK takes care of all the technical details, such as hash checksum calculation and thread-safe processing.

Complementing this documentation, you may find additional information both in the separate documentation package linked to in the download section, and on


Examples and inclusion

An important requirement for the usage of GiroCheckout is the creation of a user account and corresponding payment projects on

Important note regarding notify and redirect

GiroCheckout uses two parallel channels for the communication between the GiroCheckout server and the Shop: The notification (or notify for short) and the redirect. The notify is a server to server call in the background, whereas the redirect runs over the customer's browser, showing him the transaction result at the end. Both paths must function separately and independently from each other, in case one of them doesn't reach its destination. This way, the transaction is also successful if the notification happens to not arrive at the shop for whatever reason (so only the redirect could be successful) or if the customer interrupts the redirection to the shop site (so only the notify gets through). But of course a check is required on both sides whether the order has already been processed in the shop, in order to avoid a duplicate processing.

Please also see API Basics.

Including the Jar file

Start by adding the file girocheckout.jar to your build path.

Reference to your merchant account and your project

For all calls to the GiroCheckout API you require a reference to your merchant account and to the payment project used..

Merchant merchant = MerchantFactory.createMerchant(ihreHändlerID);
Project project = merchant.createProject(ihreProjektID, ihrProjektPasswort); 

Requests and responses

When sending a request towards GiroCheckout, begin by defining the data required for the transaction and then create the corresponding request on the Project object.

Example: Giropay payment

GiropayTransactionRequest request = project.createGiropayTransactionRequest(merchantTxId, amount, currency, purpose, bic, iban, info1Label, info2Label, info3Label, info4Label, info5Label, info1Text, info2Text, info3Text, info4Text, info5Text, urlRedirect, urlNotify);

Each request has an execute method that returns the corresponding response object.


GiropayTransactionResponse response = request.execute();
System.out.println("redirect: [" + response.getRedirect() + "]");
System.out.println("reference: [" + response.getReference() + "]"); 

Error handling

If there are problems during the communication with the GiroCheckout API, a GiroCheckoutProtocolException is thrown, which contains further information about the error. Furthermore, the GiroCheckoutException displays internal errors. Your can find a list of all error numbers here.

Result codes / payment result

The result of a payment is either contained in the notify/redirect URL or, in case of direct payments, in the correspnding response class. The code 4000 always signifies a successful transaction. All other codes give more information about what problem occurred. A list of all result codes can be found here.

Change Log

Version 1.2.5 - 31.05.2021

  • Refunds and captures for credit card, direct debit and maestro now accept the purpose field.
  • Refunds and captures for paydirekt now accept the parameter merchantReconciliationReferenceNumber.
  • Support for additional fields in Payment Page transactions:
    • timeout
    • certdata
    • otherpayments
    • tds2Address
    • tds2Postcode
    • tds2City
    • tds2Country
    • tds2Optional
    • mandateReference
    • mandateSignedOn
    • mandateReceiverName
    • mandateSequence
  • Support for the endpoint “project request” for Payment Pages.

Version 1.2.4 - 10.02.2021

  • Support for 3-D Secure 2.0, specifically the new corresponding credit card fields

Version 1.2.3 - 16.01.2020

  • Corrected problem with paydirekt

Version 1.2.2 - 09.08.2018

  • Added further parameters to Payment Page initialization

Version 1.2.1 - 28.03.2017

  • New: Direct debit cancellation
  • New: Creditcard cancellation
  • New: paydirekt cancellation
  • Introduced creditcard transaction type MoTo
  • Note: Calls to direct debit / creditcard transactions are no longer compatible to the previous release

Version 1.2.0 - 21.02.2017

  • Integration Paypage API
  • Integration Maestro API
  • Support for digital shopping carts in paydirekt
  • Note: paydirekt call is not compatible to version 1.1.x

Version 1.1.1 - 01.07.2016

  • Support for all payment methods of the GiroCheckout API
  • Added support for reservation, capture and refund
  • Note: Call for creditcard and direct debit not compatible with 1.0.x

Version 1.0.3 - 08.05.2015

  • New function getHash for hash validation when calling the Notify or Redirect URL

Version 1.0.2 - 27.01.2015

  • Improved error handling in GCGiropayBankstatusRequest

Version 1.0.1 - 21.01.2015

  • New mandatory field account holder for direct debit transactions without form service

Version 1.0.0 - 20.10.2014

  • Initial release
en/javasdk/start.txt · Last modified: 2021/05/31 18:08

Page Tools