Add refund functionality enums

discord/enums.py

@@ -114,6 +114,8 @@ __all__ = (
     'ContentRatingAgency',
     'Distributor',
     'EntitlementType',
+    'RefundReason',
+    'RefundDisqualificationReason',
     'AutoModRuleTriggerType',
     'AutoModRuleEventType',
     'AutoModRuleActionType',
@@ -1555,6 +1557,31 @@ class EntitlementType(Enum):
         return self.value
 
 
+class RefundReason(Enum):
+    other = 0
+    gifting_refund = 1
+    buyers_remorse = 2
+    wrong_purchase = 3
+    forgot_to_cancel = 4
+    premium_guild_cooldown = 5
+    user_confusion = 6
+    want_to_switch_tiers = 7
+    dont_need = 8
+
+    def __int__(self) -> int:
+        return self.value
+
+
+class RefundDisqualificationReason(Enum):
+    other = 0
+    already_refunded = 1
+    not_user_refundable_type = 2
+    past_refundable_date = 3
+    entitlement_already_consumed = 4
+    already_refunded_premium = 5
+    already_refunded_premium_guild = 6
+
+
 class AutoModRuleTriggerType(Enum):
     keyword = 1
     harmful_link = 2

discord/payments.py

@@ -31,6 +31,8 @@ from .billing import PaymentSource
 from .enums import (
     PaymentGateway,
     PaymentStatus,
+    RefundDisqualificationReason,
+    RefundReason,
     SubscriptionType,
     try_enum,
 )
@@ -117,7 +119,7 @@ class Payment(Hashable):
         The URL to download the VAT invoice for this payment, if available.
     refund_invoices_urls: List[:class:`str`]
         A list of URLs to download VAT credit notices for refunds on this payment, if available.
-    refund_disqualification_reasons: List[:class:`str`]
+    refund_disqualification_reasons: List[:class:`RefundDisqualificationReason`]
         A list of reasons why the payment cannot be refunded, if any.
     """
 
@@ -172,7 +174,9 @@ class Payment(Hashable):
         self.payment_gateway_payment_id: Optional[str] = data.get('payment_gateway_payment_id')
         self.invoice_url: Optional[str] = data.get('downloadable_invoice')
         self.refund_invoices_urls: List[str] = data.get('downloadable_refund_invoices', [])
-        self.refund_disqualification_reasons: List[str] = data.get('premium_refund_disqualification_reasons', [])
+        self.refund_disqualification_reasons: List[RefundDisqualificationReason] = [
+            try_enum(RefundDisqualificationReason, r) for r in data.get('premium_refund_disqualification_reasons', [])
+        ]
         self._flags: int = data.get('flags', 0)
 
         # The subscription object does not include the payment source ID
@@ -225,19 +229,24 @@ class Payment(Hashable):
         await self._state.http.void_payment(self.id)
         self.status = PaymentStatus.failed
 
-    async def refund(self, reason: Optional[int] = None) -> None:
+    async def refund(self, reason: RefundReason = RefundReason.other) -> None:
         """|coro|
 
-        Refund the payment.
+        Refund the payment. Refunds can only be made for payments less than 5 days old.
+
+        Parameters
+        ----------
+        reason: :class:`RefundReason`
+            The reason for the refund.
+
+            .. versionadded:: 2.1
 
         Raises
         ------
         HTTPException
             Refunding the payment failed.
         """
-        # reason here is an enum (0-8), but I was unable to find the enum values
-        # Either way, it's optional and this endpoint isn't really used anyway
-        await self._state.http.refund_payment(self.id, reason)
+        await self._state.http.refund_payment(self.id, int(reason))
         self.status = PaymentStatus.refunded
 
 

docs/api.rst

@@ -4229,6 +4229,83 @@ of :class:`enum.Enum`.
 
         The entitlement is an application subscription.
 
+.. class:: RefundReason
+
+    Represents the reason for a refund.
+
+    .. versionadded:: 2.1
+
+    .. attribute:: other
+
+        The refund is due to another reason.
+
+    .. attribute:: gifting_refund
+
+        The refund is due to an unwanted gift.
+
+    .. attribute:: buyers_remorse
+
+        The refund is due to buyer's remorse.
+
+    .. attribute:: wrong_purchase
+
+        The refund is due to a wrong purchase.
+
+    .. attribute:: forgot_to_cancel
+
+        The refund is due to forgetting to cancel a subscription.
+
+    .. attribute:: premium_guild_cooldown
+
+        The refund is due to a premium guild (boosting) cooldown.
+
+    .. attribute:: user_confusion
+
+        The refund is due to user confusion.
+
+    .. attribute:: want_to_switch_tiers
+
+        The refund is due to wanting to switch premium (Nitro) tiers.
+
+    .. attribute:: dont_need
+
+        The refund is due to not needing the purchase.
+
+.. class:: RefundDisqualificationReason
+
+    Represents the reason for a refund disqualification.
+
+    .. versionadded:: 2.1
+
+    .. attribute:: other
+
+        The purchase is disqualified from a refund due to another reason.
+
+    .. attribute:: already_refunded
+
+        The purchase is disqualified from a refund because it has already been refunded.
+
+    .. attribute:: not_user_refundable_type
+
+        The purchase is disqualified from a refund because it is not a user refundable type.
+        The user must contact Discord support to request a refund.
+
+    .. attribute:: past_refundable_date
+
+        The purchase is disqualified from a refund because it is past the refundable date.
+
+    .. attribute:: entitlement_already_consumed
+
+        The purchase is disqualified from a refund because the purchased entitlement has already been consumed.
+
+    .. attribute:: already_refunded_premium
+
+        The purchase is disqualified from a refund because the user has already refunded a premium (Nitro) purchase.
+
+    .. attribute:: already_refunded_premium_guild
+
+        The purchase is disqualified from a refund because the user has already refunded a premium guild (boosting) purchase.
+
 .. class:: SKUType
 
     Represents the type of a SKU.