> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# PPC- (PayPal Checkout)

> Die Anbindung über PayPal Checkout im Template bauen: das PayPal-SDK einbinden, die Rücksprungadressen setzen, Fehler auswerten und das PayPal-Konto des Käufers speichern und verwalten.

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](https://dokumentation.websale.de/v8s/zahlungsarten-anlegen/paypal-checkout.md)

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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

> [!WARNING]
>
> 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](https://dokumentation.websale.de/v8s/materialien/zahlungsarten-codes.md)

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

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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.

> [!WARNING]
>
> 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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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 |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{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}
```

> [!WARNING]
>
> `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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
~EJD-SetRawDataHexCodedInput($PPC-OrderDetailsRawResponse$)~
```

Referenz: [EJD- (JSON-Schnittstelle)](https://dokumentation.websale.de/v8s/referenz/tags/ejd.md)

> [!WARNING]
>
> 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)](https://dokumentation.websale.de/v8s/referenz/tags/bt/adressen.md)
* **Express Checkout, Zustände**: `ST-PPCExpress` und die fünf Varianten `_allowed`, `_cancel`, `_error`, `_locked` und `_selected` stehen bei [ST- (Seitenzustände)](https://dokumentation.websale.de/v8s/referenz/tags/st/seitenzustand-und-navigation.md)
* **Eingabefelder und Links**: `WS-PPCSaveInVault_input`, `WS-PPCSaveInVault_checked`, `WS-PPCVaultManageLink` sowie `WS-PPCExpressUseDeliveryAddressForBilling_input` und `_checked` stehen bei [WS- (Allgemeine Tags)](https://dokumentation.websale.de/v8s/referenz/tags/ws/bestellprozess-adressen-und-pruefungen.md)
* **Meldung**: `MSG-PPCVault_Notify` steht bei [MSG- (Meldungen)](https://dokumentation.websale.de/v8s/referenz/tags/msg-meldungen.md)

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

## Verwandte Themen

* Wegweiser: [PayPal Checkout](https://dokumentation.websale.de/v8s/zahlungsarten-anlegen/paypal-checkout.md)
* Referenz: [PAY- (Zahlungsarten anzeigen und auswählen)](https://dokumentation.websale.de/v8s/referenz/tags/pay/zahlungsarten-anzeigen-und-auswaehlen.md)
* Referenz: [EJD- (JSON-Schnittstelle)](https://dokumentation.websale.de/v8s/referenz/tags/ejd.md)
* Materialien: [Zahlungsarten-Codes](https://dokumentation.websale.de/v8s/materialien/zahlungsarten-codes.md)


## Related topics

- [PPP- (PayPal PLUS)](https://dokumentation.websale.de/v8s/referenz/tags/ppp-paypal-plus.md)
- [PayPal Checkout](https://dokumentation.websale.de/v8s/zahlungsarten-anlegen/paypal-checkout.md)
- [Schaltflächen der Zahlungsarten](https://dokumentation.websale.de/v8s/referenz/tags/bt/zahlungsarten.md)
- [PayPal](https://dokumentation.websale.de/v8s/zahlungsarten-anlegen/paypal.md)
- [$wsPayPalCheckout - PayPal](https://dokumentation.websale.de/frontend/referenz/module/wspaypalcheckout.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.