PPC- (PayPal Checkout) - WEBSALE Dokumentation

Bei PayPal Checkout läuft ein großer Teil des Bezahlvorgangs im Browser des Käufers. Der Shop bindet das PayPal-SDK ein, PayPal zeigt seine Schaltflächen an, und nach der Bestätigung durch den Käufer schickt das SDK ihn auf eine Adresse zurück, die der Shop vorgegeben hat. Die PPC-Tags liefern die Bausteine für diesen Austausch: die Zugangsdaten für die SDK-Adresse, die drei Rücksprungadressen, die Fehlerauswertung und alles rund um das gespeicherte PayPal-Konto. Wegweiser: PayPal Checkout

Läuft diese Zahlungsart über PayPal Checkout

Über PayPal Checkout sind nicht nur PayPal selbst angebunden, sondern auch Kreditkarte, Lastschrift, Rechnungskauf und weitere Verfahren. Welche davon ein Shop darüber abwickelt, entscheidet seine Konfiguration. PPC-UsePayPalCheckout beantwortet die Frage für die gerade gewählte Zahlungsart.

{PPC-UsePayPalCheckout}
   <div id="paypal-button-container"></div>
{/PPC-UsePayPalCheckout}

Im Express Checkout greift die positive Klammerung nicht. Dort ist noch keine Zahlungsart gewählt, und die Einbindung läuft über eigene Zustände. Die Klammerung greift außerdem nicht, wenn für den Käufer bereits ein gespeichertes PayPal-Konto vorliegt und er es verwenden will. In diesem Fall braucht die Seite die PayPal-Schaltflächen nicht mehr, weil die Zahlung ohne erneute Anmeldung läuft.

Das PayPal-SDK einbinden

Die Adresse des SDK-Skripts setzen Sie aus mehreren Angaben zusammen. Jede davon hat ein eigenes Tag.

Tag	Liefert
`PPC-ClientID`	die ClientID des Shops bei PayPal
`PPC-MerchantID`	die MerchantID des Shops
`PPC-Intent`	den Intent, also ob sofort abgebucht oder nur autorisiert wird
`PPC-IntegrationDate`	das Integrationsdatum
`PPC-ClientToken`	den Client-Token, nur für die Kreditkartenzahlung

{PPC-UsePayPalCheckout}
   <script src="https://www.paypal.com/sdk/js?client-id=~PPC-ClientID~&merchant-id=~PPC-MerchantID~&intent=~PPC-Intent~&integration-date=~PPC-IntegrationDate~"></script>
{/PPC-UsePayPalCheckout}

PPC-ClientID und PPC-MerchantID nehmen den Zahlungsarten-Code als Argument entgegen. Ohne Argument nehmen sie die gerade gewählte Zahlungsart. Gehört die nicht zu PayPal Checkout, bleibt die Ausgabe leer.

Auf der Warenkorbseite ist noch keine Zahlungsart gewählt. Für den Express Checkout müssen Sie den Zahlungsarten-Code deshalb ausdrücklich mitgeben, also ~PPC-ClientID(37)~ und ~PPC-MerchantID(37)~. Ohne Argument bekommen Sie dort nichts.

Materialien: Zahlungsarten-Codes PPC-Sandbox greift, wenn die Zahlungsart gerade gegen die Testumgebung von PayPal läuft. Damit lassen sich Testhinweise einblenden, die im Livebetrieb von selbst verschwinden.

{PPC-Sandbox}
   <p class="hinweis">Testumgebung. Es findet keine echte Zahlung statt.</p>
{/PPC-Sandbox}

Die Rücksprungadressen

Das SDK ruft je nach Ausgang des Vorgangs eine andere Adresse auf. Alle vier liefert das Shopsystem fertig.

Tag	Wird aufgerufen
`PPC-OnApproveLink`	nachdem der Käufer die Zahlung bestätigt hat
`PPC-OnCancelLink`	wenn der Käufer abbricht
`PPC-OnErrorLink`	wenn ein Fehler auftritt
`PPC-PendingLink`	für die Warteseite, solange PayPal den Vorgang noch prüft

<script>
   paypal.Buttons({
      onApprove: () => { window.location.href = "~PPC-OnApproveLink~" },
      onCancel:  () => { window.location.href = "~PPC-OnCancelLink~" },
      onError:   () => { window.location.href = "~PPC-OnErrorLink~" }
   }).render("#paypal-button-container");
