Plugin: PayPal Express

Paypal Express

Installation

Diese Erweiterung findest Du in unserem Shopware Store, der einfachste Weg, ein bestimmtes Plugin zu finden, ist die Suchleiste.
Nachdem Du den Bestellvorgang abgeschlossen hast, logge Dich in das Backend Deines Shops ein. Jetzt gehst du zu Konfiguration > Plugin-Manager > Meine Einkäufe. Du musst dich einloggen und auf die Schaltfläche Aktualisieren klicken. Die neue Erweiterung ist nun aufgelistet und kann installiert werden. Nach der Installation der Erweiterung gehst Du auf den Menüpunkt Installiert und aktualisierst die Übersicht. Jetzt kannst Du die Erweiterung aktivieren. Abschließend löscht Du unter Einstellungen > Cache/Performance > Shop-Cache löschen den Cache und aktualisierst das Backend.

Konfiguration

• API-Benutzername: Hier trägst Du den API Benutzernamen ein, den Du von PayPal erhalten hast.
• API-Passwort: Hier trägst Du das API-Passwort ein, das Du von PayPal erhalten hast.
• API-Unterschrift: Hier trägst Du die API-Unterschrift / API-Signatur ein, die Du von PayPal erhalten hast.
• REST-API Client ID: Hier trägst Du die REST-API Client ID ein, die Du von PayPal erhalten hast. Diese ID ist insbesondere für PayPal Plus nötig.
• REST-API Secret: Hier trägst Du den REST-API Secret ein, den Du von PayPal erhalten hast. Dieser ist insbesondere für PayPal Plus nötig.
• Sandbox-Modus aktivieren: Sofern Du einen Developer-Account bei PayPal besitzt, kannst Du mit separaten API-Zugangsdaten den Sandbox-Modus ausführen. Hier existieren Testkunden, mit denen Käufe problemlos durchgeführt werden können, um so die Schnittstelle zu testen. Bestellt ein realer Kunde im Sandbox-Modus, wird beim Kauf ein Fehler ausgegeben, sofern dies aktiv ist.
• API-Timeout in Sekunden: Dies legt den API-Timeout in Sekunden fest, sollte die API nicht antworten, wird das angegebene Intervall abgewartet, bevor die Verbindung unterbrochen wird.
• cURL verwenden (wenn es verfügbar ist): Sofern Dein Server cURL unterstützt, kannst Du mit dieser Einstellung cURL vom Plugin nutzen lassen.
• SSL-Version (CURLOPT-SSLVERSION): Hiermit definierst Du das Verschlüsselungsprotokoll, das verwendet werden soll. Im Standard wird hier bereits TLS benutzt. Beachte aber unbedingt, dass die einzelnen Versionen bestimmte Voraussetungen an die PHP-Version stellen, ohne die die Einstellung nicht funktionieren kann!
• Fehlermeldungen ausgeben: Hier stellst Du ein, ob das Plugin Fehler ausgeben soll.
• Alternativer Shop-Name auf der PayPal-Seite: Hier kannst Du einen alternativen Shopnamen auf der PayPal Seite ausgeben lassen.
• Alternative Sprache (LocaleCode): Hier kannst Du eine von Deinem Shop abweichende Sprache definieren, in der PayPal dargestellt werden soll.
• Shop-Logo auf der PayPal-Seite: Hier kannst Du Dein Shop-Logo auf der PayPal-Seite definieren. Beachte, dass im Standard kein Bild übertragen wird, Du solltest Dein Logo hier also unbedingt hinterlegen.
• Farbe des Warenkorbs auf der PayPal-Seite: Hier kannst Du die Farbe des Warenkorbs auf der PayPal-Seite einstellen.
• Payment-Logo im Frontend ausgeben: Hierüber regelst Du die Ausgabe des PayPal-Logos im Frontend.
• Zahlungsabschluss: Mit dieser Einstellung kannst Du definieren, ob Du die Zahlung direkt abschließen oder erst später einziehen möchtest.
• Zahlungsvereinbarung treffen / "Sofort-Kaufen" aktivieren: Um z.B. ESD-Artikel oder Abonnements per Sofort-Kauf erwerbbar zu machen, setze hier den Haken. Diese Option muss allerdings erst bei PayPal für Deinen Account freigegeben sein! Die Option in Paypal nennt sich "Recurring Billing".
• Warenkorb an PayPal übertragen: Überträgt den Inhalt des Warenkorbs an PayPal.
• "Direkt zu Paypal"-Button im Warenkorb anzeigen: Zeigt einen PayPal-Express Button im Warenkorb an.
• "Direkt zu Paypal"-Button in der Modal-Box anzeigen: Zeigt den PayPay-Express Button bereits in der Modal-Box. Beachte: Wenn Du das Responsive Theme einsetzt, wird die Modal-Box nur angezeigt, wenn Du die Theme-Option "OffCanvas Warenkorb nutzen" deaktiviert hast!
• Zahlstatus nach der kompletten Zahlung: Setzt den Zahlstatus nach der Bestellung automatisch auf die eingestellte Option.
• Zahlstatus nach der Autorisierung: Setzt den Zahlstatus nach der Autorisierung. Diese Option greift nur, wenn die Option Zahlungsvereinbarung treffen / Sofort-Kaufen aktiv ist!
• Bestellnummer an PayPal übertragen: Sendet die Bestellnummer an PayPal, dies ist in manchen Warenwirtschaften erforderlich.
• Bestellnummer für PayPal mit einem Shop-Prefix versehen: Nutzt Du mehrere Shops mit einem Account, kannst Du Überschneidungen der Bestellnummern vermeiden, indem Du diese sauber trennst.

