feat: add payment-related classes and methods for bank card data and receipts

Author: SychO3

pyrogram/methods/payments/__init__.py

@@ -20,13 +20,15 @@
 from .apply_gift_code import ApplyGiftCode
 from .buy_gift_upgrade import BuyGiftUpgrade
 from .check_gift_code import CheckGiftCode
+from .clear_saved_payment_info import ClearSavedPaymentInfo
 from .convert_gift_to_stars import ConvertGiftToStars
 from .craft_gift import CraftGift
 from .create_gift_collection import CreateGiftCollection
 from .delete_gift_collection import DeleteGiftCollection
 from .drop_gift_original_details import DropGiftOriginalDetails
 from .edit_star_subscription import EditStarSubscription
 from .get_available_gifts import GetAvailableGifts
+from .get_bank_card_data import GetBankCardData
 from .get_chat_gifts import GetChatGifts
 from .get_gift_auction_state import GetGiftAuctionState
 from .get_chat_gifts_count import GetChatGiftsCount
@@ -35,6 +37,8 @@
 from .get_gift_upgrade_variants import GetGiftUpgradeVariants
 from .get_gifts_for_crafting import GetGiftsForCrafting
 from .get_payment_form import GetPaymentForm
+from .get_payment_receipt import GetPaymentReceipt
+from .get_saved_payment_info import GetSavedPaymentInfo
 from .get_stars_balance import GetStarsBalance
 from .get_ton_balance import GetTonBalance
 from .get_upgraded_gift import GetUpgradedGift
@@ -60,20 +64,23 @@
 from .suggest_birthday import SuggestBirthday
 from .transfer_gift import TransferGift
 from .upgrade_gift import UpgradeGift
