Overhaul Help Texts in Payments Example (#4565)

AUTHORS.rst

@@ -111,6 +111,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Riko Naka <https://github.com/rikonaka>`_
 - `Rizlas <https://github.com/rizlas>`_
+- `Snehashish Biswas <https://github.com/Snehashish06>`_
 - `Sahil Sharma <https://github.com/sahilsharma811>`_
 - `Sam Mosleh <https://github.com/sam-mosleh>`_
 - `Sascha <https://github.com/saschalalala>`_

examples/paymentbot.py

@@ -2,7 +2,7 @@
 # pylint: disable=unused-argument
 # This program is dedicated to the public domain under the CC0 license.
 
-"""Basic example for a bot that can receive payment from user."""
+"""Basic example for a bot that can receive payments from users."""
 
 import logging
 
@@ -26,36 +26,36 @@ logging.getLogger("httpx").setLevel(logging.WARNING)
 
 logger = logging.getLogger(__name__)
 
+# Insert the token from your payment provider.
+# In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
 PAYMENT_PROVIDER_TOKEN = "PAYMENT_PROVIDER_TOKEN"
 
 
 async def start_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Displays info on how to use the bot."""
+    """Provides instructions on how to use the bot."""
     msg = (
-        "Use /shipping to get an invoice for shipping-payment, or /noshipping for an "
+        "Use /shipping to receive an invoice with shipping included, or /noshipping for an "
         "invoice without shipping."
     )
-
     await update.message.reply_text(msg)
 
 
 async def start_with_shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Sends an invoice with shipping-payment."""
+    """Sends an invoice which triggers a shipping query."""
     chat_id = update.message.chat_id
     title = "Payment Example"
-    description = "Payment Example using python-telegram-bot"
-    # select a payload just for you to recognize its the donation from your bot
+    description = "Example of a payment process using the python-telegram-bot library."
+    # Unique payload to identify this payment request as being from your bot
     payload = "Custom-Payload"
-    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
+    # Set up the currency.
+    # List of supported currencies: https://core.telegram.org/bots/payments#supported-currencies
     currency = "USD"
-    # price in dollars
+    # Price in dollars
     price = 1
-    # price * 100 so as to include 2 decimal points
-    # check https://core.telegram.org/bots/payments#supported-currencies for more details
+    # Convert price to cents from dollars.
     prices = [LabeledPrice("Test", price * 100)]
-
-    # optionally pass need_name=True, need_phone_number=True,
-    # need_email=True, need_shipping_address=True, is_flexible=True
+    # Optional parameters like need_shipping_address and is_flexible trigger extra user prompts
+    # https://docs.python-telegram-bot.org/en/stable/telegram.bot.html#telegram.Bot.send_invoice
     await context.bot.send_invoice(
         chat_id,
         title,
@@ -75,17 +75,16 @@ async def start_with_shipping_callback(update: Update, context: ContextTypes.DEF
 async def start_without_shipping_callback(
     update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
-    """Sends an invoice without shipping-payment."""
+    """Sends an invoice without requiring shipping details."""
     chat_id = update.message.chat_id
     title = "Payment Example"
-    description = "Payment Example using python-telegram-bot"
-    # select a payload just for you to recognize its the donation from your bot
+    description = "Example of a payment process using the python-telegram-bot library."
+    # Unique payload to identify this payment request as being from your bot
     payload = "Custom-Payload"
-    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
     currency = "USD"
-    # price in dollars
+    # Price in dollars
     price = 1
-    # price * 100 so as to include 2 decimal points
+    # Convert price to cents from dollars.
     prices = [LabeledPrice("Test", price * 100)]
 
     # optionally pass need_name=True, need_phone_number=True,
@@ -96,65 +95,65 @@ async def start_without_shipping_callback(
 
 
 async def shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Answers the ShippingQuery with ShippingOptions"""
+    """Handles the ShippingQuery with available shipping options."""
     query = update.shipping_query
-    # check the payload, is this from your bot?
+    # Verify if the payload matches, ensure it's from your bot
     if query.invoice_payload != "Custom-Payload":
-        # answer False pre_checkout_query
+        # If not, respond with an error
         await query.answer(ok=False, error_message="Something went wrong...")
         return
 
-    # First option has a single LabeledPrice
+    # Define available shipping options
+    # First option with a single price entry
     options = [ShippingOption("1", "Shipping Option A", [LabeledPrice("A", 100)])]
-    # second option has an array of LabeledPrice objects
+    # Second option with multiple price entries
     price_list = [LabeledPrice("B1", 150), LabeledPrice("B2", 200)]
     options.append(ShippingOption("2", "Shipping Option B", price_list))
     await query.answer(ok=True, shipping_options=options)
 
 
-# after (optional) shipping, it's the pre-checkout
+# After (optional) shipping, process the pre-checkout step
 async def precheckout_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Answers the PreQecheckoutQuery"""
+    """Responds to the PreCheckoutQuery as the final confirmation for checkout."""
     query = update.pre_checkout_query
-    # check the payload, is this from your bot?
+    # Verify if the payload matches, ensure it's from your bot
     if query.invoice_payload != "Custom-Payload":
-        # answer False pre_checkout_query
+        # If not, respond with an error
         await query.answer(ok=False, error_message="Something went wrong...")
     else:
         await query.answer(ok=True)
 
 
-# finally, after contacting the payment provider...
+# Final callback after successful payment
 async def successful_payment_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Confirms the successful payment."""
-    # do something after successfully receiving payment?
-    await update.message.reply_text("Thank you for your payment!")
+    """Acknowledges successful payment and thanks the user."""
+    await update.message.reply_text("Thank you for your payment.")
 
 
 def main() -> None:
-    """Run the bot."""
+    """Starts the bot and sets up handlers."""
     # Create the Application and pass it your bot's token.
     application = Application.builder().token("TOKEN").build()
 
-    # simple start function
+    # Start command to display usage instructions
     application.add_handler(CommandHandler("start", start_callback))
 
-    # Add command handler to start the payment invoice
+    # Command handlers for starting the payment process
     application.add_handler(CommandHandler("shipping", start_with_shipping_callback))
     application.add_handler(CommandHandler("noshipping", start_without_shipping_callback))
 
-    # Optional handler if your product requires shipping
+    # Handler for shipping query (if product requires shipping)
     application.add_handler(ShippingQueryHandler(shipping_callback))
 
-    # Pre-checkout handler to final check
+    # Pre-checkout handler for verifying payment details.
     application.add_handler(PreCheckoutQueryHandler(precheckout_callback))
 
-    # Success! Notify your user!
+    # Handler for successful payment. Notify the user that the payment was successful.
     application.add_handler(
         MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment_callback)
     )
 
-    # Run the bot until the user presses Ctrl-C
+    # Start polling for updates until interrupted (CTRL+C)
     application.run_polling(allowed_updates=Update.ALL_TYPES)