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.

tip
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.

telegramPayment

Use it for sending a payment form in the chat.

Properties

PropertyTypeDescriptionNoteRequired
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.
Yes
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.
Yes
currencyStringCurrency.Three-letter currency code according to ISO 4217.
You can only specify currencies that Telegram and your payment system support.
Yes
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.

note

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.

Syntax

{
"type": "telegramPayment",
"providerToken": $secrets.get("providerToken"),
"startParameter": true,
"paymentTitle": "Her",
"description": "Aurora Theater, December 25, 12 PM",
"imageUrl": "https://upload.wikimedia.org/wikipedia/en/4/44/Her2013Poster.jpg",
"amount": 15,
"currency": "USD",
"invoicePayload": "Kemp House 60 City Road London EC1V 2NX"
}

telegramPaymentPrecheckout

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

Properties

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

Syntax

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