~~NOCACHE~~
====== 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.

===== Anforderungen =====
  * 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 =====

{{:phpsdk:girocheckout_sdk_2.3.1.5.zip|Download GiroCheckout PHP SDK 2.3.1.5}}

==== Github ====
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.2.23), die normale Version ungerade (2.1.23).
[[https://github.com/girosolution/girocheckout_sdk|Hier finden Sie unser Github Repository]] und 
[[https://packagist.org/packages/girosolution/girocheckout-sdk|hier das package in packagist.org]].
===== Wichtiger Hinweis zu Notify und Redirect =====
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 [[girocheckout:general:start|API Grundlagen]].

=====Ordnerstruktur =====

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.

{{:phpsdk:sdk2.0_folders1.png?nolink&250|}}
===== Liste aller Aufrufarten =====

{{page>phpsdk:phpsdk:request_types_list&noheader&nofooter}}
===== API Aufruf einbinden =====

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

==== SDK laden ====
<code php>
8: require_once '../../GiroCheckout_SDK/GiroCheckout_SDK.php';
</code>

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

==== Zugangsdaten für Authentifizierung konfigurieren ====
<code php>
14: $merchantID = xxx;
15: $projectID = xxx;
16: $projectPassword = xxx;
</code>

Die benötigten Zugangsaten werden im [[https://www.girocockpit.de|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. 

==== API Aufruf durchführen ====
<code php>
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();
</code>

Um einen API-Aufruf durchzuführen, muss ein Request-Objekt mit der Aufrufart ([[phpsdk:phpsdk:request_types_list|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.

==== API Aufruf auswerten ====
<code php>
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:}
</code>

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.

===== Notification und Redirect Scripte einbinden =====

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

==== SDK laden ====
<code php>
8: require_once '../GiroCheckout_SDK/GiroCheckout_SDK.php';
</code>

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

==== Konfigurieren des Projektpassworts ====
<code php>
12: $projectPassword = xxx;
</code>

Das Passwort wird im giroCockpit bereitgestellt [[https://www.girocockpit.de|GiroCockpit]]. Es wird benötigt um einen Hash-Vergleich durchuführen und sicherzustellen, dass der Sender der Daten GiroCheckout ist.

==== Notification verarbeiten ====
<code php>
15: $notify = new GiroCheckout_SDK_Notify('giropayTransaction');
16: $notify->setSecret($projectPassword);
17: $notify->parseNotification($_GET);
</code>

Das Notify Objekt wird auf die gleiche Weise wie das request Objekt verwendet. Zunächst muss es instanziiert werden ([[phpsdk:phpsdk:request_types_list|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.

==== Notification auswerten ====

<code php>
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: }
</code>

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. 

^HTTP Statuscode    ^methode                        ^Beschreibung^
|200 (OK)           | //sendOkStatus()//            |Die Benachrichtigung wurde korrekt verarbeitet. |
|400 (Bad Request)  | //sendBadRequestStatus()//    |Der Händler hat die Benachrichtigung nicht verarbeitet, möchte aber auch nicht erneut benachrichtigt werden. |
|Alle anderen       | //sendOtherStatus()//         |Die Benachrichtigung wird max. 10 Mal alle 30 Minuten wiederholt, bis der Händler den HTTP Statuscode 200 oder 400 zurückgibt. |

===== Umstellen des Server Endpoints =====
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:
<code php>
apache_setenv( "GIROCHECKOUT_SERVER", "https://anderer.endpoint.de" );
</code>
2) In der Linux-Kommandozeile (z.B. für die Ausführung der SDK-Beispiele ohne Browser):
<code sh>
export GIROCHECKOUT_SERVER=https://anderer.endpoint.de
</code>
3) In der Apache-Konfiguration (innerhalb des VirtualHost-Abschnitts):
<code>
SetEnv GIROCHECKOUT_SERVER "https://anderer.endpoint.de"
</code>

===== Betrieb über einen Proxy-Server =====
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:

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

===== Debugging =====
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:

<code php>
define('__GIROCHECKOUT_SDK_DEBUG__',true);
</code>

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.

==== Logfile lesen ====

Die Logfile ist in verschiedene Sektionen aufgeteilt

^Sektion^Beschreibung^Fehlerquelle^
|start | enthält Zeitstempel des Aufrufs |  |
|PHP ini| enthält Informationen zu PHP, cURL und SSL | cURL oder SSL ist nicht aktiviert |
|transaction | enthält den Namen des API Aufrufs der verwendet wird |  |
|params set| enthält alle übergebenen Parameter | Parameter weichen von API-Beschreibung ab und fehlen |
|cURL request| enthält alle zu sendenden Parameter sowie cURL info Informationen zum Sendeaufruf |  |
|cURL reply| cURL Informationen zur Serverantwort |  |
|reply params| alle Parameter der Serverantwort |  |
|notify input| Informationen zum Notify Aufruf (Parameter, Zeitstempel) |  |
|reply params| Informationen zur verwendeten Antwortmethode |  |
|exception | enthält Fehlerbeschreibung |  |

==== Setzen einer Zertifikats Datei ====
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:

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

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

<code php>
$request->setSslVerifyDisabled();
</code>

===== Changelog =====
{{page>phpsdk:changelog}}