PHP SDK

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

GiroCheckout SDK ist nun auch über Composer, Packagist und Github installierbar. Die Versionsnummern beider Versionen unterscheiden sich in der 2. Ziffer: Die Github-Version ist hier gerade (z.B. 2.6.1), die normale Version ungerade (2.5.1). Hier finden Sie unser Github Repository und hier das package in packagist.org.

GiroCheckout verwendet zwei parallele Kanäle zur Kommunikation zwischen dem GiroCheckout-Server und dem Shop: Die Notification (oder Notify) und das Redirect. Das Notify ist ein Server-to-Server-Aufruf im Hintergrund, wobei das Redirect über den Kundenbrowser läuft und diesem am Ende das Transaktionsergebnis anzeigt.

Beide Kommunikationswege sollten unabhängig voneinander funktionieren, falls eine der beiden Meldungen nicht ankommt. Auf diese Weise ist die Transaktion auch erfolgreich, wenn die Notification aus irgendeinem Grunde nicht ankommen konnte (also nur der Redirect erfolgen konnte), oder wenn der Kunde die Rückleitung zum Shop unterbricht (also nur ein Notify ankam). Aber natürlich sollte an beiden Stellen ein Check erfolgen, ob die Bestellung bereits im Shop abgearbeitet wurde, damit das nicht doppelt geschieht.

Siehe dazu auch API Grundlagen.

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:
Über die Umgebung:

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

Oder direkt über die Methode setServer():

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

Es ist möglich, die Server-Kommunikation über einen Proxy durchzuführen, falls Ihre Umgebung dies erforderlich macht. Binden Sie dazu folgenden Code ein und passen die Parameter entsprechend an, bevor die GiroCheckout_SDK_Request::submit()-Funktion aufgerufen wird:

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

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