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

# $wsPayPalCheckout - PayPal

> Modul $wsPayPalCheckout: PayPal Express Checkout, Google Pay und Apple Pay im Frontend einbinden und den aktuellen Zahlungsstatus auswerten.

Mit dem `$wsPayPalCheckout` Modul können Sie PayPal-Zahlungsdaten dynamisch im Frontend verwenden. Es unterstützt verschiedene Zahlungsmethoden wie PayPal Express Checkout, Google Pay und Apple Pay. In diesem Abschnitt erfahren Sie, wie Sie den Zahlungsstatus abfragen und die Payment-Daten für die Integration nutzen können.

***

## Modulübersicht

**Beispiel / Ausschnitt über** `$wsPayPalCheckout`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsPayPalCheckout | json }}
```

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "integrationDate": "...",
  "status": "...",
  "paymentCanceled": false,
  "paymentFailed": false,
  "paymentDeclined": false,
  "expressCheckout": false,
  "expressCheckoutGooglePay": false,
  "expressCheckoutApplePay": false,
  "googlePay": {
    "paymentData": "...",
    "transactionInfo": {
      "countryCode": "...",
      "currencyCode": "...",
      "displayItems": [...],
      "totalPrice": "...",
      "totalPriceLabel": "...",
      "totalPriceStatus": "..."
    }
  },
  "applePay": {
    "billingContact": { },
    "brandName": "...",
    "payLineItems": [...],
    "paymentData": "...",
    "shippingOptions": [...]
  },
  "clientMetadataId": "...",
  "loadData": "ƒ()"
}
```

**Anmerkung:** `ƒ()` kennzeichnet eine Funktion.

**Variablen und Methoden in der Übersicht**

| **Variable**               | **Rückgabe-Typ** | **Beschreibung**                                                                          |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `integrationDate`          | string           | Gibt das PayPal Checkout Integrationsdatum aus.                                           |
| `status`                   | string           | Gibt den aktuellen Payment-Status der Session aus.                                        |
| `paymentCanceled`          | bool             | Gibt an, ob die Zahlung abgebrochen wurde.                                                |
| `paymentFailed`            | bool             | Gibt an, ob die Zahlung fehlgeschlagen ist.                                               |
| `paymentDeclined`          | bool             | Gibt an, ob die Zahlung abgelehnt wurde.                                                  |
| `expressCheckout`          | bool             | Gibt an, ob PayPal Express Checkout möglich ist.                                          |
| `expressCheckoutGooglePay` | bool             | Gibt an, ob Google Pay Express möglich ist.                                               |
| `expressCheckoutApplePay`  | bool             | Gibt an, ob Apple Pay Express möglich ist.                                                |
| `googlePay`                | map              | Gibt Google-Pay-spezifische Daten aus.                                                    |
| `applePay`                 | map              | Gibt Apple-Pay-spezifische Daten aus.                                                     |
| `clientMetadataId`         | string           | Client-Metadata-ID für die PayPal-SDK-Integration (die ersten 32 Zeichen der Session-ID). |
| `loadData()`               | map              | Lädt die Payment-Daten für die PayPal-Checkout-Integration.                               |

***

## Templates

Das \$wsPayPalCheckout Modul wird typischerweise im Checkout-Bereich verwendet, insbesondere auf der Zahlungsseite und der Bestellbestätigung. Die PayPal-Buttons können auch auf Produktseiten oder im Warenkorb für Express-Checkout eingebunden werden.

***

## Variablen

### \$wsPayPalCheckout.integrationDate

Gibt das Integrationsdatum der PayPal-Anbindung aus.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Integrationsdatum: {{= $wsPayPalCheckout.integrationDate }}
```

### \$wsPayPalCheckout.status

Gibt den Status der PayPal-Zahlung aus (leer, wenn kein Zahlungsvorgang aktiv).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Status: {{= $wsPayPalCheckout.status }}
```

### \$wsPayPalCheckout.paymentCanceled

