Klassischen PayPal Checkout konfigurieren

Dies ist der traditionelle PayPal Checkout, in dem bei der Bezahlung ein neues Fenster aufgeht, in dem man lediglich mit seinem PayPal-Account zahlen kann.

Achtung:

Der PayPal Checkout erfordert die Pro-Version der Shop-Erweiterung!

Achtung:

Der PayPal Checkout erfordert den Eintrag der vollen URL in der Site-Konfiguration Deiner TYPO3-Instanz!

Im Checkout erhält die Bestellung beim Wechsel auf die Bestätigungsseite den Status prepared. Klickt der Käufer auf „Mit PayPal bezahlen“, wird er zu PayPal weitergeleitet (Login + Zahlung).

• Abbruch bei PayPal: Klickt der Käufer auf „Abbrechen und zurück…“, wird er in den Shop zur Seite cancelPid umgeleitet. Es erscheint die Meldung „Ihre Bestellung wurde abgebrochen“, und die Bestellung wird auf canceled gesetzt. Startet der Käufer den Checkout erneut, wird derselbe Bestelldatensatz weiterverwendet (es existiert noch keine Bestell-/Rechnungsnummer).
• Erfolgreiche Zahlung: Nach erfolgreicher PayPal-Zahlung wird der Käufer zur Seite successPid weitergeleitet und die Bestellung bekommt den Status paid.

stateDiagram-v2
    %% Frontend
    [*] --> prepared : Kunde stellt Warenkorb zusammen\nund startet Checkout
    prepared --> ordered : Checkout abgeschlossen
    %% Stripe Payment
    ordered --> paid : Zahlung von PayPay bestätigt\nBestätigungsmail\nRechnungsnummer
    %% Versand & Abschluss
    paid --> shipped : Versand manuell durchgeführt
    paid --> processed : Abschluss ohne Versand\n(z. B. digitale Leistung)
    shipped --> processed : Abschluss nach Versand
    %% Sonderfall: Abbruch vor Zahlung (selten bei Stripe)
    prepared --> canceled : Zahlung fehlgeschlagen\noder abgebrochen
    canceled --> prepared : Zahlung kann erneut\nversucht werden
    %% Conditions
    note right of processed
      Conditions:
      - paid_date MUSS gesetzt sein
      - shipped_date MUSS gesetzt sein,
        falls Versand erfolgt ist
    end note

Weitere Aktionen:

• Retoure: Möglich sobald die Ware versandt wurde – d. h. im Zustand shipped oder processed.
• Löechen: Das Löschen einer Bestellung ist nur im Status prepared möglich.

PayPal-Account

Zuerst benötigst Du einen PayPal-Account. Logge Dich damit ein und öffne https://developer.paypal.com. Hier musst Du nun unter dem Menüpunkt My Apps & Credentials eine neue App erstellen. Dabei musst Du im ersten Schritt darauf achten, ob Du einen Live oder Sandbox Account erstellen möchtest. Nach dem Erstellen solltest Du folgende Informationen erhalten haben:

• (Sandbox) Account: Dies ist eine E-Mailadresse.
• Client ID: Dies ist ein Hashwert, der den Client identifiziert.
• Secret: Dies ist ebenfalls ein Hashwert. Diesen sollten auf jeden Fall geheim halten!

Für die Einrichtung des PayPal-Checkouts benötigst Du nur den (Sandbox) Account. (Siehe Felder sandbox und payPalId im Abschnitt Checkout Konfiguration). Die payPalId ist hierbei die Account-ID von PayPal und ist im Live Mode unter dem Profil -> Kontoeinstellungen -> Unternehmensprofil -> Geschäftsangaben zu finden.

Zum Testen benötigst Du einen weiteren Account, welchen Du unter https://developer.paypal.com/developer/accounts/ anlegen kannst.

Achtung:

Wenn Deine Umgebung durch ein Passwort geschützt ist, kann der Webhook nicht aufgerufen werden. Bitte stelle sicher, dass der Webhook direkt aufrufbar ist.

Checkout Konfiguration

• active Hier kann der Check-out aktiviert/deaktiviert werden
• checkoutPid Hier muss die Page-Uid der Checkout-Seite angegeben werden.
• successPid Hier muss die Page-Uid der Erfolgs-Seite angegeben werden. Dies ist die Seite, auf die man weitergeleitet wird, wenn die Zahlung erfolgreich war.
• cancelPid Hier muss die Page-Uid der Cancel-Seite angegeben werden. Dies ist die Seite, auf die man weitergeleitet wird, wenn man den Zahlungsprozess abgebrochen hat.
• callbackPid Hier muss die Page-Uid der Callback-Seite angegeben werden. Die Callback-Seite ist eine Seite, die von PayPal asynchron aufgerufen wird, um die Bezahlung zu bestätigen.
• service Hier wird die Checkout-Service PHP-Klasse zugewiesen. Diese kann angepasst werden, wenn etwas am Prozess verändert werden muss.
• sandbox Hier kann die Sandbox zum Testen aktiviert/deaktiviert werden.
• payPalId Hier muss der (Sandbox) Account Name eingetragen werden, welche bei PayPal erstellt wurde

Aktionen nach erfolgreicher Bezahlung

Wenn Du nach der erfolgreichen Bezahlung weitere Aktionen durchführen möchtest, kannst Du dazu den PayPalPaid Event Listener nutzen.

1. Dazu muss ein Event Listener erstellt werden:

   <?php
   namespace YourVendor\YourExtension\EventListener;
   use CodingMs\ShopPro\Event\BasketOrder\PayPalPaidPaidEvent;
   class DoSomeThingEventListener
   {
       public function __invoke(PayPalPaidPaidEvent $event): void
       {
           /* Do something */
       }
   }

2. Dieser Event Listener muss anschließend in der Configuration/Services.yaml registriert werden:

   services:
       YourVendor\YourExtension\EventListener\DoSomeThingEventListener:
           tags:
               - name: event.listener
                 identifier: 'myListener'
                 event: CodingMs\ShopPro\Event\BasketOrder\PayPalPaidPaidEvent

Debugging

Für den Fall, dass der Callback-Aufruf nicht funktioniert, kannst Du ein Debugging aktivieren. Wie dies funktioniert, kannst Du im Abschnitt HowTo/Debugging lesen.

Testing

Zum Testen der PayPal Callbacks am besten im https://developer.paypal.com einloggen (hier musst Du Deine echten Zugangsdaten verwenden). Hier musst Du unter SANDBOX den IPN Simulator aufrufen (https://developer.paypal.com/dashboard/ipnSimulator).

Im Feld IPN handler URL fügst Du Deine Callback-URL ein und wählst dann bei Transaction type den Wert Cart checkout aus. Nun erscheinen unter dem Formular eine vielzahl an Formularfeldern. Hier musst Du in dem Feld item_number die Uid Deine Basket-Order eintragen, damit der Callback die entsprechende Order wiederfindet.

Der Aufruf der Checkout-Success Seite endet mit einem 404-Fehler

Der Aufruf der Checkout-Success Seite ergibt ein:

Page Not Found
Reason: Request parameters could not be validated (&cHash empty)

Lösung 1.:

Öffne das Installtool und deaktiviere die Einstellung pageNotFoundOnCHashError: [FE][pageNotFoundOnCHashError] = false

Lösung 2.

Entferne die Parameter des Requests aus der cHash Berechnung (LocalConfigration/settings.php):

'FE' => [
    'cacheHash' => [
        'enforceValidation' => true,
        'excludedParameters' => [
            'PayerID',
        ],
    ],
],