User Tools

Site Tools


Translations of this page:
en:phpsdk:start

Table of Contents

PHP SDK

The GiroCockpit SDK allows a simple implementation of the GiroCheckout API. The SDK includes all API calls provided by GiroCheckout. For every API there is an example script in the examples section.

Requirements

  • The SDK uses the cURL extension for server communication.
  • All data must be given in UTF-8. The SDK does not take care of the conversion.
  • PHP >= 5.2

Download

Github

GiroCheckout SDK is now also available and installable via composer, packagist and Github. The version numbers of both releases differ in the second number: The Github version has an even number (such as 2.6.1), the normal version an uneven one (2.5.1). Find our github repository here and our package on packagist.org here.

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.

Folders

The folder “examples” includes any example script. Among them there is an example for every API call as well as a notification and a redirect script. The folder “GiroCheckout_SDK” contains the GiroCheckout_SDK.php, which needs to be included in order to use the SDK functionalities.

List of all request types (Request & Notify)

API documentation request type object name
eps
check eps bank status epsBankstatus GiroCheckout_SDK_EpsBankstatus()
eps Bankenabfrage epsIssuerList GiroCheckout_SDK_EpsIssuerList()
eps Transaktion epsTransaction GiroCheckout_SDK_EpsTransaction()
giropay
giropay transaction GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_TRANSACTION: “giropayTransaction“ GiroCheckout_SDK_GiropayTransaction()
giropay Capture GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_CAPTURE: “giropayCapture” GiroCheckout_SDK_GiropayCapture()
giropay Refund GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_REFUND: “giropayRefund” GiroCheckout_SDK_GiropayRefund()
giropay Void GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_VOID: “giropayVoid” GiroCheckout_SDK_GiropayVoid()
giropay sender information GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_SENDERINFO: “giropaySenderInfo” GiroCheckout_SDK_GiropaySenderInfo()
iDEAL
iDEAL get issuer list idealIssuerList GiroCheckout_SDK_IdealIssuerList()
iDEAL transaction idealPayment GiroCheckout_SDK_IdealPayment()
credit card
credit card payment creditCardTransaction GiroCheckout_SDK_CreditCardTransaction()
get PKN creditCardGetPKN GiroCheckout_SDK_CreditCardGetPKN()
recurring credit card payment creditCardRecurringTransaction GiroCheckout_SDK_CreditCardRecurringTransaction()
credit card void creditCardVoid GiroCheckout_SDK_CreditCardVoid()
direct debit
direct debit without payment page directDebitTransaction GiroCheckout_SDK_DirectDebitTransaction()
direct debit payment page directDebitTransactionWithPaymentPage GiroCheckout_SDK_DirectDebitTransactionWithPaymentPage()
direct debit void directDebitVoid GiroCheckout_SDK_DirectDebitVoid()
Maestro
Maestro payment maestroTransaction GiroCheckout_SDK_MaestroTransaction()
Maestro capture maestroCapture GiroCheckout_SDK_MaestroCapture()
Maestro refund maestroRefund GiroCheckout_SDK_MaestroRefund()
Payment Page Transaktion
Payment through Payment Page paypageTransaction GiroCheckout_SDK_PaypageTransaction()
Project request paypageProjects GiroCheckout_SDK_PaypageProjects()
Sofort.
Sofort payment sofortuwTransaction GiroCheckout_SDK_SofortUwTransaction()
PayPal
PayPal transaction paypalTransaction GiroCheckout_SDK_PaypalTransaction()
tools
get transaction information getTransactionTool GiroCheckout_SDK_Tools_GetTransaction()

Implementation of an API call

This implementation example is based on the “examples/giropay/giropayTransction.php” file.

Load SDK

8: require_once '../../GiroCheckout_SDK/GiroCheckout_SDK.php';

The file “GiroCheckout_SDK.php” has to be included in an appropriate place, to use API functionalities.

Configure data for authentication

14: $merchantID = xxx;
15: $projectID = xxx;
16: $projectPassword = xxx;

These data are provided in the GiroCockpit. Ensure that the used project ID is correct and belongs to an API call. For example you can only use a giropay project ID for an “giropayTransaction” request.

API call

