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

> Reference for $wsPayPalCheckout: embed PayPal Express Checkout, Google Pay, and Apple Pay in the frontend and evaluate the current payment status.

With the `$wsPayPalCheckout` module, you can use PayPal payment data dynamically in the frontend. It supports various payment methods such as PayPal Express Checkout, Google Pay, and Apple Pay. This section explains how to query the payment status and how to use the payment data for the integration.

***

## Module overview

**Example / excerpt of** `$wsPayPalCheckout`

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

**JSON output**

```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": "ƒ()"
}
```

**Note:** `ƒ()` denotes a function.

**Variables and methods at a glance**

| **Variable**               | **Return type** | **Description**                                                                                |
| -------------------------- | --------------- | ---------------------------------------------------------------------------------------------- |
| `integrationDate`          | string          | Returns the PayPal Checkout integration date.                                                  |
| `status`                   | string          | Returns the current payment status of the session.                                             |
| `paymentCanceled`          | bool            | Indicates whether the payment was canceled.                                                    |
| `paymentFailed`            | bool            | Indicates whether the payment failed.                                                          |
| `paymentDeclined`          | bool            | Indicates whether the payment was declined.                                                    |
| `expressCheckout`          | bool            | Indicates whether PayPal Express Checkout is possible.                                         |
| `expressCheckoutGooglePay` | bool            | Indicates whether Google Pay Express is possible.                                              |
| `expressCheckoutApplePay`  | bool            | Indicates whether Apple Pay Express is possible.                                               |
| `googlePay`                | map             | Returns Google Pay-specific data.                                                              |
| `applePay`                 | map             | Returns Apple Pay-specific data.                                                               |
| `clientMetadataId`         | string          | Client metadata ID for the PayPal SDK integration (the first 32 characters of the session ID). |
| `loadData()`               | map             | Loads the payment data for the PayPal Checkout integration.                                    |

***

## Templates

The `$wsPayPalCheckout` module is typically used in the checkout area, in particular on the payment page and the order confirmation. The PayPal buttons can also be embedded on product pages or in the basket for express checkout.

***

## Variables

### \$wsPayPalCheckout.integrationDate

Returns the integration date of the PayPal connection.

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

### \$wsPayPalCheckout.status

Returns the status of the PayPal payment (empty if no payment process is active).

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

### \$wsPayPalCheckout.paymentCanceled

Returns `true` if the customer canceled the payment.

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

### \$wsPayPalCheckout.paymentFailed

Returns `true` if a technical error occurred during the payment.

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

### \$wsPayPalCheckout.paymentDeclined

Returns `true` if the payment was declined by PayPal or the bank.

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

### \$wsPayPalCheckout.expressCheckout

Indicates whether PayPal Express Checkout is possible ([`expressCheckoutAllow`](/en/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration) active and order value greater than 0).

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

### \$wsPayPalCheckout.expressCheckoutGooglePay

Indicates whether Google Pay Express is possible (`expressCheckoutGooglePayAllow` active and order value greater than 0).

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

### \$wsPayPalCheckout.expressCheckoutApplePay

Indicates whether Apple Pay Express is possible (`expressCheckoutApplePayAllow` active and order value greater than 0).

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

### \$wsPayPalCheckout.googlePay

Returns a map with Google Pay-specific content.

| **Property**      | **Type** | **Description**                                                                                     |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `paymentData`     | string   | Response data from Google Pay (unprocessed).                                                        |
| `transactionInfo` | map      | Map with transaction info from Google Pay (including `totalPrice`, `currencyCode`, `displayItems`). |

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

### \$wsPayPalCheckout.applePay

Returns a map with Apple Pay-specific data.

| **Property**      | **Type** | **Description**                                                                                                                                                                                 |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shippingOptions` | array    | Shipping options for the Apple Pay sheet: per entry `identifier` (shipping method ID), `label`, `detail`, `amount`. Contains only active shipping methods valid for the basket.                 |
| `billingContact`  | map      | Billing address in the Apple Pay contact format (including `givenName`, `familyName`, `addressLines`, `postalCode`, `locality`, `countryCode`). `null` if no billing address has been selected. |
| `payLineItems`    | array    | Apple Pay line items.                                                                                                                                                                           |
| `brandName`       | string   | Brand name.                                                                                                                                                                                     |
| `paymentData`     | string   | Response data from Apple Pay (unprocessed).                                                                                                                                                     |

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

### \$wsPayPalCheckout.clientMetadataId

Returns the client metadata ID for the PayPal SDK integration (e.g. for the `data-client-metadata-id` attribute when embedding the SDK script). The value corresponds to the first 32 characters of the 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>
```

***

## Methods

### \$wsPayPalCheckout.loadData()

Loads the payment data for the PayPal Checkout integration (SDK parameters, URLs, order ID). Returns `null` when no PayPal payment process is currently active — i.e. no PayPal Checkout payment method is selected or available.

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

**Return value**\
`Map` — map with payment data or `null`.

**Parameters**

