Vor kurzem hatte ich mich mit der Paypal Integration in PHP für eine eCommerce-Lösung beschäftigt. Dabei begegneten mir immer wieder ein paar Stolpersteinen. Dabei fiel mir besonders auf, dass andere Entwickler oft die gleichen Probleme haben.
Daher habe ich mich entschlossen, einen Leitfaden für die Paypal Integration in PHP zu erstellen. Damit sollen andere Entwickler wesentlich schneller werden.
Möglicherweise kommen Dir ein paar Probleme etwas banal vor. Trotzdem finde ich es wichtig auch diese zu schildern. Schließlich könntest Du in die gleichen Probleme laufen.
Was Du alles für die Paypal Integration in PHP brauchst?
Ich gehe davon aus, dass der Shop, an dem Du arbeitest, nicht nur ein Produkt verkauft. Wahrscheinlich bietest Du verschiedene Waren an, oder? Falls Du nur ein einziges Produkt verkaufst, dann sollte der Einbau eines Paypal-Buttons die geeignetere Lösung sein.
Wenn Du eine Standard Shop-Software benutzt, gibt es fast immer ein Modul oder Plugin für die Bezahlung mit Paypal.
Ich zeige Dir, wie Paypal ohne ein solches Plugin integriert werden kann.
Wie Du eine REST API App erstellst
Um eine erfolgreiche Paypal Integration in deinen Shop durchzuführen, brauchst Du eine Paypal REST API App. Ohne die Paypal PHP API kannst Du die Paypal Integration in PHP vergessen.
Deshalb erkläre Ich Dir in einzelnen Schritten, was Du dafür tun musst.
Geschäftskonto erstellen
Um eine Paypal REST API App erstellen zu können, sind zwei Dinge notwendig. Erstens brauchst Du einen Paypal Account. Zweitens benötigst Du eine sog. Web-App. Dazu gleich mehr.
Hast Du bereits ein Paypal-Konto? Dann prüfe, ob es sich um ein privates oder ein geschäftliches Konto handelt.
Um die Paypal REST API nutzen zu können, ist ein Geschäftskonto notwendig.
Besitzt Du ein privates Konto, gibt es zwei Möglichkeiten:
- Umwandlung des vorhanden Accounts in ein Geschäftskonto
- Erstellung eines neuen Geschäftskontos
Persönlich empfehle ich Variante zwei! Dadurch sind private und geschäftliche Zahlungen voneinander getrennt.
Es ist jedoch in deiner Hand.
Entscheide selbst.
Wie du eine Paypal REST API App erstellst
Im nächsten Schritt für die Paypal Integration in PHP muss eine sog. Web App erstellt werden. Auf dem Paypal Developer Portal kannst Du sie erstellen. Logge Dich mit Deinem Geschäftskonto ein und betreten das Dashboard. Nun kannst Du eine App über den Button Create App erstellen.
Nach der Erstellung kannst Du eine ClientID und den Secret. Beides ist für die Sandbox wie für den Live-Betrieb vorhanden. Die Sandbox ist sozusagen die Testumgebung. Beide Werte sind notwendig um eine gültige Authentifizierung zu erhalten. Deine Entwicklung sollte in der Sandbox stattfinden.
Paypal REST API App Einstellungen anpassen
Bevor du loslegst, solltest Du die nachfolgenden Einstellungen WIRKLICH ZUERST setzen.
Der Grund ist einfach: Paypal braucht oft länger um Änderungen wirkungsvoll zu machen.
Viele Entwickler versuchen direkt nach einer Änderung ihr Ziel zu erreichen.
Danach sitzen sie Stunden lang am Programmcode. Dabei versuchen sie verzweifelt Fehler zu finden.
Dabei ist die Änderung nur noch nicht in Paypal verfügbar.
Auch ich habe diesen Zustand erlebt. Deshalb solltest Du ganz klar etwas warten. Ich warte immer einen ganzen Tag um sicher zu sein. Investiere solange Deine Zeit lieber in andere wichtige Dinge. Schone lieber Deine Nerven.
Die Einstellung der Werte Return URLs ist vorerst die wichtigste Einstellung. Hier werden die URLs für die Rückkehr von Paypal eingestellt.
Sie ist sehr wichtig für die PayPal PHP API. Aufgrund der längeren Wartezeit, würde ich die Einstellungen für die Sandbox und das Live-System gleichzeitig machen.
Bist Du Dir nicht sicher wie Deine URLs aussehen sollen? Dann mache Dir erst einmal darüber Gedanken. Erst danach würde ich mit der Entwicklung weitermachen.
Der Leitfaden nutzt für beide Fälle die gleiche URL. Der Unterschied liegt an den GET-Parametern. Die Erfolgs-URL besitzt den GET-Parameter success=1. Die URL bei Abbrüchen hat den GET-Parameter cancel=1. Der Abschnitt Die Rückkehr von Paypal geht tiefer in die Verarbeitung der Daten nach Paypal ein.
Test-Accounts i für Deine Sandbox anlegen
Neben den Einstellungen der Paypal REST API App brauchst Du noch etwas. Denn ohne einen Test-Account kannst Du nicht testen.
Dazu musst Du in den Bereich Accounts gehen. Erstelle jedoch nicht nur einen Account. Füge verschiedene Typen hinzu. Denn Du willst ja auch verschiedene Bezahlarten prüfen. Ansonsten kannst Du nicht alle Möglichkeiten zum Testen. Ich würde Test-Accounts für Bezahlungen mit Kreditkarte, ohne Kreditkarte, kein Paypal-Guthaben, usw. anlegen. Mithilfe der Accounts kannst Du verschiedene Situation prüfen. Dadurch kannst Du die Rückgabewerte von Paypal auf die verschiedenen Bezahlungen untersuchen.
Paypal PHP SDK für die PayPal REST API einbinden
Für eine vernünftige Paypal Integration in PHP, solltest Du die PayPal PHP SDK verwenden. Die aktuelle Version kannst Du bspw. über Composer installieren. Den folgende Code kannst Du in die Datei composer.json einfügen. Dazu nutzt Du den Abschnitt „require“:
"require": {
...
"paypal/rest-api-sdk-php" : "dev-master"
},
Anschließend kann die Installation über die Konsole erfolgen. Composer erstellt über den folgenden Befehl allen Dateien mit Abhängigkeiten: composer update.
Wenn Komponenten für die Paypal PHP SDK fehlen sollten, wird Composer es Dir melden. Die fehlenden Komponenten müssten dann vorher installiert werden.
Hierbei entstand mir ein wirklich großes Problem. In meiner ersten Implementierung verwendete ich eine alten Version der Paypal PHP SDK.
Anstelle der Versionierung dev-master nutzte ich eine ältere Version der Paypal PHP SDK.
Die Verschlüsselungstechnik hatte sich bis dahin geändert. Dadurch entstand bei jedem Aufruf von Paypal ein sog. Hand-Shake-Error. Der Fehler klingt zwar banal. Aber es dauerte einige Stunden um den Fehler zu ermitteln. Daher erwähne ich auch dieses Problem. Du sollst nicht in den gleichen Fehler laufen.
Wenn Du nun die Versionierung dev-master nutzt, dann musst Du noch auf etwas achten. Denn die Paypal PHP SDK kann mit jedem Update über Composer selbst ein Update erhalten. Du solltest bei jedem Update prüfen, ob die Funktionalität Deiner Paypal Integration noch stimmen. Ansonsten kann es gut sein, dass die Bezahlung über Paypal nicht mehr geht. Genau das solltest Du vermeiden.
Der erste Programmcode für die Paypal Integration in PHP
Je nach Implementierung Deines Onlineshops, kann die Einbindung der API-Komponenten der Paypal PHP SDK anders aussehen.
Zu deiner Info: Das Beispiel nutzt das Framework Symfony. Es ist in Version 2.8 umgesetzt.
Nutzt Du ein anderes PHP-Framework?
Wenn Du ein anderes Framework oder gar eine höhere Version nutzt, dann muss der Code natürlich daran angepasst werden. Wahrscheinlich ist Dir das schon klar.
Damit Du Paypal nun nutzen kannst, muss es erstmal vorbereitet werden. Schließlich muss Paypal wissen, was zu bezahlen ist. Besser gesagt wie viel bezahlt werden muss. Dabei hângt die Umsetzung stark von der Softwarearchitektur Deiner eCommerce Lösung ab.
Im Leitfaden wird extra eine neue Klasse erzeugt. Sie ist für die Ablauflogik zuständig.
Grundfunktionen der Klasse
Die Grundfunktionen der Klasse basieren auf zwei Methoden. Der Konstruktor und die Methode mit dem Namen fnSetEnvironmentDetails sind für die Vorbereitung am wichtigsten.
namespace MyShopBundle\Controller\Shop\Payment;
use Symfony\Bundle\FrameworkBundle\Controller\Controller,
Symfony\Component\HttpFoundation\Session\Session;
// Paypal requirements
use PayPal\Rest\ApiContext;
use PayPal\Api\OpenIdSession;
use PayPal\Auth\OAuthTokenCredential;
use PayPal\Api\Address;
use PayPal\Api\PayerInfo;
use PayPal\Api\Payer;
use PayPal\Api\Item;
use PayPal\Api\ItemList;
use PayPal\Api\Details;
use PayPal\Api\Amount;
use PayPal\Api\Transaction;
use PayPal\Api\Payment;
use PayPal\Api\RedirectUrls;
use PayPal\Api\PaymentExecution;
class PaypalPayment extends Controller {
protected $container;
protected $request;
protected $totalsCalculator;
protected $paymentInformation;
protected $prodClientId = "";
protected $prodSecret = "";
protected $devClientId = "";
protected $devSecret = "";
protected $clientId = "";
protected $secret = "";
public function __construct($container, $devMode = false, $clientId = false, $secret = false, $devClient = false, $devSecret = false) {
$this->container = $container;
$this->get('request');
$this->get('total_calculator');
if ($clientId === false AND $this->container->hasParameter('PaypalClientId') === false )
throw new \Exception('No existing Parameter "PaypalClientId"! Please add this parameter.');
else
$this->prodClientId = $this->container->getParameter('PaypalClientId');
if ($secret === false AND $this->container->hasParameter('PaypalSecret') === false )
throw new \Exception('No existing Parameter "PaypalSecret"! Please add this parameter.');
else
$this->prodSecret = $this->container->getParameter('PaypalSecret');
if ($devMode === true) {
if ($clientId === false AND $this->container->hasParameter('PaypalDevClientId') === false )
throw new \Exception('No existing Parameter "PaypalDevClientId"! Please add this parameter.');
else
$this->devClientId = $this->container->getParameter('PaypalDevClientId');
if ($clientId === false AND $this->container->hasParameter('PaypalDevSecret') === false )
throw new \Exception('No existing Parameter "PaypalDevSecret"! Please add this parameter.');
else
$this->devSecret = $this->container->getParameter('PaypalDevSecret');
}
$this->fnSetEnvironmentDetails($devMode);
}
protected function fnSetEnvironmentDetails($devMode = false) {
if ($devMode === false ) {
$this->clientId = $this->prodClientId;
$this->secret = $this->prodSecret;
}
else {
$this->clientId = $this->devClientId;
$this->secret = $this->devSecret;
}
}
Der Konstruktor erhält das Container-Objekt von Symfony. Weitere Argumente sind gesetzt um verschiedene Tests zu machen.
Der Container ist vorhanden, da er andere Objekte aus dem System laden kann. Außerdem kann er verschiedene Parameter aus der Parameter-Liste abholen.
Der Container holt bereits im Konstruktor die Parameter Client-ID und den Secret. Ohne sie kannst Du die Paypal PHP SDK gar nicht nutzen. Deshalb werden sog. Exceptions geworfen, wenn sie nicht gesetzt sind. Die Prüfung auf Nutzung der Sandbox oder dem Live-Betrieb findet ebenfalls im Konstruktor statt. Der Wert des Arguments $devMode entscheidet es. Ist der Wert false, wird der Live-Betrieb gestartet. Der Wert true setzt die Sandbox in Gang. Über die Methode fnSetEnvironmentDetails werden die Werte gesetzt.
Ich finde diese Art der Entwicklung wichtig. Es spielt dabei keine Rolle, ob es um eine Paypal Integration in PHP geht oder einer anderen Programmiersprache. Das gilt auch für andere Bezahlmöglichkeiten. Wenn eine Sandbox vom Anbieter angeboten wird, solltest Du sie nutzen.
Der weitere Aufbau der Klasse „PaypalPayment“
Der nächste Schritt befasst sich mit der Vorbereitung von Paypal. Hierzu nutzen wir das erstmal die Paypal PHP SDK.
public function fnGetPaymentInformation($devMode = false){
if (empty($this->paymentInformation))
$this->paymentInformation = $this->fnBuildPaymentInformation($devMode);
return $this->paymentInformation;
}
protected function fnBuildPaymentInformation($devMode) {
$totalValues = $this->totalsCalculator->fnGetTotalValues();
$paymentInformation['total'] = $totalValues['total'];
$apiContext = $this->fnGetApiContext($devMode);
$paymentInformation['paypalPayment'] = $this->fnCreatePaypalPayment($apiContext);
return $paymentInformation;
}
protected function fnCreatePaypalPayment($apiContext) {
$payer = new Payer();
$payer->setPaymentMethod("paypal");
$transaction = $this->fnBuildTransaction();
$baseUrl = $this->request->getSchemeAndHttpHost();
$responseUrl = '/your-paypal-payment-response-url/';
$redirectUrls = new RedirectUrls();
$redirectUrls->setReturnUrl($baseUrl . $responseUrl .'?success=true')
->setCancelUrl($baseUrl . $responseUrl .'?cancel=true');
$payment = new Payment();
$payment->setIntent("sale")
->setPayer($payer)
->setRedirectUrls($redirectUrls)
->setTransactions(array($transaction));
$paypalPaymentObj = $payment->create($apiContext);
return $paypalPaymentObj;
}
protected function fnGetApiContext($devMode = false) {
$oauthCredential = new OAuthTokenCredential($this->clientId, $this->secret);
$apiContext = new ApiContext($oauthCredential);
$apiContext->setConfig(
array(
'mode' => ($devMode === false ? 'live' : 'sandbox'),
'log.LogLevel' => ($devMode === false ? 'INFO' : 'DEBUG'), //'DEBUG', // PLEASE USE `INFO` LEVEL FOR LOGGING IN LIVE ENVIRONMENTS
)
);
return $apiContext;
}
protected function fnBuildTransaction($orderId = false) {
$totalValues = $this->totalsCalculator->fnGetTotalValues();
$bagItemsForPP = array();
$currentSubTotal = 0.00;
foreach( $bagItems = $this->totalsCalculator->fnGetConfiguratedBagItems() as $index => $singleBagItem) {
$currentSubTotal += ($singleBagItem['price'] - $singleBagItem['discount_amount_of_single_article']) * $singleBagItem['quantity'];
$bagItemsForPP[$index] = new Item();
$bagItemsForPP[$index]->setName($singleBagItem['fullProductName'])
->setCurrency($this->container->hasParameter('currency_normal') ? $this->container->getParameter('currency_normal') : '');
Ich gehe davon aus, dass Du PHP verstehst. Darum werde ich den obigen Code nicht zu 100% erklären.
Ich erkläre Dir aber die wichtigsten Dinge. Auf diese Punkte gehe ich jetzt ein.
Nützliche Hinweise, Fehlerquellen und Fehlermeldungen
Der sog. ApiContext aus der Paypal PHP SDK wird genutzt um eine valide Verbindung zu Paypal aufzubauen. Das Objekt prüft die ClientID und den Secret. Bei falschen Werten gibt es einen
$paypalPaymentObj = $payment->create($apiContext);
Theoretisch ist es nicht notwendig die Artikel einer Bestellung an Paypal weiterzugeben. Im Leitfaden zur Paypal Integration in PHP gebe ich Dir jedoch noch weitere hilfreiche Tipps.
Das ist einer davon und daher habe ich die Übergabe von Artikeln ebenfalls eingebaut (s. Funktion fnBuildTransaction – foreach Schleife).
Der Grund ist ganz einfach. Mithilfe der Übergabe der Artikel, lassen sich Fehler sehr viel leichter aufspüren. Fehler könnten z.B. beim Einsatz von Rabatten entstehen. Die übergebenen Werte sendet Paypal übrigens nach der Bezahlung auch zurück. Somit können die Werte anschließend verglichen werden. Du solltest auch daran denken, dass du mit den Informationen ggf. leichter Statistiken über Paypal-Bezahlungen machen könntest. Das nur am Rande.
Ich hatte in einem eigenem Shop System exakt das Problem. Nach einer Nutzung von Promotionen haben die Daten von Paypal und die Daten der Bestellung nicht mehr gepasst. Die Übergabe der korrekt rabattierten Preise hatten damals nicht geklappt. Da die Werte nicht stimmten, hat Paypal einen 404-Fehler geworfen. Denn Paypal vergleicht automatisch die Preise der Waren und den Warenkorbwert.
Darum empfehle ich Dir diese Option. Durch die Übergabe der Artikel ist die Fehlerbehebung sehr viel einfacher.Einbau in ein Template
Der Einbau des Links zur Paypal-Bezahlmaske ist relativ simpel. Über den Aufruf der Funktion fnGetPaymentInformation der Klasse PaypalPayment erfolgt eine Rückgabe der Instanz der Klasse Payment (aus Paypal PHP API). Anschließend setzt man den Link über diese Funktion an den View oder das Template: $paypalPayment->getApprovalLink();.
Anschließend muss die Variable im Template nur noch aufgerufen werden. Der Einbau erfolgt als Link, nicht über ein Formular.
Die Rückkehr von Paypal – Der letzte Schritt der Paypal Integration in PHP
Der nächste Schritt bei der Paypal Integration in PHP ist die Verarbeitung der Daten nach der Rückkehr von Paypal. Wir betrachten nun die Abarbeitung im Erfolgsfall und Stornierungsfall.
Rückgabefunktion nach einer Paypal-Bezahlung
Das Beispiel nutzt die gleiche URL für die Rückkehr im Erfolgsfall, sowie im Stornierungsfall. Der Unterschied besteht nur auf unterschiedliche GET-Parameter.
Die Entscheidung ist natürlich Deine und sollte von der Softwarearchitektur Deines Systems abhängen. Deine Entscheidung kann sich natürlich hier von unterscheiden.
Der verantwortliche Controller für die Rückkehr ist wie folgt aufgebaut:
$request = $this->container->get('request');
$session = $this->container->get('session');
$translator = $this->container->get('translator');
$paypalSuccess = ($request->query->has('success') ? true : false);
$paypalCancel = ($request->query->has('cancel') ? true : false);
$paymentId = ($request->query->has('paymentId') ? $request->query->get('paymentId') : false);
$token = ($request->query->has('token') ? $request->query->get('token') : false);
$payerId = ($request->query->has('PayerID') ? $request->query->get('PayerID') : false);
if ($paypalSuccess == true) {
$paypalResponse = array(
'paypalResponse' => array(
'paymentId' => $paymentId,
'token' => $token,
'payerId' => $payerId,
),
);
return $this->redirect($this->generateUrl('Shop_CheckoutPaymentResponse', $paypalResponse));
}
elseif ($paypalCancel == true) {
$session->getFlashBag()->add('paypal-login-error', $translator->trans($paypalLoginErrorDescription));
return $this->redirect($this->generateUrl('Shop_CheckoutPayment', array('payment_provider_response' => true)));
}
else {
$session->getFlashBag()->add('paypal-login-error', $translator->trans('An unexpected error uccurs!'));
return $this->redirect($this->generateUrl('Shop_CheckoutPayment', array('payment_provider_response' => true)));
}
Weil eine URL für den Erfolg und den Misserfolg genutzt wird, wird auf die GET-PARAMETER im Controller geprüft (s. Zeile 4 – 5). Außerdem werden die Werte paymentId, token und PayerID abgeholt (s. Zeile 6 – 8). Paypal sendet diese Parameter übrigens auch über GET-Parameter an die Erfolgs-URL.
Je nach den GET-Wert leitet der Controller an eine andere URL weiter. Im Erfolgsfall erfolgt eine Weiterleitung zum Controller für die Bearbeitung der Bezahlung. Im anderen Fall schickt der Controller den User zur Payment-Seite zurück. Ist die Bezahlung misslungen, erhält der User entsprechend eine Meldung über die Session (s. Zeile 20 und 25).
Im Beispiel landet der Kunde auf der Payment-Seite. Schließlich soll er beim Misserfolg eine snere Bezahlung wählen können. Es gibt aber auch andere Shops, bei denen der Checkout damit beendet ist.
Je nachdem, wie Du Dich entscheidest, muss der Kunde den Warenkorb wieder füllen, oder eben nicht. Es hängt von Deinem Shop oder Deiner Entscheidung ab.
Unsere Entscheidung kann ggf. die Abbruchrate eines Kaufes reduzieren. Schließlich gibt es einige Kunden, die nicht nochmals den Warenkorb füllen möchten.
Warum Du einen eigenen Controller für die Response nutzen solltest!
Du fragst Dich möglicherweise: Warum ist die URL nicht direkt auf den Controller für die Abwicklung der Bezahlung gerichtet? Die Entscheidung habe ich erstens getroffen um den Programmcode so kurz wie möglich zu halten. Zweitens vermeide ich grundsätzlich gleichen Code, so gut es geht.
Hält man sich nicht daran, können Änderungen einen höheren Arbeitsaufwand bedeuten. Kürzere Code-Abschnitte helfen den Code schneller zu verstehen. Wenn nun immer mehr Bezahlmöglichkeiten hinzu kommen, dann wird der Code immer größer. Dadurch entsteht weitaus schlecht lesender Programmcode.
Bezahldaten über Paypal REST API auslesen
Nun schauen wir uns gleich die Prüfung der Bezahldaten an. Die Daten werden wie folgt geprüft:
....
class CheckoutPaymentResponse extends Controller {
public function checkoutPaymentResponseAction(){
....
if ($request->query->has('paypalResponse')) {
$ppConstructor = new PaypalPaymentConstructor($this->container);
$paymentControlResponse = $ppConstructor->fnHandlePaypalResponse($paypalResponse = $request->query->get('paypalResponse'));
....
}
....
}
Zeile 5 bezieht sich auf den Weitergegebenen GET-Parameter paypalResponse. Sobald eine Bezahlung erkannt wurde, wird ein PaypalPayment-Objekt initialisiert.
Die Methode fnHandlePaypalResponse der Klasse PaypalPayment kümmert sich um die Rückgabewerte.
public function fnHandlePaypalResponse( $paypalResponse, $devMode = false ){
$apiContext = $this->fnGetApiContext($devMode);
$payment = Payment::get($paypalResponse['paymentId'], $apiContext);
$execution = new PaymentExecution();
$execution->setPayerId($paypalResponse['payerId']);
$result['payment_response_data'] = $payment->execute($execution, $apiContext);
$result['payment_information'] = json_encode($result['payment_information']);
....
return $result;
}
Grundsätzlich benötigt man die sog. payerId um das Payment- und Execution-Objekt der Paypal PHP SDK zu erzeugen. Das erzeugte Execution-Objekt wird als Argument in der Methode execute() übergeben. Dadurch kommen die Daten der Paypal-Bezahlung zurück. In unserem Fall nutzen wir das Array $result um die Daten zu speichern.
Anschließend können die erhaltenen Daten in die Datenbank gespeichert werden. Die Rückgabe von Paypal ist vom Typ Array. Damit die Daten in ein Datenbank-Feld gespeichert werden können, wandeln wir die Daten in das JSON-Format um (s. Zeile 9). Dadurch ist der Code vor Änderungen der Schlüsselnamen geschützt.
Hast Du eine andere Idee gehabt?Wolltest Du jeden Datensatz in eine eigene Spalte zu speichern? Das kann leider zu Problemen führen. Wenn Paypal aus irgendeinem Grund die Schlüsselnamen ändert, müsste der Code im Shop angepasst werden. Denn einen der Schlüssel gibt es dann nicht mehr.
Der Leitfaden zur Paypal Integration in PHP ist nun vollständig.
Fazit
Der vorgestellte Code kann von allen genutzt werden um eine Paypal Integration in PHP durchzuführen. Du solltest aber darauf achten, dass Du den Code entsprechend an Dein System anpasst.
Solltest Du Fragen haben, dann kannst Du gerne einen Kommentar verfassen. Hast Du andere Anmerkungen oder Dir ist etwas unklar, dann schreib mir ebenso.
Über ein positives Feedback würde ich mich natürlich auch sehr freuen. Ansonsten wünsche ich Dir viel Spaß und Erfolg bei der Umsetzung.
