Benutzer-Werkzeuge

Webseiten-Werkzeuge


Übersetzungen dieser Seite:
phpsdk:start

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

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 auch unabhängig voneinander funktionieren, falls eine der beiden Meldungen nicht ankommt. Auf dieser 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
eps
eps Bankstatus prüfen epsBankstatus GiroCheckout_SDK_EpsBankstatus()
eps Bankenabfrage epsIssuerList GiroCheckout_SDK_EpsIssuerList()
eps Transaktion epsTransaction GiroCheckout_SDK_EpsTransaction()
giropay
giropay Bankstatus prüfen giropayBankstatus GiroCheckout_SDK_GiropayBankstatus()
giropay-ID giropayIDCheck GiroCheckout_SDK_GiropayIDCheck()
giropay Transaktion giropayTransaction GiroCheckout_SDK_GiropayTransaction()
giropay + giropay-ID giropayTransaction GiroCheckout_SDK_GiropayTransaction()
iDEAL
iDEAL Bankenabfrage idealIssuerList GiroCheckout_SDK_IdealIssuerList()
iDEAL Transaktion idealPayment GiroCheckout_SDK_IdealPayment()
iDEAL Erstattung idealRefund GiroCheckout_SDK_IdealPaymentRefund()
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()
Maestro
Maestrozahlung maestroTransaction GiroCheckout_SDK_MaestroTransaction()
Maestro Capture maestroCapture GiroCheckout_SDK_MaestroCapture()
Maestro Erstattung maestroRefund GiroCheckout_SDK_MaestroRefund()
Paydirekt
Paydirekt Zahlung paydirektTransaction GiroCheckout_SDK_PaydirektTransaction()
Paydirekt Capture paydirektCapture GiroCheckout_SDK_PaydirektCapture()
Paydirekt Erstattung paydirektRefund GiroCheckout_SDK_PaydirektRefund()
Paydirekt Stornierung paydirektVoid GiroCheckout_SDK_PaydirektVoid()
Payment Page Transaktion
Zahlung über Payment Page paypageTransaction GiroCheckout_SDK_PaypageTransaction()
SOFORT-Überweisung
SOFORT-Überweisung Zahlung sofortuwTransaction GiroCheckout_SDK_SofortUwTransaction()
PayPal
PayPal Transaktion paypalTransaction GiroCheckout_SDK_PaypalTransaction()
Tools
Transaktion abfragen getTransactionTool GiroCheckout_SDK_Tools_GetTransaction()

API Aufruf einbinden

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

SDK laden

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.

Zugangsdaten für Authentifizierung konfigurieren

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.

API Aufruf durchführen

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.

API Aufruf auswerten

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.

Notification und Redirect Scripte einbinden

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

SDK laden

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.

Konfigurieren des Projektpassworts

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.

Notification verarbeiten

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.

Notification auswerten

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.

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:

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"

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

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

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

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

$request->setSslVerifyDisabled();

Changelog

Version 2.1.14 - 20.07.2017

  • URL-Parameter bei Paypage sind jetzt optional.

Version 2.1.13 - 17.07.2017

  • Fehlende Notification-Parameter bei Paypage hinzugefügt.

Version 2.1.12 - 13.06.2017

  • Neue Logos für Lastschrift.

Version 2.1.11 - 30.05.2017

  • Connection Timeout für Verbindungsaufbau generell von 3 auf 15 Sek. erhöht.

Version 2.1.10 - 11.04.2017

  • Funktionen für Windows-Umgebungen setSslCertFile() und setSslVerifyDisabled() wieder eingebunden.

Version 2.1.9 - 24.03.2017

  • Bugfix bei Erzeugung des Kreditkartenlogo-Dateinamens
  • Unterstützung für Storno bei Kreditkarten, Lastschrift und Paydirekt

Version 2.1.8 - 02.03.2017

  • Verbesserte Statistik-Information zu verwendeten SDK-Versionen (intern)

Version 2.1.7 - 14.02.2017

  • Bei Paydirekt: Unterstützung der Warenkorbtypen ANONYMOUS_DONATION (Spenden) und AUTHORITIES_PAYMENT (Behördenzahlung) eingebaut

Version 2.1.6 - 10.02.2017

  • Rückwärtskompatibilität mit PHP 5.2.x (wieder)hergestellt
  • Parameter issuer bei iDEAL ist nicht mehr Pflicht (Bank wird abgefragt, wenn er fehlt. Aber Achtung: dies muss im Cockpit freigeschaltet werden.)

Version 2.1.5 - 02.02.2017

Version 2.1.4 - 18.01.2017

  • Korrekturen in Fehlermeldungstexten

Version 2.1.3 - 10.01.2017

  • Bugfix CURL Helper
  • Neue Logo-Dateien

Version 2.1.2 - 09.01.2017

  • Integration Paypage API
  • Integration Maestro API
  • Korrektur Datumsformat im Logfile
  • Text-Korrekturen
  • Neue Logos MasterCard, JCB
  • Fix UTF8-Fehler in Paydirekt
  • Unterstützung digitale Warenkörbe Paydirekt

Version 2.1.0 - 31.08.2016

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

Version 2.0.3 - 29.06.2016

  • Einige Beispiele überarbeitet und korrigiert

Version 2.0.2 - 08.06.2016

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

Version 2.0.1 - 11.05.2016

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

Version 2.0.0 - 09.05.2016

  • 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
2017/01/09 18:47 · Michael Heumann
phpsdk/start.txt · Zuletzt geändert: 2017/07/20 23:06 von michaelheumann

Seiten-Werkzeuge