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.

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