Skip to main content

telegramPayment and telegramPaymentPrecheckout

The telegramPayment and telegramPaymentPrecheckout replies are used for setting up payments in Telegram for the services or goods you provide.

You can also use the built-in TelegramPayment action tag in the script. This tag does not require any additional event handling: you will only need to specify similar parameters, as well as transitions to states depending on the condition being met.


Use it for sending a payment form in the chat.


providerTokenStringPayment system token.You need to obtain a unique token for each payment system in Telegram.Yes
startParameterBooleanAllow clients to forward payment links to other clients.true — other clients can pay for the service or goods using this link.
false — other clients cannot pay for the service or goods using this link. They will be transferred to the chat with the bot.
paymentTitleStringService or goods title.Use no more than 32 characters.Yes
descriptionStringService or goods description.Use no more than 255 characters.Yes
imageUrlStringImage URL.You can attach your service or goods image to the invoice.No
amountStringService or goods price.Telegram sets limits for each currency on the minimum and maximum entered amount.
The amount should contain 12 digits or less.
currencyStringCurrency.Three-letter currency code according to ISO 4217.
You can only specify currencies that Telegram and your payment system support.
invoicePayloadStringArbitral invoice details.The details will not be shown in the chat. Only the payment system owner can use them to analyze payments.Yes

Payment system token

To receive payments from clients, you need to obtain a unique token of the payment system and specify it in the providerToken property. Create a bot in Telegram before obtaining a token. Follow the steps described in the Telegram as an inbound channel article and return to this one.


If you already have a bot in Telegram, continue reading this article.

  1. Open Telegram and enter BotFather in the search bar.
  2. Send the /mybots command to BotFather.
  3. Choose your bot and select Payments.
  4. Choose a payment system from the list.
  5. Choose one of the payment methods:
    • Test for testing the payment system.
    • Live for setting up a real payment system integration.
  6. You will be redirected to a chatbot for the selected payment system. Start the chatbot.
  7. Follow all the steps the chatbot asks for.
  8. Return to the chat with BotFather.
  9. In the last message from BotFather, you will see a list of connected payment systems and tokens for each of them. Copy the token for the selected payment system.
  10. Paste the token in the providerToken property.

Price limits

Telegram sets limits on the minimum and maximum entered amount for each currency. The minimum and maximum amount for each of the currencies roughly correspond to the limit of 1–10,000 USD. For each currency except USD, these limits depend on exchange rates and may change over time.

You can find approximate values of the minimum and maximum amount for each supported currency in the Telegram documentation.


"type": "telegramPayment",
"providerToken": $secrets.get("providerToken"),
"startParameter": true,
"paymentTitle": "Her",
"description": "Aurora Theater, December 25, 12 PM",
"imageUrl": "",
"amount": 15,
"currency": "USD",
"invoicePayload": "Kemp House 60 City Road London EC1V 2NX"


Use it for handling the telegramPrecheckoutEvent event when Telegram sends data to check the goods availability.


precheckoutIdStringThe ID sent by Telegram.Yes
successBooleanCan the payment be executed.Yes


"type": "telegramPaymentPrecheckout",
"precheckoutId": $request.query,
"success": true