Gibt `true` aus, wenn der Kunde die Zahlung abgebrochen hat.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.paymentCanceled }}
    // Zahlung wurde abgebrochen
{{ /if }}
```

### \$wsPayPalCheckout.paymentFailed

Gibt `true` aus, wenn ein technischer Fehler bei der Zahlung aufgetreten ist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.paymentFailed }}
    // Zahlung ist fehlgeschlagen
{{ /if }}
```

### \$wsPayPalCheckout.paymentDeclined

Gibt `true` aus, wenn die Zahlung von PayPal oder der Bank abgelehnt wurde.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.paymentDeclined }}
    // Zahlung wurde abgelehnt
{{ /if }}
```

### \$wsPayPalCheckout.expressCheckout

Gibt an, ob PayPal Express Checkout möglich ist ([`expressCheckoutAllow`](/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration) aktiv und Bestellwert größer 0).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.expressCheckout }}
    // PayPal Express Checkout anzeigen
{{ /if }}
```

### \$wsPayPalCheckout.expressCheckoutGooglePay

Gibt an, ob Google Pay Express möglich ist (`expressCheckoutGooglePayAllow` aktiv und Bestellwert größer 0).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.expressCheckoutGooglePay }}
    // Google Pay anzeigen
{{ /if }}
```

### \$wsPayPalCheckout.expressCheckoutApplePay

Gibt an, ob Apple Pay Express möglich ist (`expressCheckoutApplePayAllow` aktiv und Bestellwert größer 0).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsPayPalCheckout.expressCheckoutApplePay }}
    // Apple Pay anzeigen
{{ /if }}
```

### \$wsPayPalCheckout.googlePay

Gibt eine Map mit Google Pay spezifischen Inhalten aus.

| **Eigenschaft**   | **Typ** | **Beschreibung**                                                                               |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `paymentData`     | string  | Antwortdaten von Google Pay (unverarbeitet).                                                   |
| `transactionInfo` | map     | Map mit Transaktionsinfos von Google Pay (u. a. `totalPrice`, `currencyCode`, `displayItems`). |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Google-Pay-Daten: {{= $wsPayPalCheckout.googlePay | json }}
```

### \$wsPayPalCheckout.applePay

Gibt eine Map mit Apple Pay spezifischen Daten aus.

| **Eigenschaft**   | **Typ** | **Beschreibung**                                                                                                                                                                         |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shippingOptions` | array   | Versandoptionen für das Apple-Pay-Sheet: je Eintrag `identifier` (Versandart-ID), `label`, `detail`, `amount`. Enthält nur aktive, für den Warenkorb gültige Versandarten.               |
| `billingContact`  | map     | Rechnungsadresse im Apple-Pay-Kontaktformat (u. a. `givenName`, `familyName`, `addressLines`, `postalCode`, `locality`, `countryCode`). `null`, wenn keine Rechnungsadresse gewählt ist. |
| `payLineItems`    | array   | Apple Pay Positionen.                                                                                                                                                                    |
| `brandName`       | string  | Markenname.                                                                                                                                                                              |
| `paymentData`     | string  | Antwortdaten von Apple Pay (unverarbeitet).                                                                                                                                              |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
Apple-Pay-Daten: {{= $wsPayPalCheckout.applePay | json }}
```

### \$wsPayPalCheckout.clientMetadataId

Gibt die Client-Metadata-ID für die PayPal-SDK-Integration aus (z. B. für das `data-client-metadata-id`-Attribut beim Einbinden des SDK-Skripts). Der Wert entspricht den ersten 32 Zeichen der Session-ID.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script src="https://www.paypal.com/sdk/js?..." data-client-metadata-id="{{= $wsPayPalCheckout.clientMetadataId }}"></script>
```

***

## Methoden

### \$wsPayPalCheckout.loadData()

Lädt die Payment-Daten für die PayPal-Checkout-Integration (SDK-Parameter, URLs, Order-ID). Gibt `null` zurück, wenn aktuell kein PayPal-Zahlvorgang aktiv ist - also keine PayPal-Checkout-Zahlungsart gewählt bzw. verfügbar ist.

