$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

{{= $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.

---

​

Related links

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