Das GiroCockpit SDK dient zur erleichterten Einbindung der GiroCheckout API. Das SDK beinhaltet sämtliche zur Verfügung stehenden Schnittstellen der GiroSolution AG, für die Anbindung an den GiroCheckout. Zu jedem Schnittstellenaufruf sind zusätzlich Beispielscripte vorhanden.

• Das SDK nutzt für die Serverkommunikation die cUrl Extension.
• Alle Daten müssen UTF-8 kodiert angegeben werden. Das SDK kümmert sich nicht um die Umwandlung.
• PHP >= 5.2

Download GiroCheckout PHP SDK 2.1.0

Der Ordner „examples“ enthält API Beispielscripte. Darunter jeweils ein Script für jeden API Aufruf sowie Beispiele für Notify und Redirect. Der Ordner „GiroCheckout_SDK“ enthält unter anderem die GiroCheckout_SDK.php, welche per include oder require eingebunden werden muss. Darin werden alle notwendigen Dateien geladen um das SDK verwenden zu können.

Am Beispielcode der Datei „examples/giropay/giropayTransction.php“ wird ein API Aufruf exemplarisch näher erläutert.

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

Die Datei „GiroCheckout_SDK.php“ muss an geeigneter Stelle eingebunden werden, damit die für alle Schnittstellenaufrufe notwendigen Quellen vorhanden sind.

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

Die benötigten Zugangsaten werden im GiroCockpit bereitgestellt. Dabei muss darauf geachtet werden, dass die Daten dem richtigen Projekt entnommen werden. Beispielsweise funktioniert ein „giropayTransaction“ Aufruf nur mit einer korrekten giropay Projekt-ID.

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

Um einen API-Aufruf durchzuführen, muss ein Request-Objekt mit der Aufrufart (Liste aller Aufrufarten) instanziiert werden. Dem Request-Objekt wird durch die Methode setSecret($projectPassword) das Passwort zur hashgenerierung mitgeteilt. Über die Methode addParam() muss jeder Parameter der Anfrage an das Request-Objekt übergeben werden. ACHTUNG: der hash muss nicht übergeben werden, das SDK kümmert sich automatisch um die korrekte Hashgenerierung.

Um eine Anfrage an GiroCheckout abzusetzen muss die Request-Methode submit() aufgerufen werden.

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:}

Die Methode requestHasSucceeded() gibt true zurück, wenn der Aufruf ohne Fehlermeldung erfolgte. Sie kann verwendet werden, um zu prüfen, ob der Schnittstellenaufruf erfolgreich war. Es werden je nach Schnittstelle die definierten Rückgabeparameter durch die Methode getResponseParam() bereitgestellt.

Durch den Aufruf der Methode redirectCustomerToPaymentProvider() wird der Käufer automatisch an die im Paramter redirect übermittelte URL weitergeeitet.

Erfolgte ein Fehler wird über den „response code“ Parameter (rc) der jeweilige Fehlercode übermittelt. Die Methode getResponseMessage() liefert eine Fehlerbeschreibung in einer unterstützten Sprache.

Am Beispielcode der Datei „examples/notification.php“ wird ein API Aufruf exemplarisch näher erläutert.

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

Die Datei „GiroCheckout_SDK.php“ muss an geeigneter Stelle eingebunden werden, damit die für alle Schnittstellenaufrufe notwendigen Quellen vorhanden sind.

12: $projectPassword = xxx;

Das Passwort wird im giroCockpit bereitgestellt GiroCockpit. Es wird benötigt um einen Hash-Vergleich durchuführen und sicherzustellen, dass der Sender der Daten GiroCheckout ist.

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

Das Notify Objekt wird auf die gleiche Weise wie das request Objekt verwendet. Zunächst muss es instanziiert werden (Liste aller Aufrufarten) und das Projektpasswort muss übergeben werden. Bitte achten Sie darauf, dass das Passwort zum Projekt des Aufrufs gehört.

Anschließend muss ein Array mit den Variablen des Aufrufs an die Methode parseNotification() übergeben werden.

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: }

Die Methode paymentSuccessful() gibt true zurück, wenn die Zahlung erfolgreich war. Im Falle einer giropay-ID Transaktion liefert das Ergebnis des Alterschecks die Methode avsSuccessful(). Alle laut Schnittstelle definierten Antwortparameter können durch die Methode getResponseParam() ausgelesen werden.

