PHP SDK

Inhalt

• Anforderungen
• Download
  • Github
• Wichtiger Hinweis zu Notify und Redirect
• Ordnerstruktur
• Liste aller Aufrufarten
• API Aufruf einbinden
  • SDK laden
  • Zugangsdaten für Authentifizierung konfigurieren
  • API Aufruf durchführen
  • API Aufruf auswerten
• Notification und Redirect Scripte einbinden
  • SDK laden
  • Konfigurieren des Projektpassworts
  • Notification verarbeiten
  • Notification auswerten
• Umstellen des Server Endpoints
• Betrieb über einen Proxy-Server
• Debugging
  • Logfile lesen
  • Setzen einer Zertifikatsdatei
• Changelog

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

Download GiroCheckout PHP SDK 2.5.13

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.6.1), die normale Version ungerade (2.5.1). Hier finden Sie unser Github Repository und 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 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.

Liste aller Aufrufarten

API-Dokumentation	Aufrufstring	Objektname
Kreditkarte
Kreditkartenzahlung	creditCardTransaction	GiroCheckout_SDK_CreditCardTransaction()
Kreditkarte Capture	creditCardCapture	GiroCheckout_SDK_CreditCardCapture()
Kreditkarte Erstattung	creditCardRefund	GiroCheckout_SDK_CreditCardRefund()
PKN Abfragen	creditCardGetPKN	GiroCheckout_SDK_CreditCardGetPKN()
wiederkehrende Kartenzahlung	creditCardRecurringTransaction	GiroCheckout_SDK_CreditCardRecurringTransaction()
Kreditkarte Stornierung	creditCardVoid	GiroCheckout_SDK_CreditCardVoid()
Lastschrift
Lastschrift ohne Zahlformular	directDebitTransaction	GiroCheckout_SDK_DirectDebitTransaction()
Lastschrift mit Zahlformular	directDebitTransactionWithPaymentPage	GiroCheckout_SDK_DirectDebitTransactionWithPaymentPage()
Lastschrift Capture	directDebitCapture	GiroCheckout_SDK_DirectDebitCapture()
Lastschrift Erstattung	directDebitRefund	GiroCheckout_SDK_DirectDebitRefund()
Lastschrift Stornierung	directDebitVoid	GiroCheckout_SDK_DirectDebitVoid()
Payment Page Transaktion
Zahlung über Payment Page	paypageTransaction	GiroCheckout_SDK_PaypageTransaction()
Projektabfrage	paypageProjects	GiroCheckout_SDK_PaypageProjects()
PayPal
PayPal Transaktion	paypalTransaction	GiroCheckout_SDK_PaypalTransaction()
Direktüberweisung
Direktüberweisung Zahlung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_DIREKTUBW_TRANSACTION: „direktubwTransaction“	GiroCheckout_SDK_DirektubwTransaction()
Apple Pay
Apple Pay Zahlung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_APPLE_PAY_FORM_TRANSACTION: „applePayFormTransaction“	GiroCheckout_SDK_ApplePayFormTransaction()
Apple Pay Capture	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_APPLE_PAY_CAPTURE: „applePayCapture“	GiroCheckout_SDK_ApplePayCapture()
Apple Pay Erstattung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_APPLE_PAY_REFUND: „applePayRefund“	GiroCheckout_SDK_ApplePayRefund()
Apple Pay Stornierung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_APPLE_PAY_VOID: „applePayVoid“	GiroCheckout_SDK_ApplePayVoid()
Google Pay
Google Pay Zahlung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GOOGLE_PAY_FORM_TRANSACTION: „googlePayFormTransaction“	GiroCheckout_SDK_GooglePayFormTransaction()
Google Pay Capture	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GOOGLE_PAY_CAPTURE: „googlePayCapture“	GiroCheckout_SDK_GooglePayCapture()
Google Pay Erstattung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GOOGLE_PAY_REFUND: „googlePayRefund“	GiroCheckout_SDK_GooglePayRefund()
Google Pay Stornierung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_GOOGLE_PAY_VOID: „googlePayVoid“	GiroCheckout_SDK_GooglePayVoid()
Wero
Wero Zahlung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_WERO_TRANSACTION: „weroTransaction“	GiroCheckout_SDK_WeroTransaction()
Wero Erstattung	GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_WERO_REFUND: „weroRefund“	GiroCheckout_SDK_WeroRefund()
Tools
Transaktion abfragen	getTransactionTool	GiroCheckout_SDK_Tools_GetTransaction()