**Signatur**\
`$wsPayPalCheckout.loadData(expressCheckout)`

**Rückgabe**\
`Map` - Map mit Payment-Daten oder `null`.

**Parameter**

| **Name**          | **Typ** | **Pflicht** | **Beschreibung**                                                                                                                                                                                                                                           |
| ----------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expressCheckout` | string  | nein        | Nur der exakte Wert `"express"` hat eine Wirkung: Die Prüfung, ob eine PayPal-Zahlungsart gewählt ist, wird übersprungen - nötig für den Express-Checkout, bei dem zu Beginn noch keine Zahlungsart gewählt ist. Die zurückgegebenen Daten sind identisch. |

**Beispiel,** das die Payment-Daten lädt.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myPaypalDataVariable = $wsPayPalCheckout.loadData() }}
{{ if $myPaypalDataVariable }}
    // Payment-Daten verfügbar
{{ /if }}
```

**Beispiel** für den Express-Checkout (z. B. im Warenkorb, bevor eine Zahlungsart gewählt wurde):

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myPaypalDataVariable = $wsPayPalCheckout.loadData("express") }}
```

<Info>
  Mit Verwendung der Funktion `$wsPayPalCheckout.loadData()` stehen verschiedene Variablen zur Verfügung, um Payment-Daten abzurufen und auszugeben. Nachfolgend eine Übersicht, welche Variablen verfügbar sind.
</Info>

### Payment-Daten (Rückgabe von `$wsPayPalCheckout.loadData()` )

Zunächst ist es notwendig, die Map mit den Payment-Daten, wie im obigen Beispiel dargestellt, einer lokalen Variable zuzuweisen. Diese kann anschließend an verschiedenen Stellen im Template verwendet werden.

**JSON-Ausgabe der Variablen**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "sandbox": true/false,
  "merchantId": "...",
  "payerId": "...",
  "clientId": "...",
  "paymentType": "paypal",
  "languageCode": "...",
  "intent": "capture",
  "approvalUrl": "...",
  "cancelUrl": "...",
  "errorUrl": "...",
  "expressApprovalUrl": "...",
  "getClientToken": "ƒ()",
  "orderId": "..."
}
```

**Variablen in der Übersicht**