</script>

Die Warteseite braucht PPC-PendingLink für sich selbst. Sie lädt sich in Abständen neu, bis PayPal den Vorgang abgeschlossen hat.

<head>
   <meta http-equiv="Refresh" content="5;url=~PPC-PendingLink~">
</head>

Fehler von PayPal auswerten

Lehnt PayPal den Vorgang ab, liefert die Antwort einen Fehlercode. PPC-PayPalErrorCode greift als Klammerung, wenn überhaupt ein Code vorliegt, und mit einem Code im Argument nur bei genau diesem.

{PPC-PayPalErrorCode(PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED)}
   <p class="fehler">
      Die Kombination aus Ihrem Namen und Ihrer Anschrift konnte nicht validiert werden.
      Bitte korrigieren Sie Ihre Daten und versuchen Sie es erneut.
   </p>
{/PPC-PayPalErrorCode(PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED)}

{PPC-PayPalErrorCode}
   {!PPC-PayPalErrorCode(PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED)}
      <p class="fehler">
         Die gewählte Zahlungsart kann derzeit nicht genutzt werden.
         Bitte wählen Sie eine andere.
      </p>
   {/!PPC-PayPalErrorCode(PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED)}
{/PPC-PayPalErrorCode}

Die äußere Klammerung ohne Argument fängt alle übrigen Codes ab. Ohne sie würde der allgemeine Hinweis auch dann erscheinen, wenn gar kein Fehler vorliegt.

Beim Rechnungskauf über PayPal gibt der Dienstleister Ratepay den Wortlaut der Ablehnungstexte vor, einschließlich der Verweise auf seine Datenschutzbestimmungen und sein Kontaktformular. Übernehmen Sie diese Texte unverändert und formulieren Sie sie nicht um.

Der Code steht in der Antwort von PayPal unter details.issue. Welche Codes vorkommen können, hängt von der Zahlungsart ab und steht in der Dokumentation von PayPal.

Das PayPal-Konto speichern

Ein angemeldeter Käufer kann sein PayPal-Konto im Shop hinterlegen und beim nächsten Mal ohne erneute Anmeldung bezahlen.

Tag	Liefert
`PPC-Vaulted`	greift, wenn für den Käufer ein PayPal-Konto gespeichert ist
`PPC-VaultedEmailAddress`	die E-Mail-Adresse des gespeicherten Kontos
`PPC-VaultedPayment`	greift, wenn gerade mit dem gespeicherten Konto bezahlt wird
`PPC-UserIDToken`	das Token, das die Speicherung gegenüber PayPal ausweist

{PPC-Vaulted}
   <p>Sie zahlen mit ~PPC-VaultedEmailAddress~.</p>
{/PPC-Vaulted}

{!PPC-Vaulted}
   <label>
      <input type="checkbox" name="~WS-PPCSaveInVault_input~" ~WS-PPCSaveInVault_checked~>
      PayPal-Konto für zukünftige Zahlungen speichern
   </label>
{/!PPC-Vaulted}

PPC-Vaulted und PPC-VaultedEmailAddress greifen nur, solange die Speicherung im Shop überhaupt freigeschaltet ist. Ist sie abgeschaltet, bleiben beide still, und die negative Klammerung zeigt das Angebot zum Speichern. Blenden Sie dieses Angebot deshalb zusätzlich über die Konfiguration aus, wenn es im Shop nicht gelten soll. PPC-UserIDToken ist kein passiver Wert. Das Shopsystem holt das Token bei PayPal ab, sobald das Tag ausgewertet wird. Setzen Sie es deshalb nur dort, wo es gebraucht wird. Auf der Bestellübersicht liefert PPC-UserIDToken nur dann einen Wert, wenn der Käufer das Speichern angekreuzt hat. Auf der Verwaltungsseite liefert es einen Wert, solange noch kein Konto gespeichert ist.

Die Verwaltungsseite für das gespeicherte Konto

Das Template PPCVaultManage zeigt dem Käufer sein gespeichertes Konto und lässt ihn es anlegen oder löschen. Es hat zwei Zustände.

Tag	Zeigt
`PPC-VaultOverview`	die Übersicht über das gespeicherte Konto
`PPC-VaultConfirmDelete`	die Rückfrage vor dem Löschen

