feat: Implement PayPal checkout (#165)

* Implement payment provider `PayPalCheckout`
* Add PayPal SDK as `paypal` extra
* Generalize some methods in `PaymentProviderAbstract`

Author: sveneberth

pyproject.toml

@@ -42,6 +42,9 @@ version = { attr = "viur.shop.version.__version__" }
 unzer = [
     "unzer~=1.3",
 ]
+paypal = [
+    "paypal-server-sdk~=1.0",
+]
 
 [tool.setuptools.packages.find]
 where = ["src"]

src/viur/shop/data/translations.py

@@ -105,6 +105,10 @@
         "_default_text": "Payment in advance",
         "de": "Bezahlen über Vorkasse",
     },
+    "viur.shop.payment_provider.paypal_checkout": {
+        "_default_text": "PayPal",
+        "de": "Bezahlen über PayPal",
+    },
 
     # --- Enums ---------------------------------------------------------------
     # Availability

src/viur/shop/globals.py

@@ -1,3 +1,7 @@
+"""
+Global constants and settings for the viur-shop.
+"""
+
 import logging
 import typing as t
 

src/viur/shop/payment_providers/__init__.py

@@ -1,7 +1,6 @@
 from .abstract import PaymentProviderAbstract
 from .amazon_pay import AmazonPay
 from .invoice import Invoice
-from .paypal_plus import PayPalPlus
 from .prepayment import PrePayment, Prepayment
 
 try:
@@ -20,3 +19,12 @@
     from .unzer_paylater_invoice import UnzerPaylaterInvoice
     from .unzer_paypal import UnzerPayPal
     from .unzer_sofort import UnzerSofort
+
+try:
+    import paypalserversdk
+except ImportError:
+    # The paypal extra was not enabled, we don't import the related providers
+    ...
+else:
+    del paypalserversdk
+    from .paypal_checkout import PayPalCheckout

src/viur/shop/payment_providers/abstract.py

@@ -1,11 +1,13 @@
 import abc
+import enum
 import functools
 import uuid
 
-from viur import toolkit
-from viur.core import Module, translate, utils
+from viur.core import CallDeferred, Module, current, db, translate, utils
 from viur.core.prototypes.instanced_module import InstancedModule
 from viur.core.skeleton import SkeletonInstance
+
+from viur import toolkit
 from viur.shop.skeletons.order import OrderSkel
 from ..types import *
 
@@ -58,10 +60,14 @@ def description(self) -> translate:
         """Define the description of the payment provider"""
         return translate(f"viur.shop.payment_provider.{self.name}.descr", self.name)
 
+    # --- Internal Checks & Actions during the payment flow -------------------
+    # --- (controlled by the order module) ------------------------------------
+
     def is_available(
         self: t.Self,
         order_skel: SkeletonInstance_T[OrderSkel] | None,
     ) -> bool:
+        """Decide whether the payment provider is available."""
         return True
 
     def can_checkout(
@@ -113,25 +119,52 @@ def check_payment_state(
         """
         ...
 
+    @CallDeferred
+    # @log_unzer_error
+    def check_payment_deferred(self, order_key: db.Key) -> None:
+        """Check the status for a payment deferred"""
+        logger.debug(f"Checking payment for {order_key=!r} deferred")
+        order_skel = self.shop.order.skel().read(order_key)
+        logger.debug(f"Checking payment for {order_skel=!r} deferred")
+        # TODO: duplicate check / code?
+        is_paid, payment = self.check_payment_state(order_skel)
+        if is_paid and order_skel["is_paid"]:
+            logger.info(f'Order {order_skel["key"]!r} already marked as paid. Nothing to do.')
+        elif is_paid:
+            logger.info(f'Mark order {order_skel["key"]!r} as paid')
+            self.shop.order.set_paid(order_skel)
+        else:
+            logger.info(f'Order {order_skel["key"]!r} is not paid')
+
+    # --- API Endpoints  ------------------------------------------------------
+
     @abc.abstractmethod
     # @exposed
     def return_handler(self):
+        """Frontend Endpoint where the might be redirected to by the payment provider during the payment flow"""
         ...
 
     @abc.abstractmethod
     # @exposed
     def webhook(self):
+        """API Endpoint (Webhook) to listen for events from payment provider"""
         ...
 
     @abc.abstractmethod
     # @exposed
     def get_debug_information(self):
+        """Provide information about the payment of an order.
+
+        Only for debugging purposes. It's not an API endpoint.
+        """
         ...
 
+    # --- utils ---------------------------------------------------------------
+
     def _append_payment_to_order_skel(
         self,
         order_skel: SkeletonInstance_T[OrderSkel],
-        payment: dict[str, t.Any] | None = None,
+        payment: PaymentTransactionSpecific | None = None,
     ) -> SkeletonInstance_T[OrderSkel]:
         """Append payment data to an order
 
@@ -147,8 +180,10 @@ def set_payment(skel: SkeletonInstance):
                     "payment_provider": self.name,
                     "creationdate": utils.utcNow().isoformat(),
                     "uuid": str(uuid.uuid4()),
+                    "client_ip": current.request.get().request.client_addr,
+                    "user_agent": current.request.get().request.user_agent,
                 }
-                | (payment or {})
+                | (payment or {})  # type: PaymentTransaction
             )
 
         order_skel = toolkit.set_status(
@@ -162,7 +197,7 @@ def serialize_for_api(
         self,
         order_skel: SkeletonInstance_T[OrderSkel] | None,
     ) -> PaymentProviderResult:
-        """Serialize this Payment Provder for the API
+        """Serialize this Payment Provider for the API
 
         Used by :meth:`Order.get_payment_providers` and :meth:`Order.payment_providers_list`
         Can be subclasses to expose more information via API.
@@ -174,5 +209,17 @@ def serialize_for_api(
             is_available=self.is_available(order_skel),
         )
 
+    @classmethod
+    def model_to_dict(cls, obj: t.Any) -> t.Any:
+        """Convert any nested model to a JSON-compatible representation
+        """
+        if isinstance(obj, dict):
+            return {k: cls.model_to_dict(v) for k, v in obj.items()}
+        elif isinstance(obj, list | tuple):
+            return [cls.model_to_dict(v) for v in obj]
+        elif isinstance(obj, enum.Enum):
+            return f"{obj!r}"
+        return obj
+
 
 PaymentProviderAbstract.html = True

src/viur/shop/payment_providers/invoice.py

@@ -2,6 +2,7 @@
 
 from viur.core import errors, exposed
 from viur.core.skeleton import SkeletonInstance
+
 from . import PaymentProviderAbstract
 from ..globals import SHOP_LOGGER
 from ..skeletons import OrderSkel