| **Name**          | **Type** | **Required** | **Description**                                                                                                                                                                                                                               |
| ----------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expressCheckout` | string   | no           | Only the exact value `"express"` has an effect: the check whether a PayPal payment method is selected is skipped — required for Express Checkout, where no payment method has been selected yet at the start. The returned data is identical. |

**Example** that loads the payment data.

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

**Example** for Express Checkout (e.g. in the basket, before a payment method has been selected):

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

<Info>
  When you use the `$wsPayPalCheckout.loadData()` function, various variables become available to retrieve and output payment data. Below is an overview of the available variables.
</Info>

### Payment data (return value of `$wsPayPalCheckout.loadData()`)

First, the map with the payment data — as shown in the example above — has to be assigned to a local variable. It can then be used at various places in the template.

**JSON output of the variables**

```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": "..."
}
```

**Variables at a glance**

| **Variable**         | **Type** | **Description**                                                                                                                                                                                                            |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sandbox`            | bool     | Indicates whether sandbox mode (test mode for payment methods) is active.                                                                                                                                                  |
| `merchantId`         | string   | PayPal merchant ID of the merchant account (identical to `payerId`; corresponds to [`payment.payPalCheckout.payerId`](/en/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration)). |
| `payerId`            | string   | PayPal merchant ID of the merchant account (identical to `merchantId`). Both names are provided because the PayPal SDK expects the value under both names depending on the context.                                        |
| `clientId`           | string   | PayPal client ID.                                                                                                                                                                                                          |
| `paymentType`        | string   | Payment type (default: "`paypal`").                                                                                                                                                                                        |
| `languageCode`       | string   | Language code.                                                                                                                                                                                                             |
| `intent`             | string   | PayPal intent of the transaction (e.g. `"capture"`), for the SDK parameter `intent`.                                                                                                                                       |
| `approvalUrl`        | string   | URL for payment approval.                                                                                                                                                                                                  |
| `cancelUrl`          | string   | URL for a canceled payment.                                                                                                                                                                                                |
| `errorUrl`           | string   | URL for errors that occurred.                                                                                                                                                                                              |
| `expressApprovalUrl` | string   | URL for a successful express payment.                                                                                                                                                                                      |
| `getClientToken`     | function | Function that returns the client token for the PayPal SDK integration (`null` if no token can be determined).                                                                                                              |
| `orderId`            | string   | PayPal order ID of the current transaction.                                                                                                                                                                                |

<Warning>
  `googlePay` and `applePay` are **not** part of the `loadData()` return value. These maps are available directly on the module: [`$wsPayPalCheckout.googlePay`](#wspaypalcheckout-googlepay) and [`$wsPayPalCheckout.applePay`](#wspaypalcheckout-applepay).
</Warning>

***

## Actions

The PayPal Checkout plugin registers five actions. They are intended for the JavaScript integration of the PayPal SDK callbacks: they are invoked via POST (create the action as usual with `$wsActions.create(...)` and send `wsact`/`wscsrf` along) and — unlike classic form actions — respond directly with JSON.

| **Action**                        | **Parameter**              | **Description**                                                                                                                                                                                                                                                                                             |
| --------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UpdateGooglePayPaymentData`      | `payload` (JSON, optional) | Processes the shipping selection from the Google Pay sheet: sets the selected shipping method if applicable and returns updated `newShippingOptionParameters` and `newTransactionInfo` (in the case of an invalid shipping method also `error`).                                                            |
| `CompleteApplePayShippingContact` | `payload` (JSON)           | Processes the contact/address selection from the Apple Pay sheet and returns the updated totals and line items.                                                                                                                                                                                             |
| `CompleteApplePayShippingMethod`  | `payload` (JSON)           | Processes the shipping method selection from the Apple Pay sheet: sets the selected shipping method, updates the PayPal order amount, and returns `newTotal` and `newLineItems` (in the case of an invalid shipping method also `errors`).                                                                  |
| `CapturePaypalPayment`            | `payload` (JSON)           | Captures the authorized PayPal payment. Response: `{"capture": "..."}` with the values `success`, `pending`, or `fail`; in the case of errors, also `error`. In express checkout, the required free fields and the checkout validity are re-checked before capture, and the PayPal order amount is updated. |
| `SavePayPalPaymentData`           | `ppcpaymentdata` (Base64)  | Stores the response data from Apple Pay or Google Pay (Base64-encoded) in the session; afterwards, they are available in `googlePay.paymentData` and `applePay.paymentData`.                                                                                                                                |

<Info>
  The error texts of these actions (e.g. `requestEmpty` for an empty payload) are controlled via the configuration nodes `actions.updateApplePay` and `actions.updateGooglePay`.
</Info>

***

## Related links

* [payment.payPalCheckout - PayPal Checkout configuration](/en/konfiguration/payment-zahlungsmethoden#3-payment-paypalcheckout-paypal-checkout-konfiguration) — sets up the PayPal integration (merchant ID, mode, express checkout).
* [\$wsCheckout](/en/frontend/referenz/module/wscheckout) — the checkout into which the PayPal payment is embedded (including `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)