20: $request = new GiroCheckout_SDK_Request('giropayTransaction');
21: $request->setSecret($projectPassword);
22: $request->addParam('merchantId',$merchantID)
23:         ->addParam('projectId',$projectID)
24:         ->addParam('merchantTxId',1234567890)
25:         ->addParam('amount',100)
26:         ->addParam('currency','EUR')
27:         ->addParam('purpose','Beispieltransaktion')
28:         ->addParam('bic','TESTDETT421')
29:         ->addParam('info1Label','Ihre Kundennummer')
30:         ->addParam('info1Text','0815')
21:         ->addParam('urlRedirect','https://www.my-domain.de/girocheckout/redirect-giropay')
22:         ->addParam('urlNotify','https://www.my-domain.de/girocheckout/notify-giropay')
23:     //the hash field is auto generated by the SDK
24:         ->submit();

To perform a request there has to be instantiated and configurated a request object (list of all request types). The project password has to be given to the request object by calling the setSecret() method. It is used for the hash generation. Any API parameters, exept for the hash param, have to be set to the request object by calling addParam().

The method submit() performs the API call to GiroCheckout.

API response

38: if($request->requestHasSucceeded())
39: {
40:   $request->getResponseParam('rc');
41:   $request->getResponseParam('msg');
42:   $request->getResponseParam('reference');
43:   $request->getResponseParam('redirect');
44:
45:   $request->redirectCustomerToPaymentProvider();
46: }
47:
48: /* if the transaction did not succeed update your local system, get the responsecode and notify the customer */
49: else {
50:   $request->getResponseParam('rc');
51:   $request->getResponseParam('msg');
52:   $request->getResponseMessage($request->getResponseParam('rc'),'DE');
53:}

The method requestHasSucceeded() returns true, if the request was successfully performed. Any API response parameters are provided by the getResponseParam() method. The customer redirection can be performet by calling the redirectCustomerToPaymentProvider() method. The buyer will be redirected to the URL given in the redirect parameter.

If an eror occured there is the error code stored in the rc param. The method getResponseMessage() delivers a translated error message in a supporded language.

Notification und Redirect scripts

This implementation example is based on the “examples/notification.php” file.

load SDK

8: require_once '../GiroCheckout_SDK/GiroCheckout_SDK.php';

The file “GiroCheckout_SDK.php” has to be included in an appropriate place, to use API functionalities.

Configure data for authentication

12: $projectPassword = xxx;

The password is provided in the GiroCockpit. It is for the hash comparison, to ensure that GiroCheckout sends you Data.

Process notification

$notify = new GiroCheckout_SDK_Notify('giropayTransaction');
$notify->setSecret($projectPassword);
$notify->parseNotification($_GET);

The notification Object will work the same way as the Request Object. At first it has to be instantiated with the transaction type (list of all request types) and configured with the password.

Afterwards there has to be passed an array including the request params to the parseNotification() method.

Handle notification

21: if($notify->paymentSuccessful()) {
22:   $notify->getResponseParam('gcReference');
23:   $notify->getResponseParam('gcMerchantTxId');
24:   $notify->getResponseParam('gcBackendTxId');
25:   $notify->getResponseParam('gcAmount');
26:   $notify->getResponseParam('gcCurrency');
27:   $notify->getResponseParam('gcResultPayment');
28: 
29:   if($notify->avsSuccessful()) {
30:     $notify->getResponseParam('gcResultAVS');
31:   }
32:
33:   $notify->sendOkStatus();
34:   exit;
35: }
36: else {
37:   $notify->getResponseParam('gcReference');
38:   $notify->getResponseParam('gcMerchantTxId');
39:   $notify->getResponseParam('gcBackendTxId');
40:   $notify->getResponseParam('gcResultPayment');
41:
42:   $notify->sendOkStatus();
43:   exit;
44: }

The method paymentSuccessful() returns true, if the payment has succeeded. Due to a giropay-ID transaction the method avsSuccessful() deliveres the result of the age verification. Any response parameter can be received throught the getResponseParam() method.

sendOkStatus(), sendBadRequestStatus() and sendOtherStatus() deliver the appropriate Header.

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

Changing the Server Endpoint

In special cases it may be necessary to access a different Server for development and tests than the default https://payment.girosolution.de. Should you have received another endpoint URL from Girosolution, there is a way of overriding the default server.

