Skip to main content

TelegramPayment

The TelegramPayment action allows you to set up payments in Telegram.

tip
If you want to make Telegram payments using JavaScript code snippets rather than action tags, use replies with the telegramPayment type in $response.replies instead.

Parameters​

ParameterTypeDescriptionCommentsRequired
providerTokenStringPayment system tokenYou need to obtain a unique token for each payment system in Telegram.Yes
startParameterBooleanAllow clients to forward payment links to other clientstrue — 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 titleUse no more than 32 characters.Yes
descriptionStringService or goods descriptionUse no more than 255 characters.Yes
imageUrlStringImage URLYou can attach your service or goods image to the invoice.No
amountStringService or goods priceTelegram sets limits for each currency on the minimum and maximum entered amount.
The amount should contain 12 digits or less.		Yes
currencyStringCurrencyThree-letter currency code according to ISO 4217. You can only specify currencies that Telegram and your payment system support.Yes
invoicePayloadStringArbitral invoice detailsThe details will not be shown in the chat. Only the payment system owner will see them.Yes
precheckoutEnabledBooleanCheck the goods availability before checkouttrue — before checkout, the bot will send requests to the service URL specified in precheckoutUrl.
If the goods are out of stock and the service returns a response with an HTTP code other than 2xx, the bot will go to errorState.
false — the bot will not check the goods availability before checkout.		No
precheckoutUrlStringURL of the service which returns information on whether the requested goods are in stock—No
okStateStringThe state the dialog will switch to if the payment is successful—No
errorStateStringThe state the dialog will switch to if the parameters are filled incorrectlyThe bot will go to this state if, for example, the specified token is invalid or the price is less than the minimum allowed amount.No
catchAllStateStringThe state the dialog will switch to if the client fails to pay and sends an arbitrary message to the bot—No
tip
Learn more about Telegram Bot Payments API

Payment system token​

To receive payments from clients, you need to obtain a unique token of the payment system and specify it in the tag parameters. 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.

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

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.

How to use​

state: TelegramPayment
    intent!: /Purchase pass
    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
        okState = /TelegramPayment/PaymentSuccessful
        errorState = /TelegramPayment/PaymentFailed
        catchAllState = /TelegramPayment/CatchAll

    state: PaymentSuccessful
        a: The payment was successful. We have sent your ticket to your email address. See you at Conversations!
        go!: /SendTickets

    state: PaymentFailed
        a: The payment failed due to a technical error. Please contact us at client@just-ai.com to buy tickets.

    state: CatchAll
        a: The payment was declined. Please check if you have entered the correct card details and try again.
        go!: /TelegramPayment

When the client switches to the TelegramPayment state, the following message will appear in the chat:

Telegram Payment