API Aufruf einbinden

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

SDK laden

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.

Zugangsdaten für Authentifizierung konfigurieren

$merchantID = xxx;
$projectID = xxx;
$projectPassword = xxx;

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

API Aufruf durchführen

$request = new GiroCheckout_SDK_Request(GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_WERO_TRANSACTION ));
$request->setSecret($projectPassword);
$request->addParam('merchantId',$merchantID)
        ->addParam('projectId',$projectID)
        ->addParam('merchantTxId',1234567890)
        ->addParam('amount',100)
        ->addParam('currency','EUR')
        ->addParam('purpose','Beispieltransaktion')
        ->addParam('urlRedirect','https://www.my-domain.de/girocheckout/redirect-wero')
        ->addParam('urlNotify','https://www.my-domain.de/girocheckout/notify-wero')
    //the hash field is auto generated by the SDK
        ->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.

API Aufruf auswerten

if($request->requestHasSucceeded()) {
  $rc = $request->getResponseParam('rc');
  $msg = $request->getResponseParam('msg');
  $ref = $request->getResponseParam('reference');
  $redir = $request->getResponseParam('redirect');
  $request->redirectCustomerToPaymentProvider();
}
/* if the transaction did not succeed, update your local system, get the responsecode and notify the customer */
else {
  $rc = $request->getResponseParam('rc');
  $msg = $request->getResponseParam('msg');
  $request->getResponseMessage($rc,'DE');
}

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

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

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.

Konfigurieren des Projektpassworts

$projectPassword = xxx;

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

Notification verarbeiten

$notify = new GiroCheckout_SDK_Notify(GiroCheckout_SDK_TransactionType_helper::TRANS_TYPE_WERO_TRANSACTION ));
$notify->setSecret($projectPassword);
$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.

Notification auswerten

if($notify->paymentSuccessful()) {
  $ref = $notify->getResponseParam('gcReference');
  $txid = $notify->getResponseParam('gcMerchantTxId');
  $bkid = $notify->getResponseParam('gcBackendTxId');
  $amt = $notify->getResponseParam('gcAmount');
  $cur = $notify->getResponseParam('gcCurrency');
  $rc = $notify->getResponseParam('gcResultPayment');

  $notify->sendOkStatus();
  exit;
}
else {
  $ref = $notify->getResponseParam('gcReference');
  $txid = $notify->getResponseParam('gcMerchantTxId');
  $bkid = $notify->getResponseParam('gcBackendTxId');
  $rc = $notify->getResponseParam('gcResultPayment');

  $notify->sendOkStatus();
  exit;
}

Die Methode paymentSuccessful() gibt true zurück, wenn die Zahlung erfolgreich war. 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 GiroCheckout 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_WERO_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"

Version 2.5.12/2.6.12 der SDKs hat die Möglichkeit eingeführt, über eine Konstante anzugeben, gegen welche Serverumgebung die API-Calls gesendet werden sollen. Dies geschieht über das Setzen eines der folgenden Werte über o.g. Methoden 1-3:

Wert	Bedeutung
gc1-dev	GiroCheckout 1 Entwicklungsumgebung
gc1-prod	GiroCheckout 1 Produktion
gc2-preprod	GiroCheckout 2 Vorproduktion (demnächst verfügbar)
gc2-prod	GiroCheckout 2 Produktion (demnächst verfügbar)

Bitte beachten, dass Credentials für die Umgebungen benötigt werden, die Sie einsetzen wollen.

Hinweis: In gc1 enthalten die URLs aus historischen Gründen den String „v2“. Bitte nicht mit gc2 verwechseln.

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:

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

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:

define('__GIROCHECKOUT_SDK_DEBUG__',true);

Das SDK generiert eine Logdatei 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 Logdatei 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 Zertifikatsdatei

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

Changelog