Add base Subscribtion/recurring payments support

payments/core.py

@@ -143,6 +143,27 @@ def get_return_url(
             return url + "?" + qs
         return url
 
+    def autocomplete_with_subscription(self, payment):
+        """
+        Complete the payment with subscription
+
+        If the provider uses workflow such that the payments are initiated from
+        implementer's side.
+        The users of django-payments will create a payment and call
+        Payment.autocomplete_with_subscription() right before the subscription end.
+
+        Throws RedirectNeeded if there is problem with the payment
+        that needs to be solved by user.
+        """
+        raise NotImplementedError
+
+    def cancel_subscription(self, subscription):
+        """
+        Cancel subscription
+        Used by providers, that use provider initiated cancellation workflow
+        """
+        raise NotImplementedError
+
     def capture(self, payment, amount=None):
         raise NotImplementedError
 

payments/models.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import enum
 import json
 from typing import Iterable
 from uuid import uuid4
@@ -39,6 +40,63 @@ def __setattr__(self, key, value):
         return None
 
 
+class BaseSubscription(models.Model):
+    token = models.CharField(
+        _("subscription token/id"),
+        help_text=_("Token/id used to identify subscription by provider"),
+        max_length=255,
+        default=None,
+        null=True,
+        blank=True,
+    )
+    payment_provider = models.CharField(
+        _("payment provider"),
+        help_text=_("Provider variant, that will be used for payment renewal"),
+        max_length=255,
+        default=None,
+        null=True,
+        blank=True,
+    )
+    subscribtion_data = models.JSONField(
+        _("subscription data"),
+        help_text=_("Provider-specific data associated with subscription"),
+        default=dict,
+    )
+
+    class TimeUnit(enum.Enum):
+        year = "year"
+        month = "month"
+        day = "day"
+
+    def set_recurrence(self, token: str, **kwargs):
+        """
+        Sets token and other values associated with subscription recurrence
+        Kwargs can contain provider-specific values
+        """
+        self.token = token
+        self.subscribtion_data = kwargs
+
+    def get_period(self) -> int:
+        raise NotImplementedError
+
+    def get_unit(self) -> TimeUnit:
+        raise NotImplementedError
+
+    def cancel(self):
+        """
+        Cancel the subscription by provider
+        Used by providers, that use provider initiated subscription workflow
+        Implementer is responsible for cancelling the subscription model
+
+        Raises PaymentError if the cancellation didn't pass through
+        """
+        provider = provider_factory(self.variant)
+        provider.cancel_subscription(self)
+
+    class Meta:
+        abstract = True
+
+
 class BasePayment(models.Model):
     """
     Represents a single transaction. Each instance has one or more PaymentItem.
@@ -185,6 +243,39 @@ def get_success_url(self) -> str:
     def get_process_url(self) -> str:
         return reverse("process_payment", kwargs={"token": self.token})
 
+    def get_payment_url(self) -> str:
+        """
+        Get the url the view that handles the payment
+        (payment_details() in documentation)
+        For now used only by PayU provider to redirect users back to CVV2 form
+        """
+        raise NotImplementedError
+
+    def get_subscription(self) -> BaseSubscription | None:
+        """
+        Returns subscription object associated with this payment
+        or None if the payment is not recurring
+        """
+        return None
+
+    def is_recurring(self) -> bool:
+        return self.get_subscription() is not None
+
+    def autocomplete_with_subscription(self):
+        """
+        Complete the payment with subscription
+
+        If the provider uses workflow such that the payments are initiated from
+        implementer's side.
+        Call this function right before the subscription end to
+        make a new subscription payment.
+
+        Throws RedirectNeeded if there is problem with the payment
+        that needs to be solved by user
+        """
+        provider = provider_factory(self.variant)
+        provider.autocomplete_with_subscription(self)
+
     def capture(self, amount=None):
         """Capture a pre-authorized payment.