You may do this in one of three ways:

1) In your PHP code:
Via the environment:

apache_setenv( "GIROCHECKOUT_SERVER", "https://anderer.endpoint.de" );

Or directly through the setServer() method:

try {
  $request = new GiroCheckout_SDK_Request( GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GIROPAY_TRANSACTION );
  $request->setSecret($projectPassword);
 
  $request->setServer( 2 ); // Set server to 2=dev, 1 is prod
 
  $request->addParam('merchantId',$merchantID)
          ->addParam(...)
          ->submit();
}
catch(Exception $e) {
  // Handle exception
}

2) On the Linux command line (e.g. for executing the SDK examples without a browser):

export GIROCHECKOUT_SERVER=https://other.endpoint.de

3) In the Apache configuration (within the VirtualHost section):

SetEnv GIROCHECKOUT_SERVER "https://other.endpoint.de"

Operation via a proxy server

It is possible to operate the server communication via a proxy, if your environment requires to do so. To implement this, include the following code and modify the parameters accordingly, before the GiroCheckout_SDK_Request::submit() function is called:

  $Config = GiroCheckout_SDK_Config::getInstance();
  $Config->setConfig('CURLOPT_PROXY', 'http://myproxy.com'):
  $Config->setConfig('CURLOPT_PROXYPORT', 9090);
  $Config->setConfig('CURLOPT_PROXYUSERPWD', 'myuser:mypasswd');

Debugging

The SDK contains the opportunity to debug an API call. Therefor there has to be defined a constant which has to be set to “true”:

define('__GIROCHECKOUT_SDK_DEBUG__',true);

Now the SDK will write a log file which is located under “GiroCheckout_PHP_SDK/log” by default. The webserver needs to have writing permissions to this folder. The debug mode should only be used during debug issues and should be deactivated afterwards.

Reading logfile

The logfile is segmented into different sections:

SectionDescriptionCommon issues
start includes the timestamp when the script was loaded
PHP ini provides information about PHP, cURL and SSL cURL or SSL is not activated
transaction shows the used API call
params set shows any parameters that were given to the request object parameters are missing
cURL request includes any parameters that are sent to GiroCheckout
cURL reply cURL information about the server reply
reply params any parameters in the server's reply
notify input information about the notify call (parameters, timestamp)
reply params information about the used reply method
exception includes the error description

Set certificate file

Under an Windows server environment it might happen that cURL is not able to check the SSL certrificate. Then it will be necessary to give cURL an specific certificate file. The SDK provides the possibility of setting a local certificate file. Therefor the following code is needed bevore the $request→submit() method is called:

$request->setSslCertFile('path/to/certificate');

For testing purposes the certificate validation can be disabled. Please do not use this in your live environment.

$request->setSslVerifyDisabled();

Changelog

Version 2.5.1 / 2.6.1 (GIT) - 17.05.2024

  • Implemented order secured for giropay (parameters secureAuth and secureAuthUntil).

Version 2.5.0 / 2.6.0 (GIT) - 14.05.2024

  • 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

Version 2.3.14 / 2.4.14 - 25.07.2023

  • Renamed parameter customerId to giropayCustomerId for giropay

Version 2.3.13 / 2.4.13 - 05.06.2023

  • New parameter customerId for giropay

Version 2.3.12 / 2.4.12 - 17.02.2023

  • Added support for ApplePay.

Version 2.3.11 / 2.4.11 - 24.01.2023

  • Added optional parameter qrcodeReturn which causes the initialization to returns the payment link as a base64 encoded QR code in the field qrcode.

Version 2.3.10 / 2.4.10 - 14.11.2022

  • Renamed internal parameter.

Version 2.3.9 / 2.4.9 - 14.09.2022

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

Version 2.3.7 / 2.4.7 - 01.07.2022

  • Added support for new optional Kassenzeichen parameter for all payment methods

Version 2.3.6 / 2.4.6 - 15.06.2022

  • Bugfix regarding handling of mandatory fields.

Version 2.3.5 / 2.4.5 - 20.04.2022

  • Support for new giropay.

Version 2.3.4 / 2.4.4 - 25.02.2022

  • Support for Paypal reservation (auth) and capture.