+from .validate_requested_info import ValidateRequestedInfo
 
 
 class Payments(
     AddCollectionGifts,
     ApplyGiftCode,
     BuyGiftUpgrade,
     CheckGiftCode,
+    ClearSavedPaymentInfo,
     ConvertGiftToStars,
     CraftGift,
     CreateGiftCollection,
     DeleteGiftCollection,
     DropGiftOriginalDetails,
     EditStarSubscription,
     GetAvailableGifts,
+    GetBankCardData,
     GetChatGifts,
     GetGiftAuctionState,
     GetChatGiftsCount,
@@ -82,6 +89,8 @@ class Payments(
     GetGiftUpgradeVariants,
     GetGiftsForCrafting,
     GetPaymentForm,
+    GetPaymentReceipt,
+    GetSavedPaymentInfo,
     GetStarsBalance,
     GetTonBalance,
     GetUpgradedGift,
@@ -106,6 +115,7 @@ class Payments(
     ShowGift,
     SuggestBirthday,
     TransferGift,
-    UpgradeGift
+    UpgradeGift,
+    ValidateRequestedInfo
 ):
     pass

pyrogram/methods/payments/clear_saved_payment_info.py

@@ -0,0 +1,64 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Optional
+
+import pyrogram
+from pyrogram import raw
+
+
+class ClearSavedPaymentInfo:
+    async def clear_saved_payment_info(
+        self: "pyrogram.Client",
+        credentials: Optional[bool] = None,
+        info: Optional[bool] = None
+    ) -> bool:
+        """Clear saved payment information.
+
+        .. include:: /_includes/usable-by/users.rst
+
+        Parameters:
+            credentials (``bool``, *optional*):
+                Pass True to remove saved payment credentials.
+
+            info (``bool``, *optional*):
+                Pass True to remove saved order information.
+
+        Returns:
+            ``bool``: True on success.
+
+        Example:
+            .. code-block:: python
+
+                # Clear both credentials and info
+                await app.clear_saved_payment_info(
+                    credentials=True,
+                    info=True
+                )
+
+                # Clear only saved credentials
+                await app.clear_saved_payment_info(credentials=True)
+        """
+        r = await self.invoke(
+            raw.functions.payments.ClearSavedInfo(
+                credentials=credentials,
+                info=info
+            )
+        )
+
+        return bool(r)

pyrogram/methods/payments/get_bank_card_data.py

@@ -0,0 +1,54 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+import pyrogram
+from pyrogram import raw, types
+
+
+class GetBankCardData:
+    async def get_bank_card_data(
+        self: "pyrogram.Client",
+        number: str
+    ) -> "types.BankCardData":
+        """Get information about a bank card by its number.
+
+        .. include:: /_includes/usable-by/users.rst
+
+        Parameters:
+            number (``str``):
+                The bank card number.
+
+        Returns:
+            :obj:`~pyrogram.types.BankCardData`: On success, the bank card data is returned.
+
+        Example:
+            .. code-block:: python
+
+                data = await app.get_bank_card_data("1234567890123456")
+
+                print(data.title)
+                for link in data.open_urls:
+                    print(link.name, link.url)
+        """
+        r = await self.invoke(
+            raw.functions.payments.GetBankCardData(
+                number=number
+            )
+        )
+
+        return types.BankCardData._parse(r)

pyrogram/methods/payments/get_payment_receipt.py

@@ -0,0 +1,62 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Union
+
+import pyrogram
+from pyrogram import raw, types
+
+
+class GetPaymentReceipt:
+    async def get_payment_receipt(
+        self: "pyrogram.Client",
+        chat_id: Union[int, str],
+        message_id: int
+    ) -> "types.PaymentReceipt":
+        """Get a payment receipt.
+
+        .. include:: /_includes/usable-by/users.rst
+
+        Parameters:
+            chat_id (``int`` | ``str``):
+                Unique identifier (int) or username (str) of the target chat.
+
+            message_id (``int``):
+                Identifier of the message with the successful payment service message.
+
+        Returns:
+            :obj:`~pyrogram.types.PaymentReceipt`: On success, the payment receipt is returned.
+
+        Example:
+            .. code-block:: python
+
+                receipt = await app.get_payment_receipt(
+                    chat_id=chat_id,
+                    message_id=123
+                )
+
+                print(receipt.total_amount, receipt.currency)
+        """
+        r = await self.invoke(
+            raw.functions.payments.GetPaymentReceipt(
+                peer=await self.resolve_peer(chat_id),
+                msg_id=message_id
+            )
+        )
+
+        return types.PaymentReceipt._parse(self, r)

pyrogram/methods/payments/get_saved_payment_info.py

@@ -0,0 +1,49 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+import pyrogram
+from pyrogram import raw, types
+
+
+class GetSavedPaymentInfo:
+    async def get_saved_payment_info(
+        self: "pyrogram.Client",
+    ) -> "types.SavedPaymentInfo":
+        """Get saved payment information.
+
+        .. include:: /_includes/usable-by/users.rst
+
+        Returns:
+            :obj:`~pyrogram.types.SavedPaymentInfo`: On success, the saved payment info is returned.
+
+        Example:
+            .. code-block:: python
+
+                info = await app.get_saved_payment_info()
+
+                if info.has_saved_credentials:
+                    print("Has saved credentials")
+
+                if info.order_info:
+                    print(info.order_info.name)
+        """
+        r = await self.invoke(
+            raw.functions.payments.GetSavedInfo()
+        )
+
+        return types.SavedPaymentInfo._parse(r)

pyrogram/methods/payments/send_payment_form.py

@@ -16,6 +16,8 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
+from typing import Optional
+
 import pyrogram
 from pyrogram import raw, types
 
@@ -25,7 +27,10 @@ async def send_payment_form(
         self: "pyrogram.Client",
         payment_form_id: int,
         input_invoice: "types.InputInvoice",
-        credentials: "types.InputCredentials" = None
+        credentials: "types.InputCredentials" = None,
+        requested_info_id: Optional[str] = None,
+        shipping_option_id: Optional[str] = None,
+        tip_amount: Optional[int] = None
     ) -> "types.PaymentResult":
         """Send a filled-out payment form to the bot for final verification.
 
@@ -42,6 +47,16 @@ async def send_payment_form(
                 The credentials chosen by user for payment.
                 Pass None for a payment in Telegram Stars.
 
+            requested_info_id (``str``, *optional*):
+                Identifier of a saved order info, returned by
+                :meth:`~pyrogram.Client.validate_requested_info`.
+
+            shipping_option_id (``str``, *optional*):
+                Identifier of the chosen shipping option.
+
+            tip_amount (``int``, *optional*):
+                The amount of tip in the smallest units of the currency.
+
         Returns:
             :obj:`~pyrogram.types.PaymentResult`: On success, the payment result is returned.
 
@@ -60,7 +75,7 @@ async def send_payment_form(
                     payment_form_id=form.id,
                     input_invoice=invoice,
                     credentials=types.InputCredentialsNew(
-                        data=json.dumps({"token": "...", "type": "card"}), # Pass the token received from the payment provider
+                        data=json.dumps({"token": "...", "type": "card"}),
                     )
                 )
 
@@ -89,7 +104,10 @@ async def send_payment_form(
                 raw.functions.payments.SendPaymentForm(
                     form_id=payment_form_id,
                     invoice=await input_invoice.write(self),
-                    credentials=await credentials.write(self)
+                    credentials=await credentials.write(self),
+                    requested_info_id=requested_info_id,
+                    shipping_option_id=shipping_option_id,
+                    tip_amount=tip_amount
                 )
             )