diff --git a/docs/source/inclusions/bot_methods.rst b/docs/source/inclusions/bot_methods.rst index 9dcfa1982e2..bece5296e22 100644 --- a/docs/source/inclusions/bot_methods.rst +++ b/docs/source/inclusions/bot_methods.rst @@ -369,6 +369,8 @@ - Used for getting basic info about a file * - :meth:`~telegram.Bot.get_me` - Used for getting basic information about the bot + * - :meth:`~telegram.Bot.refund_star_payment` + - Used for refunding a payment in Telegram Stars .. raw:: html diff --git a/telegram/_bot.py b/telegram/_bot.py index 604fba6aa67..6ae534f14cd 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -9011,6 +9011,47 @@ async def replace_sticker_in_set( api_kwargs=api_kwargs, ) + async def refund_star_payment( + self, + user_id: int, + telegram_payment_charge_id: str, + *, + read_timeout: ODVInput[float] = DEFAULT_NONE, + write_timeout: ODVInput[float] = DEFAULT_NONE, + connect_timeout: ODVInput[float] = DEFAULT_NONE, + pool_timeout: ODVInput[float] = DEFAULT_NONE, + api_kwargs: Optional[JSONDict] = None, + ) -> bool: + """Refunds a successful payment in `Telegram Stars `. + + .. versionadded:: NEXT.VERSION + + Args: + user_id (:obj:`int`): User identifier of the user whose payment will be refunded. + telegram_payment_charge_id (:obj:`str`): Telegram payment identifier. + + Returns: + :obj:`bool`: On success, :obj:`True` is returned. + + Raises: + :class:`telegram.error.TelegramError` + + """ + data: JSONDict = { + "user_id": user_id, + "telegram_payment_charge_id": telegram_payment_charge_id, + } + + return await self._post( + "refundStarPayment", + data, + read_timeout=read_timeout, + write_timeout=write_timeout, + connect_timeout=connect_timeout, + pool_timeout=pool_timeout, + api_kwargs=api_kwargs, + ) + def to_dict(self, recursive: bool = True) -> JSONDict: # noqa: ARG002 """See :meth:`telegram.TelegramObject.to_dict`.""" data: JSONDict = {"id": self.id, "username": self.username, "first_name": self.first_name} @@ -9261,3 +9302,5 @@ def to_dict(self, recursive: bool = True) -> JSONDict: # noqa: ARG002 """Alias for :meth:`get_business_connection`""" replaceStickerInSet = replace_sticker_in_set """Alias for :meth:`replace_sticker_in_set`""" + refundStarPayment = refund_star_payment + """Alias for :meth:`refund_star_payment`""" diff --git a/telegram/_user.py b/telegram/_user.py index c003b34d166..9224990111b 100644 --- a/telegram/_user.py +++ b/telegram/_user.py @@ -2145,3 +2145,35 @@ async def get_chat_boosts( pool_timeout=pool_timeout, api_kwargs=api_kwargs, ) + + async def refund_star_payment( + self, + telegram_payment_charge_id: str, + *, + read_timeout: ODVInput[float] = DEFAULT_NONE, + write_timeout: ODVInput[float] = DEFAULT_NONE, + connect_timeout: ODVInput[float] = DEFAULT_NONE, + pool_timeout: ODVInput[float] = DEFAULT_NONE, + api_kwargs: Optional[JSONDict] = None, + ) -> bool: + """Shortcut for:: + + await bot.refund_star_payment(user_id=update.effective_user.id, *args, **kwargs) + + For the documentation of the arguments, please see + :meth:`telegram.Bot.refund_star_payment`. + + .. versionadded:: NEXT.VERSION + + Returns: + :obj:`bool`: On success, :obj:`True` is returned. + """ + return await self.get_bot().refund_star_payment( + user_id=self.id, + telegram_payment_charge_id=telegram_payment_charge_id, + read_timeout=read_timeout, + write_timeout=write_timeout, + connect_timeout=connect_timeout, + pool_timeout=pool_timeout, + api_kwargs=api_kwargs, + ) diff --git a/telegram/ext/_extbot.py b/telegram/ext/_extbot.py index ddc6eae0581..0dbdd2eb700 100644 --- a/telegram/ext/_extbot.py +++ b/telegram/ext/_extbot.py @@ -4157,6 +4157,28 @@ async def replace_sticker_in_set( api_kwargs=self._merge_api_rl_kwargs(api_kwargs, rate_limit_args), ) + async def refund_star_payment( + self, + user_id: int, + telegram_payment_charge_id: str, + *, + read_timeout: ODVInput[float] = DEFAULT_NONE, + write_timeout: ODVInput[float] = DEFAULT_NONE, + connect_timeout: ODVInput[float] = DEFAULT_NONE, + pool_timeout: ODVInput[float] = DEFAULT_NONE, + api_kwargs: Optional[JSONDict] = None, + rate_limit_args: Optional[RLARGS] = None, + ) -> bool: + return await super().refund_star_payment( + user_id=user_id, + telegram_payment_charge_id=telegram_payment_charge_id, + read_timeout=read_timeout, + write_timeout=write_timeout, + connect_timeout=connect_timeout, + pool_timeout=pool_timeout, + api_kwargs=self._merge_api_rl_kwargs(api_kwargs, rate_limit_args), + ) + # updated camelCase aliases getMe = get_me sendMessage = send_message @@ -4278,3 +4300,4 @@ async def replace_sticker_in_set( setMessageReaction = set_message_reaction getBusinessConnection = get_business_connection replaceStickerInSet = replace_sticker_in_set + refundStarPayment = refund_star_payment diff --git a/tests/test_bot.py b/tests/test_bot.py index 415a165789b..8fa53628193 100644 --- a/tests/test_bot.py +++ b/tests/test_bot.py @@ -2210,6 +2210,17 @@ async def do_request(*args, **kwargs): obj = await bot.get_business_connection(business_connection_id=bci) assert isinstance(obj, BusinessConnection) + async def test_refund_star_payment(self, bot, monkeypatch): + # can't make actual request so we just test that the correct data is passed + async def make_assertion(url, request_data: RequestData, *args, **kwargs): + return ( + request_data.parameters.get("user_id") == 42 + and request_data.parameters.get("telegram_payment_charge_id") == "37" + ) + + monkeypatch.setattr(bot.request, "post", make_assertion) + assert await bot.refund_star_payment(42, "37") + class TestBotWithRequest: """ diff --git a/tests/test_user.py b/tests/test_user.py index d1ef521b9b2..06936532860 100644 --- a/tests/test_user.py +++ b/tests/test_user.py @@ -700,3 +700,18 @@ async def make_assertion(*_, **kwargs): monkeypatch.setattr(user.get_bot(), "forward_messages", make_assertion) assert await user.forward_messages_to(chat_id="test_forwards", message_ids=(42, 43)) + + async def test_instance_method_refund_star_payment(self, monkeypatch, user): + async def make_assertion(*_, **kwargs): + return kwargs["user_id"] == user.id and kwargs["telegram_payment_charge_id"] == 42 + + assert check_shortcut_signature( + user.refund_star_payment, Bot.refund_star_payment, ["user_id"], [] + ) + assert await check_shortcut_call( + user.refund_star_payment, user.get_bot(), "refund_star_payment" + ) + assert await check_defaults_handling(user.refund_star_payment, user.get_bot()) + + monkeypatch.setattr(user.get_bot(), "refund_star_payment", make_assertion) + assert await user.refund_star_payment(telegram_payment_charge_id=42)