Bitte beachte, dass der technische Name (Feld: "Name") unter Einstellungen > Zahlungsarten 
für die Paypal Zahlungsart nicht geändert werden sollte.

Paypal in Subshops

Um komplett subshopfähig zu sein, sieht die Konfiguration für einen Sprach- / Subshop eine gesonderte Konfiguration vor. Es ist möglich, alle Dropdown-Einträge aus dem Hauptshop vererben zu lassen, oder sie ggf. neu zu setzen. Unter dem jeweiligen Reiter (1) kannst Du in die Einstellungen der jeweiligen Subshops wechseln und Deine gewünschten Einstellungen vornehmen.

Soll PayPal in Deinen Sprach- oder Subshops nicht eingesetzt werden, trage in die API-Zugangsdaten einfach inkorrekte Daten ein, um die Vererbung zu unterbinden.

Paypal Plus

Vorbemerkung

• Das Produkt „PayPal PLUS“ muss für jeden Händler individuell freigeschaltet werden. Sofern noch nicht geschehen beantrage zunächst die Freischaltung unter: www.paypal.de/paypal-plus.

Voraussetzungen

Um PayPal Plus nutzen zu können, müssen folgende Voraussetzungen erfüllt sein:

• PayPal PLUS muss für Deinen Account freigeschaltet sein. Bitte beachte, dass Du den Kauf per Rechnung ebenfalls separat freischalten musst.
• PayPal Plugin ist installiert, konfiguriert und aktiv.
• Im PayPal Plugin müssen die REST-API Client ID und REST-API Secret gefüllt sein! Diese Daten werden Dir von PayPal zur Verfügung gestellt, einen Leitfaden findest Du im angehängten PDF.

Installation

Das Paypal Plus Plugin kannst Du wie gewohnt über den Shopware-Store beziehen.

Konfiguration

Die Konfiguration kannst Du über die Plugin-Einstellungen oder die Grundeinstellungen unter Grundeinstellungen > Zahlungsarten > PayPal PLUS vornehmen:

• Länder, für die "PayPal PLUS" angezeigt wird: Hier kannst Du definieren, in welchen Ländern PayPal PLUS für Deine Kunden zur Verfügung stehen soll. Beachte hierbei, dass die Zahlungsarten Lastschrift und Rechnung aktuell nur in Deutschland zur Verfügung stehen!
• Zahlungsart-Auswahl im Bestellabschluss ausblenden (Shopware 4): Diese Option steuert, ob die PayPal PLUS Zahlartauswahl im Checkout angezeigt werden soll, oder nur in der Shopware Zahlartauswahl. Diese Option kannst Du nur mit Shopware 4 nutzen.
• Zahlungsart-Auswahl überschreiben: Hier definierst Du die Bezeichnung der Zahlart im Frontend.
• Zahlungsart-Beschreibung ergänzen: Hiermit kannst Du die Beschreibung der Zahlungsart im Frontend erweitern.