Tag	Liefert den Link
`PPC-DeleteVaultConfirm`	zur Rückfrage vor dem Löschen
`PPC-DeleteVaultNoConfirm`	der sofort löscht
`PPC-CreateSetupTokenLink`	über den das SDK ein Setup-Token holt
`PPC-CreatePaymentTokenLink`	über den aus dem Setup-Token ein gespeichertes Konto wird

{PPC-VaultOverview}
   {PPC-Vaulted}
      <p>Gespeichertes Konto: ~PPC-VaultedEmailAddress~</p>
      <a href="~PPC-DeleteVaultConfirm~">Verbindung mit PayPal löschen</a>
   {/PPC-Vaulted}

   {!PPC-Vaulted}
      <div id="ppcbtn-div"></div>
   {/!PPC-Vaulted}
{/PPC-VaultOverview}

{PPC-VaultConfirmDelete}
   <p>Möchten Sie die Verbindung mit PayPal wirklich löschen?</p>
   <a href="~PPC-DeleteVaultNoConfirm~">ja, löschen</a>
{/PPC-VaultConfirmDelete}

PPC-DeleteVaultConfirm löscht nichts. Es führt auf die Rückfrage, also in den Bereich PPC-VaultConfirmDelete. Gelöscht wird erst über PPC-DeleteVaultNoConfirm. Setzen Sie dieses zweite Tag deshalb nur innerhalb der Rückfrage und nicht in der Übersicht.Beide Links geben nichts aus, solange kein Konto gespeichert ist. Im Markup steht dann ein leeres href. Klammern Sie sie deshalb mit {PPC-Vaulted}, wie im Beispiel.

Die beiden Token-Links bedienen die PayPal-Schaltfläche auf der Verwaltungsseite. Das SDK holt sich über den ersten ein Setup-Token, und der zweite macht daraus die dauerhafte Speicherung.

<script>
   window.paypal.Buttons({
      createVaultSetupToken: async () => {
         const result = await fetch("~PPC-CreateSetupTokenLink~")
         const data = await result.json()
         return data.ppc_setuptoken
      },
      onApprove: (data) => {
         const url = new URL("~PPC-CreatePaymentTokenLink~")
         url.searchParams.append("ppc_setuptoken", data.vaultSetupToken)
         window.location.replace(url)
      }
   }).render("#ppcbtn-div")
</script>

Die Rohantworten von PayPal

Drei Tags geben die Antworten von PayPal unverändert als JSON aus.

Tag	Liefert die Antwort auf
`PPC-CreateOrderRawResponse`	das Anlegen des Vorgangs
`PPC-OrderDetailsRawResponse`	die Abfrage der Vorgangsdaten
`PPC-CaptureAuthorizeRawResponse`	die Abbuchung oder Autorisierung

PPC-OrderDetailsRawResponse ist nicht nur zur Fehlersuche gedacht. Über die JSON-Schnittstelle holen Sie einzelne Werte daraus, beispielsweise die von PayPal gelieferte Adresse.

~EJD-SetRawDataHexCodedInput($PPC-OrderDetailsRawResponse$)~

Referenz: EJD- (JSON-Schnittstelle)

Die anderen beiden Rohantworten enthalten vollständige Vorgangsdaten. Geben Sie sie nicht auf einer Seite aus, die ein Käufer im Livebetrieb erreichen kann.

Im Shopsystem vorhanden, bisher nicht beschrieben

Zehn weitere PPC-Tags sind im Shopsystem angelegt. Neun davon gehören zu Google Pay und Apple Pay über PayPal Checkout.

Tag	Liefert
`PPC-OrderID`	die Vorgangskennung bei PayPal
`PPC-PaymentDataName`	den Feldnamen für die Zahlungsdaten
`PPC-PaymentDataRawResponse`	die Zahlungsdaten als Rohantwort
`PPC-GPayTransactionInfo`	die Transaktionsangaben für Google Pay
`PPC-GPayExpressOnPaymentDataChangedLink`	die Rückrufadresse für geänderte Zahlungsdaten bei Google Pay
`PPC-APayBrandName`	den für Apple Pay hinterlegten Markennamen
`PPC-APayBillingContact`	die Rechnungsadresse für Apple Pay
`PPC-APayLineItems`	die Bestellpositionen für Apple Pay
`PPC-APayExpressCompleteShippingContactSelectionLink`	die Rückrufadresse nach der Adresswahl bei Apple Pay
`PPC-APayExpressCompleteShippingMethodSelectionLink`	die Rückrufadresse nach der Versandartwahl bei Apple Pay