| **Variable**         | **Typ**  | **Beschreibung**                                                                                                                                                                                               |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sandbox`            | bool     | Gibt an, ob der Sandbox-Modus (Testmodus für Zahlungsarten) aktiv ist.                                                                                                                                         |
| `merchantId`         | string   | PayPal Merchant-ID des Händlerkontos (identisch mit `payerId`; entspricht [`payment.payPalCheckout.payerId`](/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration)). |
| `payerId`            | string   | PayPal Merchant-ID des Händlerkontos (identisch mit `merchantId`). Beide Namen werden bereitgestellt, weil das PayPal-SDK den Wert je nach Kontext unter beiden Bezeichnungen erwartet.                        |
| `clientId`           | string   | PayPal Client-ID.                                                                                                                                                                                              |
| `paymentType`        | string   | Zahlungstyp (Standard: “`paypal`”).                                                                                                                                                                            |
| `languageCode`       | string   | Sprachcode.                                                                                                                                                                                                    |
| `intent`             | string   | PayPal-Intent der Transaktion (z. B. `"capture"`), für den SDK-Parameter `intent`.                                                                                                                             |
| `approvalUrl`        | string   | URL für die Payment-Bestätigung.                                                                                                                                                                               |
| `cancelUrl`          | string   | URL bei Abbruch der Zahlung.                                                                                                                                                                                   |
| `errorUrl`           | string   | URL bei aufgetretenen Fehlern.                                                                                                                                                                                 |
| `expressApprovalUrl` | string   | URL bei erfolgreicher Express-Zahlung.                                                                                                                                                                         |
| `getClientToken`     | function | Funktion, die den Client-Token für die PayPal-SDK-Integration zurückgibt (`null`, wenn kein Token ermittelt werden kann).                                                                                      |
| `orderId`            | string   | PayPal Order-ID der aktuellen Transaktion.                                                                                                                                                                     |

<Warning>
  `googlePay` und `applePay` sind **nicht** Teil der `loadData()`-Rückgabe. Diese Maps stehen direkt am Modul zur Verfügung: [`$wsPayPalCheckout.googlePay`](#wspaypalcheckout-googlepay) und [`$wsPayPalCheckout.applePay`](#wspaypalcheckout-applepay).
</Warning>

***

## Aktionen

Das PayPal-Checkout-Plugin registriert fünf Aktionen. Sie sind für die JavaScript-Integration der PayPal-SDK-Callbacks gedacht: Sie werden per POST aufgerufen (Aktion wie üblich über `$wsActions.create(...)` erzeugen und `wsact`/`wscsrf` mitsenden) und antworten - anders als klassische Formular-Aktionen - direkt mit JSON.

| **Aktion**                        | **Parameter**              | **Beschreibung**                                                                                                                                                                                                                                                                                                 |
| --------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UpdateGooglePayPaymentData`      | `payload` (JSON, optional) | Verarbeitet die Versandauswahl aus dem Google-Pay-Sheet: setzt ggf. die gewählte Versandart und liefert aktualisierte `newShippingOptionParameters` und `newTransactionInfo` (bei ungültiger Versandart zusätzlich `error`) zurück.                                                                              |
| `CompleteApplePayShippingContact` | `payload` (JSON)           | Verarbeitet die Kontakt-/Adressauswahl aus dem Apple-Pay-Sheet und liefert die aktualisierten Summen und Positionen zurück.                                                                                                                                                                                      |
| `CompleteApplePayShippingMethod`  | `payload` (JSON)           | Verarbeitet die Versandart-Auswahl aus dem Apple-Pay-Sheet: setzt die gewählte Versandart, aktualisiert den PayPal-Bestellbetrag und liefert `newTotal` und `newLineItems` (bei ungültiger Versandart zusätzlich `errors`) zurück.                                                                               |
| `CapturePaypalPayment`            | `payload` (JSON)           | Zieht die autorisierte PayPal-Zahlung ein. Antwort: `{"capture": "..."}` mit den Werten `success`, `pending` oder `fail`, bei Fehlern zusätzlich `error`. Im Express-Checkout werden vor dem Einzug die Pflicht-Freifelder und die Checkout-Gültigkeit erneut geprüft und der PayPal-Bestellbetrag aktualisiert. |
| `SavePayPalPaymentData`           | `ppcpaymentdata` (Base64)  | Speichert die Antwortdaten von Apple Pay bzw. Google Pay (Base64-kodiert) in der Session; sie stehen danach in `googlePay.paymentData` bzw. `applePay.paymentData` zur Verfügung.                                                                                                                                |

<Info>
  Die Fehlertexte dieser Aktionen (z. B. `requestEmpty` bei leerem Payload) werden über die Konfigurationsknoten `actions.updateApplePay` bzw. `actions.updateGooglePay` gesteuert.
</Info>

***

## Weiterführende Links

* [payment.payPalCheckout - PayPal Checkout Konfiguration](/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration) - richtet die PayPal-Anbindung ein (Merchant-ID, Modus, Express-Checkout).
* [\$wsCheckout](/frontend/referenz/module/wscheckout) - der Checkout, in den die PayPal-Zahlung eingebettet ist (u. a. `isPPCExpressCheckout`, `isExpressCheckoutLocked`).


## Related topics

- [$wsPayPalCheckout - PayPal](/en/frontend/referenz/module/wspaypalcheckout.md)
- [payment - Payment methods](/en/konfiguration/payment-zahlungsmethoden.md)
- [payment - Zahlungsmethoden](/konfiguration/payment-zahlungsmethoden.md)
- [checkout - Bestellablauf](/konfiguration/checkout-bestellablauf.md)
- [checkout - Order flow](/en/konfiguration/checkout-bestellablauf.md)