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

Property	Type	Description	Note	Required
providerToken	String	Payment system token.	You need to obtain a unique token for each payment system in Telegram.	Yes
startParameter	Boolean	Allow 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
paymentTitle	String	Service or goods title.	Use no more than 32 characters.	Yes
description	String	Service or goods description.	Use no more than 255 characters.	Yes
imageUrl	String	Image URL.	You can attach your service or goods image to the invoice.	No
amount	String	Service 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
currency	String	Currency.	Three-letter currency code according to ISO 4217. You can only specify currencies that Telegram and your payment system support.	Yes
invoicePayload	String	Arbitral 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": "Bolshaya Zelenina str. 24, lit. A, 197110, Russian Federation"
}

tip

Learn more about how to use telegramPayment in the script

telegramPaymentPrecheckout

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

Properties

Property	Type	Description	Required
precheckoutId	String	The ID sent by Telegram.	Yes
success	Boolean	Can the payment be executed.	Yes

Syntax

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

tip

Learn more about how to use telegramPaymentPrecheckout in the script