diff --git a/AUTHORS.rst b/AUTHORS.rst index 1106c1e7d..74b80ac09 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -111,6 +111,7 @@ The following wonderful people contributed directly or indirectly to this projec - `Rahiel Kasim `_ - `Riko Naka `_ - `Rizlas `_ +- `Snehashish Biswas `_ - `Sahil Sharma `_ - `Sam Mosleh `_ - `Sascha `_ diff --git a/examples/paymentbot.py b/examples/paymentbot.py index a18ee6c28..90daa44ce 100644 --- a/examples/paymentbot.py +++ b/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)