Konfiguration des Webhooks

Es ist sehr wichtig, dass für das PayPal Plus Modul der sogenannte 'Webhook' eingerichtet wird. Ansonsten können nachträglich keine wiederkehrenden Zahlungsstatus-Änderungen durchgeführt werden, z.B. wenn eine Zahlung zunächst nur "reserviert" als Status besaß und nach einer gewissen Zeit "Abgeschlossen" gestellt werden soll.

Um diesen Webhook einzurichten, gehe bitte auf developer.paypal.com. Unter "Dashboard" findest Du den Bereich "My Apps and Credentials". Wenn Du aus den dort hinterlegten "REST API Apps" Deine App auswählst, gelangst Du zum Bereich der Webhooks. Zum Hinzufügen des Webhooks, klicke bitte "Add webhook" an.

Eine Webhook URL muss das folgende Format besitzen:

• 'http://www.meinShop.de/shop/payment_paypal/webhook' oder auch 'http://meinShop.de/payment_paypal/webhook'
• Es handelt sich hierbei um die Base-Domain mit Shop-Zusatz, falls dieser vorhanden ist.
• Diese URL entspricht der Notify-URL, unterscheidet sich dabei aber in dem Zusatz "webhook" am Ende der URL.

Bei der Einstellung "Event Types" muss darüber hinaus "All events" aktiviert werden.

Anzeige im Frontend

Die einzelnen Zahlungsarten (Paypal, Lastschrift, Kreditkarte, Kauf auf Rechnung) werden per iFrame im Checkout eingeblendet und ersetzen die in Shopware integrierten Zahlungsarten. Voraussetzung hierfür ist, dass der Kunde in seinem Account "Paypal" als Zahlungsart ausgewählt hat.

Das iFrame unterliegt zusätzlich der Logik, dass es, sofern der Kunde bereits "PayPal" als aktive Zahlart gesetzt hat, auch im "Step 3" des Checkouts angezeigt wird:

Wie kann ich testen?

Im Sandbox Modus kannst Du mit sogenannten Sandbox-Konten testen. Diese kannst Du auf der Website https://developer.paypal.com/ anlegen. Am einfachsten lässt sich das Modul im ELV-Modus testen. Dazu brauchst Du eine gültige Bankleitzahl und eine beliebige 8-stellige Kontonummer.

Sandbox-Transaktionen werden in einer virtuellen Testumgebung abgewickelt. Es werden also keine echten Konten belastet. Bitte beachte, dass es bei dieser Testumgebung gelegentlich zu Störungen kommen kann.

FAQ - Fehlercodes

10004 

Transaction refused because of an invalid argument. The transaction id is not valid

Der Zahlungseingang seitens Paypal konnte nicht bestätigt werden. Der Kunde hat die Bezahlung in seinem PayPal-Account vorgenommen, diese konnte aber nicht von Paypal verifiziert werden. Das heißt im Klartext: Paypal kann zum Zeitpunkt des Zahlungsabschlusses im PayPal-Account die Zahlung nicht bestätigen. Gründe hierfür können beispielsweise ein Timeout seitens der PayPal-API, eine fehlende Liquidität seitens des Kontos oder der Kreditkarte sein, von welcher PayPal den Betrag abbuchen will. Es ist auch möglich, dass ein kurzfristiges, technisches Problem seitens PayPal besteht.

Damit ist die Zahlung für Shopware nicht vollzogen. In diesem Fall wird eine ungültige TransaktionsID (der ExpressCheckout-Token) übergeben. Dieser Token beginnt immer mit dem Kürzel EC- und kann unter Kunden->Zahlungen->PayPal eingesehen werden. Da kein Zahlungseingang erfolgt ist, steht der Zahlungsstatus auf Offen. In diesem Fall solltest Du den Zahlungseingang in Ihrem Paypal-Account nochmal überprüfen.