Version 2.3.3 / 2.4.3 - 16.02.2022

  • Support for Paypal refund.

Version 2.3.2 / 2.4.2 - 31.01.2022

  • Support for refund, capture and info for payment page transactions using the payment page reference.
  • Fix in handling of error when capture, refund or void fails.

Version 2.3.1.11 / 2.4.1.11 - 11.11.2021

  • Support for the API call senderInfo
  • Purpose parameter in credit card capture

Version 2.3.1.9 / 2.4.1.9 - 21.07.2021

  • Compatibility with PHP up to 7.4.x

Version 2.3.1.8 / 2.4.1.8 - 06.07.2021

  • Introduced new paypage parameter informationText.

Version 2.3.1.7 / 2.4.1.7 - 04.06.2021

  • Replaced old paydirekt logos with new giropay/paydirekt ones.

Version 2.3.1.6 / 2.4.1.6 - 27.04.2021

  • Added the fields for direct debit mandates to payment page.

Version 2.3.1.5 / 2.4.1.5 - 22.01.2021

  • Added the fields for donation certificate info to direct debit payment call.

Version 2.3.1.4 / 2.4.1.4 - 18.12.2020

  • Removed email parameter for 3-D Secure 2.0.

Version 2.3.1.3 / 2.4.1.3 - 11.12.2020

  • Added error codes for 3-D Secure 2.0 cases.
  • Added support for 3-D Secure 2.0 to payment page calls.
  • Fixed a bug in the new function testApiCredentials.

Version 2.3.1 / 2.4.1 - 25.11.2020

  • Added new function for testing API credentials: GiroCheckout_SDK_Tools::testApiCredentials().
  • Added optional fields for 3-D Secure 2.0 to creditcard API (available on backend from December 2020)

Version 2.1.33 / 2.2.33 - 31.08.2020

  • New parameter timeout in Payment Page API.

Version 2.1.31 / 2.2.31 - 17.01.2020

  • Added support for parameter otherpayments in Payment Page.

Version 2.1.30 / 2.2.30b - 07.12.2019

  • Added parameter to Request class to allow for easier use of development server.
  • Fixed Paydirekt cart class to make sure numeric values are not returned as strings in the JSON.

Version 2.1.29 / 2.2.29 - 18.10.2019

  • Added support for the new credit card iframe form calls initform and finalizeform

Version 2.1.28 / 2.2.28 - 06.09.2019

  • Provides a function to obtain the payment method logo name
  • Introduces constants for the transaction types

Version 2.1.27 / 2.2.27 - 21.08.2019

  • Added parameter certdata for donation certificate in paypage service.
  • New call for paypage donation certificate implemented.

Version 2.1.26 / 2.2.26 - 09.07.2019

  • Corrected Bluecode spelling
  • Added check if function curl_exec is present and enabled

Version 2.1.25 / 2.2.25 - 28.05.2019

  • Finalized support for Bluecode e-commerce payment method

Version 2.1.24 / 2.2.24 - 12.04.2019

  • Return better error messages when authentication data is invalid.
  • Improved error returns and better handling of empty return values.

Version 2.1.23 - 13.12.2018

  • Bugfix in Paydirekt: Cart did not accept items with a value of 0,00 EUR.
  • 2 new optional parameters securedAuth and securedAuthUntil for secured authorizations in Paydirekt (this function is not yet available in Paydirekt production) (see API).
  • First Github version of the SDK is available.

Version 2.1.22 - 16.08.2018

  • New optional parameter 'single' that controls the repeatability of the payment link (see API).

Version 2.1.21 - 18.07.2018

  • New optional Parameters for paydirekt shipping address in payment page
  • Minor corrections in example files

Version 2.1.20 - 06.07.2018

  • Bugfix in Paypage init call: Parameter description is now optional.
  • CPSP support for giropay

Version 2.1.19 - 05.01.2018

  • Support for the field gcObvName in giropay.

Version 2.1.18 - 22.11.2017

  • Support for the new orderid parameter for payment pages.

Version 2.1.17 - 04.11.2017

  • Refunds for credit card, direct debit and maestro now accept a parameter for the purpose.

Version 2.1.16 - 19.10.2017

  • Fixed bug that prevented the field mandateReference to be properly read from the direct debit with form service response.

