$wsPayPalCheckout - PayPal - WEBSALE Dokumentation

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

{{= $wsPayPalCheckout | json }}

JSON output

{
  "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.

Integration date: {{= $wsPayPalCheckout.integrationDate }}

$wsPayPalCheckout.status

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

Status: {{= $wsPayPalCheckout.status }}

$wsPayPalCheckout.paymentCanceled

Returns true if the customer canceled the payment.

{{ if $wsPayPalCheckout.paymentCanceled }}
    // Payment was canceled
{{ /if }}

$wsPayPalCheckout.paymentFailed

Returns true if a technical error occurred during the payment.

{{ if $wsPayPalCheckout.paymentFailed }}
    // Payment failed
{{ /if }}

$wsPayPalCheckout.paymentDeclined

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

{{ if $wsPayPalCheckout.paymentDeclined }}
    // Payment was declined
{{ /if }}

$wsPayPalCheckout.expressCheckout

Indicates whether PayPal Express Checkout is possible (expressCheckoutAllow active and order value greater than 0).

{{ 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).

{{ if $wsPayPalCheckout.expressCheckoutGooglePay }}
    // Show Google Pay
{{ /if }}

$wsPayPalCheckout.expressCheckoutApplePay

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

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

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

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.

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

{{ 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):

{{ var $myPaypalDataVariable = $wsPayPalCheckout.loadData("express") }}

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.

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

{
  "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`).
`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.

googlePay and applePay are not part of the loadData() return value. These maps are available directly on the module: $wsPayPalCheckout.googlePay and $wsPayPalCheckout.applePay.

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

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

payment.payPalCheckout - PayPal Checkout configuration — sets up the PayPal integration (merchant ID, mode, express checkout).
$wsCheckout — the checkout into which the PayPal payment is embedded (including isPPCExpressCheckout, isExpressCheckoutLocked).

​Module overview

​Templates

​Variables

​$wsPayPalCheckout.integrationDate

​$wsPayPalCheckout.status

​$wsPayPalCheckout.paymentCanceled

​$wsPayPalCheckout.paymentFailed

​$wsPayPalCheckout.paymentDeclined

​$wsPayPalCheckout.expressCheckout

​$wsPayPalCheckout.expressCheckoutGooglePay

​$wsPayPalCheckout.expressCheckoutApplePay

​$wsPayPalCheckout.googlePay

​$wsPayPalCheckout.applePay

​$wsPayPalCheckout.clientMetadataId

​Methods

​$wsPayPalCheckout.loadData()

​Payment data (return value of $wsPayPalCheckout.loadData())

​Actions

​Related links

Module overview

Templates

Variables

$wsPayPalCheckout.integrationDate

$wsPayPalCheckout.status

$wsPayPalCheckout.paymentCanceled

$wsPayPalCheckout.paymentFailed

$wsPayPalCheckout.paymentDeclined

$wsPayPalCheckout.expressCheckout

$wsPayPalCheckout.expressCheckoutGooglePay

$wsPayPalCheckout.expressCheckoutApplePay

$wsPayPalCheckout.googlePay

$wsPayPalCheckout.applePay

$wsPayPalCheckout.clientMetadataId

Methods

$wsPayPalCheckout.loadData()

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

Actions

Related links