Dem Kunden wird aufgrund der nicht verifizierten Zahlung in seinem Paypal-Account, beim Wechsel zurück in den Checkout-Prozess, von Shopware darauf hingewiesen, dass es seitens PayPal Probleme mit dem Zahlungsabschluss gibt und von PayPal keine gültige TransaktionsID bereitgestellt werden konnte. In diesem Fall wird dem Kunden folgender Hinweis beim Bestellabschluss angezeigt: "Es ist ein Problem aufgetreten und die Bestellung konnte nicht abgeschlossen werden. Bitte kontaktieren Sie den Shopbetreiber."

Sofern dieses Verhalten nicht gewünscht ist und nicht verifizierte Paypal-Bestellungen gar nicht erst zu Shopware übertragen werden sollen, musst Du die Option "Bestellnummer an Paypal übertragen" deaktivieren. Somit kann bei nicht verifizierten Paypal-Zahlungen kein Bestellabschluss erfolgen, der Kunde wird zurück in den Checkout-Prozess in Shopware geleitet und gebeten eine andere Zahlungsart zu wählen.

Bei fehlerhaften Transaktions-IDs empfehlen wir zuerst den "API-Timeout" zu prüfen. Im Standard ist dieser auf 60 Sekunden gesetzt, hast Du aber eine bedeutend kürzeren Timeout, solltest Du diesen Schrittweise bis auf maximal 120-160 Sekunden erhöhen. Deaktiviere zudem die Option Bestellnummer an Paypal übertragen.

Authentication / Authorization Failed

Die API-Zugangsdaten sind nicht korrekt.

10002

Security error. Security header is not valid

Der API-Schlüssel ist nicht korrekt.

Duplicate invoice

Payment has already been made for this InvoiceID

Der Bestellnummernkreis ist zu niedrig / Die Bestellnummern sind in PayPal bereits vergeben.

Shipping Adress State Empty

The field "Shipping Adress State" is required

Bundesländer sind nicht konfiguriert. Für folgende Länder sind diese verpflichtend:

• USA (US)
• Canada (CA)
• (Mainland) China (CN)
• Japan (JP)
• Mexico (MX)
• Brasil (BR)

Die Bundesländer kannst Du in den Ländereinstellungen im Backend von Shopware konfigurieren.

Invalid transaction-ID. Transaction-ID is invalid

Die Option "Zahlungen nur autorisieren" ist aktiv, aber nicht für den PayPal Händler-Account freigeschaltet.

Express Checkout PayerID is missing

Die Option "Zahlungsvereinbarung treffen" ist aktiv, aber der PayPal Händler-Account ist dafür nicht freigeschaltet.

Error in cURL request

Operation timed out after 5000 milliseconds with 0 bytes received

Der Fehler tritt immer dann auf, wenn in der php-Konfiguration kein gültiges curlopti_timout gesetzt wurde.

Auflistung aller Paypal Error-Codes

Hier findest Du eine Auflistung aller von PayPal ausgegeben Fehlercodes. Diese Codes werden als Fehlermeldungen über das PayPal-Plugin im Backend von Shopware ausgegeben. Bitte beachte, dass es sich bei diesen Error-Codes um Fehler handelt, die von Paypal zurückgegeben werden und nicht von Shopware stammen.

Paypal Plus: Zugriff nicht erlaubt

Diese Meldung auf der Checkoutseite im Frontend erscheint immer dann, wenn der genutzte PayPal Plus- Account von Paypal noch nicht für den Livebetrieb freigeschaltet wurde.

Paypal NICHT in Sprach-/ Subshops nutzen

Auch PayPal vererbt wie jedes andere Plugin seine Konfigurationen. Dadurch werden die Zugangsdaten des Hauptshops verwendet, wenn im Subshop nichts anderes eingetragen wurde.

Möchtest Du PayPal nicht in Sprach-/ oder Subshops nutzen, so musst Du in den Zugangsdaten für den entsprechenden Sprach-/ Subshop invalide Daten eingeben. Dadurch wird der Fallback unterbunden und PayPal aufgrund der falschen Daten nicht angezeigt.