Diese Tags sind hier nur aufgeführt, damit sie beim Lesen fremder Templates nicht rätselhaft bleiben. Bevor sie als zugesagte Schnittstelle gelten, müssen sie bestätigt werden.

Tags anderer Präfixe zu diesem Thema

Die Funktion erstreckt sich über mehrere Präfixe. Die übrigen Tags sind bei ihrem jeweiligen Präfix beschrieben.

Express Checkout, Schaltflächen: BT-PPCExpress, BT-PPCExpress_cancel und BT-PPCExpress_reload stehen bei BT- (Schaltflächen)
Express Checkout, Zustände: ST-PPCExpress und die fünf Varianten _allowed, _cancel, _error, _locked und _selected stehen bei ST- (Seitenzustände)
Eingabefelder und Links: WS-PPCSaveInVault_input, WS-PPCSaveInVault_checked, WS-PPCVaultManageLink sowie WS-PPCExpressUseDeliveryAddressForBilling_input und _checked stehen bei WS- (Allgemeine Tags)
Meldung: MSG-PPCVault_Notify steht bei MSG- (Meldungen)

Die Tags im Überblick

Tag	Einzel-Tag	Bereichs-Tag	negatives Bereichs-Tag	Schleifen-Tag
`PPC-UsePayPalCheckout`	–	ja	ja	–
`PPC-ClientID(<Zahlungsarten-Code>)`	ja	–	–	–
`PPC-MerchantID(<Zahlungsarten-Code>)`	ja	–	–	–
`PPC-ClientToken`	ja	–	–	–
`PPC-Intent`	ja	–	–	–
`PPC-IntegrationDate`	ja	–	–	–
`PPC-Sandbox`	–	ja	ja	–
`PPC-OnApproveLink`	ja	–	–	–
`PPC-OnCancelLink`	ja	–	–	–
`PPC-OnErrorLink`	ja	–	–	–
`PPC-PendingLink`	ja	–	–	–
`PPC-PayPalErrorCode(<Code>)`	ja	ja	ja	–
`PPC-Vaulted`	–	ja	ja	–
`PPC-VaultedPayment`	–	ja	ja	–
`PPC-VaultedEmailAddress`	ja	ja	ja	–
`PPC-UserIDToken`	ja	ja	ja	–
`PPC-VaultOverview`	–	ja	ja	–
`PPC-VaultConfirmDelete`	–	ja	ja	–
`PPC-DeleteVaultConfirm`	ja	–	–	–
`PPC-DeleteVaultNoConfirm`	ja	–	–	–
`PPC-CreateSetupTokenLink`	ja	–	–	–
`PPC-CreatePaymentTokenLink`	ja	–	–	–
`PPC-CreateOrderRawResponse`	ja	ja	ja	–
`PPC-OrderDetailsRawResponse`	ja	ja	ja	–
`PPC-CaptureAuthorizeRawResponse`	ja	ja	ja	–

Alle Tags sind auf allen Templates zulässig. Die Tags rund um die Verwaltung des gespeicherten Kontos liefern nur auf dem Template PPCVaultManage sinnvolle Werte.

​Läuft diese Zahlungsart über PayPal Checkout

​Das PayPal-SDK einbinden

​Die Rücksprungadressen

​Fehler von PayPal auswerten

​Das PayPal-Konto speichern

​Die Verwaltungsseite für das gespeicherte Konto

​Die Rohantworten von PayPal

​Im Shopsystem vorhanden, bisher nicht beschrieben

​Tags anderer Präfixe zu diesem Thema

​Die Tags im Überblick

​Verwandte Themen

Läuft diese Zahlungsart über PayPal Checkout

Das PayPal-SDK einbinden

Die Rücksprungadressen

Fehler von PayPal auswerten

Das PayPal-Konto speichern

Die Verwaltungsseite für das gespeicherte Konto

Die Rohantworten von PayPal

Im Shopsystem vorhanden, bisher nicht beschrieben

Tags anderer Präfixe zu diesem Thema

Die Tags im Überblick

Verwandte Themen