Skip to main content

Payments in Telegram

You can accept payments from Telegram users for services or goods you provide. There are two ways to set up payments in the Tovie Platform script:

  1. Using the TelegramPayment action tag.
  2. Using the telegramPayment reply type via the $response object.

A action tag is a ready-made solution that you can easily use in the script only by specifying the necessary parameters. Using the bot reply via $response is suitable for scripts in which you need to configure the goods availability check more flexibly.

This article demonstrates how to set up payments using the reply via $response. You can learn more about using the action tag in the TelegramPayment article.

How to use​

Consider the following example. You want the bot to send a payment form for a ticket to a user.

To do this, you need to:

  1. Create a bot in Telegram.
  2. Connect a payment system and obtain its unique token.
  3. Use the telegramPayment reply in the script.
tip
Learn more about the telegramPayment format
state: TelegramPayment
    intent!: /Payment
    script:
        $response.replies = $response.replies || [];
        $response.replies.push({
            "type": "telegramPayment",
            "providerToken": $injector.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"
        });

Goods availability​

Before proceeding with the payment, Telegram sends a request to Tovie Platform to check the goods availability. In the script, this request triggers telegramPrecheckoutEvent. Add the Precheckout and PaymentFailed nested states in the TelegramPayment state.

tip
Use the telegramPaymentPrecheckout reply type to set the check status.

To check the goods availability, the bot will send requests to the service URL specified in the precheckoutUrl variable. 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 the PaymentFailed state. This state will handle errors, its implementation will be described later.

state: Precheckout
    event: telegramPrecheckoutEvent
    script:
        // The service URL for checking the goods availability.
        var precheckoutUrl = "https://www.example.com/";

        $response.replies = $response.replies || [];
        var telegramPrecheckoutReply = {
            type: "telegramPaymentPrecheckout",
            precheckoutId: $request.query,
            success: true
        };
        try {
            var response = $http.query(precheckoutUrl);
            if (!response.isOk) {
                telegramPrecheckoutReply.success = false;
                $reactions.transition("/TelegramPayment/PaymentFailed");
            }
        } catch (e) {
            telegramPrecheckoutReply.success = false;
            $reactions.transition("/TelegramPayment/PaymentFailed");
        }
        $response.replies.push(telegramPrecheckoutReply);

state: PaymentFailed
    event: telegramPaymentFailedEvent
    a: The payment failed due to a technical error. Please contact us at bd@tovie.ai to buy tickets.
caution
Note
You always need to handle the telegramPrecheckoutEvent event in the script. Otherwise payments will fail, and all subsequent user messages will be handled in the CatchAll state.

If you don’t need to check the goods availability before checkout, use the following script:

state: Precheckout
    event: telegramPrecheckoutEvent
    script:
        $response.replies = $response.replies || [];
        $response.replies.push({
            "type": "telegramPaymentPrecheckout",
            "precheckoutId": $request.query,
            "success": true
        });

In this case, the event is always handled successfully, and the goods are always considered in stock.

Payment status​

The following events are provided for handling payment statuses:

  • telegramPaymentSuccessEvent — the payment was successful.
  • telegramPaymentFailedEvent — an error occurred because the goods are out of stock or the reply parameters are filled incorrectly: for example, the specified token is invalid or the price is less than the minimum allowed amount.
  • noMatch — the user failed to pay and sent an arbitrary message to the bot.

Create the PaymentSuccessful and CatchAll nested states for telegramPaymentSuccessEvent and noMatch. For handling telegramPaymentFailedEvent, use the PaymentFailed state written previously.

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

state: CatchAll
    event: noMatch
    a: The payment was declined. Please check if you have entered the correct card details and try again.
    go!: /TelegramPayment
The whole script example
state: TelegramPayment
    intent!: /Payment
    script:
        $response.replies = $response.replies || [];
        $response.replies.push({
            "type": "telegramPayment",
            "providerToken": $injector.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"
        });

    state: Precheckout
        event: telegramPrecheckoutEvent
        script:
            // The service URL for checking the goods availability.
            var precheckoutUrl = "https://www.example.com/";

            $response.replies = $response.replies || [];
            var telegramPrecheckoutReply = {
                type: "telegramPaymentPrecheckout",
                precheckoutId: $request.query,
                success: true
            };
            try {
                var response = $http.query(precheckoutUrl);
                if (!response.isOk) {
                    telegramPrecheckoutReply.success = false;
                    $reactions.transition("/TelegramPayment/PaymentFailed");
                }
            } catch (e) {
                telegramPrecheckoutReply.success = false;
                $reactions.transition("/TelegramPayment/PaymentFailed");
            }
            $response.replies.push(telegramPrecheckoutReply);

    state: PaymentFailed
        event: telegramPaymentFailedEvent
        a: The payment failed due to a technical error. Please contact us at bd@tovie.ai to buy tickets.

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

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