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 http://api.girocheckout.de.

Download GiroCheckout Java SDK 2.5.2
Download GiroCheckout Java SDK Documentation

An important requirement for the usage of GiroCheckout is the creation of a user account and corresponding payment projects on https://www.girocockpit.de.

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.

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

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); 

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.

Example:

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

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.

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.

• Bugfix in hash calculation.

• Implemented order secured for giropay (parameters secureAuth and secureAuthUntil).
• Refund, capture and void implemented for new giropay
• Removed now unsupported payment methods: Paydirekt, giropay ID,
• Removed now unused end points and examples: giropay AVS/KVS, Bankstatus
• Renamed parameter customerId to giropayCustomerId for giropay
• New parameter customerId for giropay

• Solved problem with URLs (upper/lower case differences)
• Added optional parameter qrcodeReturn which causes the initialization to returns the payment link as a base64 encoded QR code in the field qrcode.

• epsBankStatus: removed bankcode field from response
• New endpoint epsSenderInfo
• New endpoint idealSenderInfo
• New endpoint creditCardSenderInfo
• New endpoint directDebitSenderInfo
• New endpoint directGetPKN
• New endpoint paypageCapture
• New endpoint paypageRefund
• New endpoint paypalCapture
• New endpoint paypalRefund
• New endpoint bluecodeRefund
• creditCardTransaction: removed indicator field
• creditCardVoid: added new field referenceParent to response
• directDebitCapture: removed merchantTxId field from response
• directDebitRefund: removed merchantTxId field from response
• directDebitVoid: added new fields referenceParent, amount and currency to response
• paydirektVoid: added new field referenceParent to response
• getTransactionTool: removed merchantTxId field from response
• bluecodeTransaction: removed fields branch, slip, slipDateTime and recurringid from response

• Changed SDK version number to match PHP SDK
• Replaced iDeal logos with new versions
• Updated list of return and error codes
• New griopay API: Renamed optional parameter merchantReconciliationReferenceNumber to merchantOrderReferenceNumber.
• Payment Page: Renamed optional parameter paydirektMerchantReconciliationReferenceNumber to paydirektMerchantOrderReferenceNumber.
• Added support for new optional Kassenzeichen parameter for all payment methods
• Support for new giropay.
• Support for Paypal reservation (auth) and capture.
• Support for Paypal refund.
• Support for refund, capture and info for payment page transactions using the payment page reference.
• Support for the API call senderInfo
• Purpose parameter in credit card capture
• Introduced new paypage parameter informationText.
• Replaced old paydirekt logos with new giropay/paydirekt ones.
• Added the fields for direct debit mandates to payment page.

• 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.

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

• Corrected problem with paydirekt

• Added further parameters to Payment Page initialization

• 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

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

• 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

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

• Improved error handling in GCGiropayBankstatusRequest

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

• Initial release