Added full support of Bot API 7.7 (#1536)

* Added full support of Bot API 7.7

* Added changes description

.butcher/schema/schema.json

@@ -1,7 +1,7 @@
 {
   "api": {
-    "version": "7.6",
+    "version": "7.7",
-    "release_date": "2024-07-01"
+    "release_date": "2024-07-07"
   },
   "items": [
     {
@@ -1447,6 +1447,14 @@
               "name": "successful_payment",
               "required": false
             },
+            {
+              "type": "RefundedPayment",
+              "description": "Message is a service message about a refunded payment, information about the payment.",
+              "html_description": "<td><em>Optional</em>. Message is a service message about a refunded payment, information about the payment. <a href=\"#payments\">More about payments &#187;</a></td>",
+              "rst_description": "*Optional*. Message is a service message about a refunded payment, information about the payment. `More about payments » <https://core.telegram.org/bots/api#payments>`_\n",
+              "name": "refunded_payment",
+              "required": false
+            },
             {
               "type": "UsersShared",
               "description": "Service message: users were shared with the bot",
@@ -16278,6 +16286,56 @@
           ],
           "category": "types"
         },
+        {
+          "anchor": "refundedpayment",
+          "name": "RefundedPayment",
+          "description": "This object contains basic information about a refunded payment.",
+          "html_description": "<p>This object contains basic information about a refunded payment.</p>",
+          "rst_description": "This object contains basic information about a refunded payment.",
+          "annotations": [
+            {
+              "type": "String",
+              "description": "Three-letter ISO 4217 currency code, or 'XTR' for payments in Telegram Stars. Currently, always 'XTR'",
+              "html_description": "<td>Three-letter ISO 4217 <a href=\"/bots/payments#supported-currencies\">currency</a> code, or &#8220;XTR&#8221; for payments in <a href=\"https://t.me/BotNews/90\">Telegram Stars</a>. Currently, always &#8220;XTR&#8221;</td>",
+              "rst_description": "Three-letter ISO 4217 `currency <https://core.telegram.org/bots/payments#supported-currencies>`_ code, or 'XTR' for payments in `Telegram Stars <https://t.me/BotNews/90>`_. Currently, always 'XTR'\n",
+              "name": "currency",
+              "required": true
+            },
+            {
+              "type": "Integer",
+              "description": "Total refunded price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45, total_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).",
+              "html_description": "<td>Total refunded price in the <em>smallest units</em> of the currency (integer, <strong>not</strong> float/double). For example, for a price of <code>US$ 1.45</code>, <code>total_amount = 145</code>. See the <em>exp</em> parameter in <a href=\"/bots/payments/currencies.json\">currencies.json</a>, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).</td>",
+              "rst_description": "Total refunded price in the *smallest units* of the currency (integer, **not** float/double). For example, for a price of :code:`US$ 1.45`, :code:`total_amount = 145`. See the *exp* parameter in `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).\n",
+              "name": "total_amount",
+              "required": true
+            },
+            {
+              "type": "String",
+              "description": "Bot-specified invoice payload",
+              "html_description": "<td>Bot-specified invoice payload</td>",
+              "rst_description": "Bot-specified invoice payload\n",
+              "name": "invoice_payload",
+              "required": true
+            },
+            {
+              "type": "String",
+              "description": "Telegram payment identifier",
+              "html_description": "<td>Telegram payment identifier</td>",
+              "rst_description": "Telegram payment identifier\n",
+              "name": "telegram_payment_charge_id",
+              "required": true
+            },
+            {
+              "type": "String",
+              "description": "Provider payment identifier",
+              "html_description": "<td><em>Optional</em>. Provider payment identifier</td>",
+              "rst_description": "*Optional*. Provider payment identifier\n",
+              "name": "provider_payment_charge_id",
+              "required": false
+            }
+          ],
+          "category": "types"
+        },
         {
           "anchor": "shippingquery",
           "name": "ShippingQuery",

.butcher/types/Message/entity.json

@@ -491,6 +491,14 @@
         "name": "successful_payment",
         "required": false
       },
+      {
+        "type": "RefundedPayment",
+        "description": "Message is a service message about a refunded payment, information about the payment.",
+        "html_description": "<td><em>Optional</em>. Message is a service message about a refunded payment, information about the payment. <a href=\"#payments\">More about payments &#187;</a></td>",
+        "rst_description": "*Optional*. Message is a service message about a refunded payment, information about the payment. `More about payments » <https://core.telegram.org/bots/api#payments>`_\n",
+        "name": "refunded_payment",
+        "required": false
+      },
       {
         "type": "UsersShared",
         "description": "Service message: users were shared with the bot",

.butcher/types/RefundedPayment/entity.json

@@ -0,0 +1,57 @@
+{
+  "meta": {},
+  "group": {
+    "title": "Payments",
+    "anchor": "payments"
+  },
+  "object": {
+    "anchor": "refundedpayment",
+    "name": "RefundedPayment",
+    "description": "This object contains basic information about a refunded payment.",
+    "html_description": "<p>This object contains basic information about a refunded payment.</p>",
+    "rst_description": "This object contains basic information about a refunded payment.",
+    "annotations": [
+      {
+        "type": "String",
+        "description": "Three-letter ISO 4217 currency code, or 'XTR' for payments in Telegram Stars. Currently, always 'XTR'",
+        "html_description": "<td>Three-letter ISO 4217 <a href=\"/bots/payments#supported-currencies\">currency</a> code, or &#8220;XTR&#8221; for payments in <a href=\"https://t.me/BotNews/90\">Telegram Stars</a>. Currently, always &#8220;XTR&#8221;</td>",
+        "rst_description": "Three-letter ISO 4217 `currency <https://core.telegram.org/bots/payments#supported-currencies>`_ code, or 'XTR' for payments in `Telegram Stars <https://t.me/BotNews/90>`_. Currently, always 'XTR'\n",
+        "name": "currency",
+        "required": true
+      },
+      {
+        "type": "Integer",
+        "description": "Total refunded price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45, total_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).",
+        "html_description": "<td>Total refunded price in the <em>smallest units</em> of the currency (integer, <strong>not</strong> float/double). For example, for a price of <code>US$ 1.45</code>, <code>total_amount = 145</code>. See the <em>exp</em> parameter in <a href=\"/bots/payments/currencies.json\">currencies.json</a>, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).</td>",
+        "rst_description": "Total refunded price in the *smallest units* of the currency (integer, **not** float/double). For example, for a price of :code:`US$ 1.45`, :code:`total_amount = 145`. See the *exp* parameter in `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).\n",
+        "name": "total_amount",
+        "required": true
+      },
+      {
+        "type": "String",
+        "description": "Bot-specified invoice payload",
+        "html_description": "<td>Bot-specified invoice payload</td>",
+        "rst_description": "Bot-specified invoice payload\n",
+        "name": "invoice_payload",
+        "required": true
+      },
+      {
+        "type": "String",
+        "description": "Telegram payment identifier",
+        "html_description": "<td>Telegram payment identifier</td>",
+        "rst_description": "Telegram payment identifier\n",
+        "name": "telegram_payment_charge_id",
+        "required": true
+      },
+      {
+        "type": "String",
+        "description": "Provider payment identifier",
+        "html_description": "<td><em>Optional</em>. Provider payment identifier</td>",
+        "rst_description": "*Optional*. Provider payment identifier\n",
+        "name": "provider_payment_charge_id",
+        "required": false
+      }
+    ],
+    "category": "types"
+  }
+}

CHANGES/1536.feature.rst

@@ -0,0 +1,7 @@
+Added full support of `Bot API 7.7 <https://core.telegram.org/bots/api-changelog#july-7-2024>`_
+
+- Added the class :class:`aiogram.types.refunded_payment.RefundedPayment`,
+  containing information about a refunded payment.
+- Added the field :code:`refunded_payment` to the class
+  :class:`aiogram.types.message.Message`,
+  describing a service message about a refunded payment.

aiogram/enums/content_type.py

@@ -39,6 +39,7 @@ class ContentType(str, Enum):
     PINNED_MESSAGE = "pinned_message"
     INVOICE = "invoice"
     SUCCESSFUL_PAYMENT = "successful_payment"
+    REFUNDED_PAYMENT = "refunded_payment"
     USERS_SHARED = "users_shared"
     CHAT_SHARED = "chat_shared"
     CONNECTED_WEBSITE = "connected_website"

aiogram/types/__init__.py

@@ -187,6 +187,7 @@ from .reaction_count import ReactionCount
 from .reaction_type import ReactionType
 from .reaction_type_custom_emoji import ReactionTypeCustomEmoji
 from .reaction_type_emoji import ReactionTypeEmoji
+from .refunded_payment import RefundedPayment
 from .reply_keyboard_markup import ReplyKeyboardMarkup
 from .reply_keyboard_remove import ReplyKeyboardRemove
 from .reply_parameters import ReplyParameters
@@ -418,6 +419,7 @@ __all__ = (
     "ReactionType",
     "ReactionTypeCustomEmoji",
     "ReactionTypeEmoji",
+    "RefundedPayment",
     "ReplyKeyboardMarkup",
     "ReplyKeyboardRemove",
     "ReplyParameters",

aiogram/types/message.py

@@ -13,7 +13,6 @@ from aiogram.utils.text_decorations import (
 
 from ..client.default import Default
 from ..enums import ContentType
-from . import InputPaidMediaPhoto, InputPaidMediaVideo
 from .custom import DateTime
 from .maybe_inaccessible_message import MaybeInaccessibleMessage
 
@@ -80,6 +79,8 @@ if TYPE_CHECKING:
     from .input_media_document import InputMediaDocument
     from .input_media_photo import InputMediaPhoto
     from .input_media_video import InputMediaVideo
+    from .input_paid_media_photo import InputPaidMediaPhoto
+    from .input_paid_media_video import InputPaidMediaVideo
     from .input_poll_option import InputPollOption
     from .invoice import Invoice
     from .labeled_price import LabeledPrice
@@ -98,6 +99,7 @@ if TYPE_CHECKING:
     from .proximity_alert_triggered import ProximityAlertTriggered
     from .reaction_type_custom_emoji import ReactionTypeCustomEmoji
     from .reaction_type_emoji import ReactionTypeEmoji
+    from .refunded_payment import RefundedPayment
     from .reply_keyboard_markup import ReplyKeyboardMarkup
     from .reply_keyboard_remove import ReplyKeyboardRemove
     from .reply_parameters import ReplyParameters
@@ -249,6 +251,8 @@ class Message(MaybeInaccessibleMessage):
     """*Optional*. Message is an invoice for a `payment <https://core.telegram.org/bots/api#payments>`_, information about the invoice. `More about payments » <https://core.telegram.org/bots/api#payments>`_"""
     successful_payment: Optional[SuccessfulPayment] = None
     """*Optional*. Message is a service message about a successful payment, information about the payment. `More about payments » <https://core.telegram.org/bots/api#payments>`_"""
+    refunded_payment: Optional[RefundedPayment] = None
+    """*Optional*. Message is a service message about a refunded payment, information about the payment. `More about payments » <https://core.telegram.org/bots/api#payments>`_"""
     users_shared: Optional[UsersShared] = None
     """*Optional*. Service message: users were shared with the bot"""
     chat_shared: Optional[ChatShared] = None
@@ -407,6 +411,7 @@ class Message(MaybeInaccessibleMessage):
             pinned_message: Optional[Union[Message, InaccessibleMessage]] = None,
             invoice: Optional[Invoice] = None,
             successful_payment: Optional[SuccessfulPayment] = None,
+            refunded_payment: Optional[RefundedPayment] = None,
             users_shared: Optional[UsersShared] = None,
             chat_shared: Optional[ChatShared] = None,
             connected_website: Optional[str] = None,
@@ -505,6 +510,7 @@ class Message(MaybeInaccessibleMessage):
                 pinned_message=pinned_message,
                 invoice=invoice,
                 successful_payment=successful_payment,
+                refunded_payment=refunded_payment,
                 users_shared=users_shared,
                 chat_shared=chat_shared,
                 connected_website=connected_website,
@@ -651,6 +657,8 @@ class Message(MaybeInaccessibleMessage):
             return ContentType.CHAT_BACKGROUND_SET
         if self.boost_added:
             return ContentType.BOOST_ADDED
+        if self.refunded_payment:
+            return ContentType.REFUNDED_PAYMENT
 
         return ContentType.UNKNOWN
 

aiogram/types/refunded_payment.py

@@ -0,0 +1,49 @@
+from typing import TYPE_CHECKING, Any, Literal, Optional
+
+from .base import TelegramObject
+
+
+class RefundedPayment(TelegramObject):
+    """
+    This object contains basic information about a refunded payment.
+
+    Source: https://core.telegram.org/bots/api#refundedpayment
+    """
+
+    currency: Literal["XTR"] = "XTR"
+    """Three-letter ISO 4217 `currency <https://core.telegram.org/bots/payments#supported-currencies>`_ code, or 'XTR' for payments in `Telegram Stars <https://t.me/BotNews/90>`_. Currently, always 'XTR'"""
+    total_amount: int
+    """Total refunded price in the *smallest units* of the currency (integer, **not** float/double). For example, for a price of :code:`US$ 1.45`, :code:`total_amount = 145`. See the *exp* parameter in `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies)."""
+    invoice_payload: str
+    """Bot-specified invoice payload"""
+    telegram_payment_charge_id: str
+    """Telegram payment identifier"""
+    provider_payment_charge_id: Optional[str] = None
+    """*Optional*. Provider payment identifier"""
+
+    if TYPE_CHECKING:
+        # DO NOT EDIT MANUALLY!!!
+        # This section was auto-generated via `butcher`
+
+        def __init__(
+            __pydantic__self__,
+            *,
+            currency: Literal["XTR"] = "XTR",
+            total_amount: int,
+            invoice_payload: str,
+            telegram_payment_charge_id: str,
+            provider_payment_charge_id: Optional[str] = None,
+            **__pydantic_kwargs: Any,
+        ) -> None:
+            # DO NOT EDIT MANUALLY!!!
+            # This method was auto-generated via `butcher`
+            # Is needed only for type checking and IDE support without any additional plugins
+
+            super().__init__(
+                currency=currency,
+                total_amount=total_amount,
+                invoice_payload=invoice_payload,
+                telegram_payment_charge_id=telegram_payment_charge_id,
+                provider_payment_charge_id=provider_payment_charge_id,
+                **__pydantic_kwargs,
+            )

docs/api/types/index.rst

@@ -242,6 +242,7 @@ Payments
     labeled_price
     order_info
     pre_checkout_query
+    refunded_payment
     revenue_withdrawal_state
     revenue_withdrawal_state_failed
     revenue_withdrawal_state_pending

docs/api/types/refunded_payment.rst

@@ -0,0 +1,10 @@
+###############
+RefundedPayment
+###############
+
+
+.. automodule:: aiogram.types.refunded_payment
+    :members:
+    :member-order: bysource
+    :undoc-members: True
+    :exclude-members: model_config,model_fields

tests/test_api/test_types/test_message.py

@@ -77,6 +77,7 @@ from aiogram.types import (
     PollOption,
     ProximityAlertTriggered,
     ReactionTypeCustomEmoji,
+    RefundedPayment,
     SharedUser,
     Sticker,
     Story,
@@ -587,6 +588,18 @@ TEST_CHAT_BACKGROUND_SET = Message(
         )
     ),
 )
+TEST_REFUND_PAYMENT = Message(
+    message_id=42,
+    date=datetime.datetime.now(),
+    chat=Chat(id=42, type="private"),
+    from_user=User(id=42, is_bot=False, first_name="User"),
+    refunded_payment=RefundedPayment(
+        total_amount=42,
+        provider_payment_charge_id="payment",
+        telegram_payment_charge_id="charge",
+        invoice_payload="payload",
+    ),
+)
 TEST_MESSAGE_UNKNOWN = Message(
     message_id=42,
     date=datetime.datetime.now(),
@@ -656,6 +669,7 @@ MESSAGES_AND_CONTENT_TYPES = [
     [TEST_MESSAGE_WRITE_ACCESS_ALLOWED, ContentType.WRITE_ACCESS_ALLOWED],
     [TEST_MESSAGE_BOOST_ADDED, ContentType.BOOST_ADDED],
     [TEST_CHAT_BACKGROUND_SET, ContentType.CHAT_BACKGROUND_SET],
+    [TEST_REFUND_PAYMENT, ContentType.REFUNDED_PAYMENT],
     [TEST_MESSAGE_UNKNOWN, ContentType.UNKNOWN],
 ]
 
@@ -716,6 +730,7 @@ MESSAGES_AND_COPY_METHODS = [
     [TEST_MESSAGE_GIVEAWAY_WINNERS, None],
     [TEST_MESSAGE_BOOST_ADDED, None],
     [TEST_CHAT_BACKGROUND_SET, None],
+    [TEST_REFUND_PAYMENT, None],
     [TEST_MESSAGE_UNKNOWN, None],
 ]