Version 2.1.15 - 04.09.2017

  • New Paypage call for requesting a list of GiroCockpit projects and a new projects parameter in the initialization call of a paypage transaction.
  • New logo for Sofort (now Klarna).

Version 2.1.14 - 20.07.2017

  • URL parameters are now optional for paypage transactions.

Version 2.1.13 - 17.07.2017

  • Added missing notification parameters for paypage.

Version 2.1.12 - 13.06.2017

  • New logos for direct debit.

Version 2.1.11 - 30.05.2017

  • Connection Timeout for server connection increased generally from 3 to 15 seconds.

Version 2.1.10 - 11.04.2017

  • Re-included functions for Windows environments setSslCertFile() and setSslVerifyDisabled().

Version 2.1.9 - 24.03.2017

  • Bugfix in generation of credit card logo filename
  • Implemented support for Void for credit card, direct debit and Paydirekt

Version 2.1.8 - 02.03.2017

  • Enhanced statistics information on used SDK versions (internal change)

Version 2.1.7 - 14.02.2017

  • For Paydirekt: Support for new cart types ANONYMOUS_DONATION and AUTHORITIES_PAYMENT implemented.

Version 2.1.6 - 10.02.2017

  • Restored backwards compatibility with PHP 5.2.x
  • Parameter issuer for iDEAL is not mandatory anymore (bank will be inquired if missing. But beware: this must be enabled in GiroCockpit.)

Version 2.1.5 - 02.02.2017

Version 2.1.4 - 18.01.2017

  • Corrections in error message texts

Version 2.1.3 - 10.01.2017

  • Bugfix CURL Helper
  • New Logo files

Version 2.1.2 - 09.01.2017

  • Integration of Paypage API
  • Integration of Maestro API
  • Correction date format in log file
  • Text corrections
  • New logos MasterCard, JCB
  • Fix UTF8 bug in Paydirekt
  • Support digital cart in Paydirekt

Version 2.1.0 - 31.08.2016

  • Integration of Blue Code API
  • Corrected bug in SOFORT Überweisung: Wrong Endpoint

Version 2.0.3 - 29.06.2016

  • Improved and corrected some examples.

Version 2.0.2 - 08.06.2016

  • Mandatory fields may now not be empty anymore.
  • Improved some examples.

Version 2.0.1 - 11.05.2016

  • Giropay+Giropay-ID is now integrated into Giropay, only one class.
  • Examples for Giropay+Giropay-ID improved.

Version 2.0.0 - 09.05.2016

  • Direct debit has new parameter “type” (AUTH, SALE) (GiroCheckout_SDK_DirectDebitTransaction)
  • Direct debit Capture implemented (GiroCheckout_SDK_DirectDebitCapture)
  • Direct debit Refund implemented (GiroCheckout_SDK_DirectDebitRefund)
  • iDEAL Refund implemented (GiroCheckout_SDK_IdealPaymentRefund)
  • Credit card has new paramter “type” (AUTH, SALE) (GiroCheckout_SDK_CreditCardTransaction)
  • Credit card Capture implemented (GiroCheckout_SDK_CreditCardCapture)
  • Credit card Refund implemented (GiroCheckout_SDK_CreditCardRefund)
  • Paydirekt Transaction implemented (AUTH, SALE) (GiroCheckout_SDK_PaydirektTransaction)
  • Paydirekt Capture implemented (GiroCheckout_SDK_PaydirektCapture)
  • Paydirekt Refund implemented (GiroCheckout_SDK_PaydirektRefund)
  • Giropay: Field BIC is now optional (GiroCheckout_SDK_GiropayTransaction and GiroCheckout_SDK_GiropayTransactionWithGiropayID)
  • EPS: Field BIC is now optional (GiroCheckout_SDK_EpsTransaction)
  • EPS: Included new logos
  • Sofortüberweisung implemented (GiroCheckout_SDK_SofortUwTransaction)
  • Function GiroCheckout_SDK_Tools::getCreditCardLogoName() was corrected and adapted, new logos for all card combinations
2017/01/09 18:54 · michaelheumann
en/phpsdk/start.txt · Last modified: 2024/05/17 19:34

Page Tools