Die Methoden sendOkStatus(), sendBadRequestStatus() und sendOtherStatus() liefern den passenden Header zurück.

In Einzelfällen kann es vorkommen, dass Sie für die Entwicklung bzw. die Tests auf einen anderen Server zugreifen müssen als den Default-Server https://payment.girosolution.de. Sollten Sie von Girosolution einen anderen Endpoint erhalten haben, können Sie diesen temporär überschreiben. Hierfür stehen Ihnen folgende drei Möglichkeiten zur Verfügung:

1) Im PHP Code:

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

2) In der Linux-Kommandozeile (z.B. für die Ausführung der SDK-Beispiele ohne Browser):

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

3) In der Apache-Konfiguration (innerhalb des VirtualHost-Abschnitts):

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

Das SDK bietet eine Möglichkeit den Ablauf eines API Aufrufs zu debuggen. Dazu muss eine Konstante in PHP, vor dem Einbinden des SDKs, definiert und auf „true“ gesetzt werden:

define('__GIROCHECKOUT_SDK_DEBUG__',true);

Das SDK generiert eine Logfile und legt sie standardmäßig unter „GiroCheckout_PHP_SDK/log“ ab. Der Webserver muss Schreibzugriff auf diesen Ordner haben. Der Debug Modus sollte ausschließlich während der Fehlersuche aktiviert sein. Im Livebetrieb sollte er deaktiviert sein und die Logs entfernt werden.

Die Logfile ist in verschiedene Sektionen aufgeteilt

In einer Windows Serverumgebung kann es vorkommen, dass cURL das übermittelte SSL-Zertifikat nicht prüfen kann. Diesbezüglich sollte ein Zertifikat explizit an das SDK übergeben werden. Dazu ist folgender Aufruf, vor dem $request→submit() Aufruf, nötig:

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

Zu Testzwecken kann die Zertifikatsprüfung komplett abgeschaltet werden. Dies ist im Livebetrieb nicht zu empfehlen.

$request->setSslVerifyDisabled();

• Integration Blue Code API
• Korrektur Bug bei SOFORT Überweisung: Falscher Endpoint

• Einige Beispiele überarbeitet und korrigiert

• Pflichtfelder dürfen nun nicht mehr leer sein.
• Einige Beispiele überarbeitet

• Giropay+Giropay-ID ist nun in Giropay integriert, nur noch eine Klasse.
• Beispiel für Giropay+Giropay-ID verbessert.

• Lastschrift um Parameter type erweitert (AUTH, SALE) (GiroCheckout_SDK_DirectDebitTransaction)
• Lastschrift Capture implementiert (GiroCheckout_SDK_DirectDebitCapture)
• Lastschrift Refund implementiert (GiroCheckout_SDK_DirectDebitRefund)
• iDEAL Refund implementiert (GiroCheckout_SDK_IdealPaymentRefund)
• Kreditkarte um Parameter type erweitert (AUTH, SALE) (GiroCheckout_SDK_CreditCardTransaction)
• Kreditkarte Capture implementiert (GiroCheckout_SDK_CreditCardCapture)
• Kreditkarte Refund implementiert (GiroCheckout_SDK_CreditCardRefund)
• Paydirekt Transaktion implementiert (AUTH, SALE) (GiroCheckout_SDK_PaydirektTransaction)
• Paydirekt Capture implementiert (GiroCheckout_SDK_PaydirektCapture)
• Paydirekt Refund implementiert (GiroCheckout_SDK_PaydirektRefund)
• Giropay: Feld BIC ist jetzt optional (GiroCheckout_SDK_GiropayTransaction u. GiroCheckout_SDK_GiropayTransactionWithGiropayID)
• EPS: Feld BIC ist jetzt optional (GiroCheckout_SDK_EpsTransaction)
• EPS: Neue Logos eingebunden
• Sofortüberweisung implementiert (GiroCheckout_SDK_SofortUwTransaction)
• Funktion GiroCheckout_SDK_Tools::getCreditCardLogoName() korrigiert und angepasst, neue Logos für alle KK-Kombinationen