Как принимать оплату Telegram Stars в ботах

"Telegram Stars" или "Звёзды" являются внутренней валютой Telegram за которую можно приобретать товары или услуги, отправлять пожертвования и т.п. Сейчас мы расскажем об интеграции приема платежей в данной валюте на примере Telegram бота, написанного на Nodejs и библиотеке Telegraf.



[1] Создание платежа

Для начала сохраните платеж пользователя в базе данных. Он должен иметь следующие поля:

amountInStars: {
type: Number,
required: true,
},
telegramPaymentChargeId: {
type: String,
},
providerPaymentChargeId: {
type: String,
}

JS

amountInStars: {

    type: Number,

    required: true,

},

telegramPaymentChargeId: {

    type: String,

},

providerPaymentChargeId: {

    type: String,

}

amountInStars - сумма платежа в валюте Telegram Stars.
telegramPaymentChargeId и providerPaymentChargeId - это поля, которые пригодятся нам после того, как пользователь произведет оплату.

Для выставления платежа в валюте Stars вызовете асинхронный метод sendInvoice у контекста Telegraf.

await ctx.sendInvoice({
title: Пополнение баланса на ${amount} RUB,
description: Пополнение баланса в боте на сумму ${amount} рублей,
payload: ${payment._id},
currency: 'XTR',
prices: [{ label: 'XTR', amount: amountInTelegramStars }],
provider_token: '',
});

JS

await ctx.sendInvoice({

    title: Пополнение баланса на ${amount} RUB,

    description: Пополнение баланса в боте на сумму ${amount} рублей,

    payload: ${payment._id},

    currency: 'XTR',

    prices: [{ label: 'XTR', amount: amountInTelegramStars }],

    provider_token: '',

});

title и description - отвечают за визуальное отображение информации о платеже
payload - номер заказа в вашей системе
currency - используйте значение "XTR" для валюты Telegram Stars
prices - значения суммы платежа и валюты
provider_token - для валюты Telegram Stars в качестве значения передайте пустую строку

[2] Проверка перед оплатой платежа пользователем

Перед тем, как у пользователя будет возможность оплатить счет, Telegram отправит нам callback с информацией о нем. Вам нужно подтвердить то, что счет выставлен верно и он актуален. В ином случае, отозвать актуальность выставленного счета.

bot.on('pre_checkout_query', validateTelegramStarsPayment);

JS

bot.on('pre_checkout_query', validateTelegramStarsPayment);

Нам понадобится поле invoice_payload, содержащие номер заказа для последующей проверки.

const preCheckoutQuery = ctx.update.pre_checkout_query;
const paymentId = preCheckoutQuery.invoice_payload;
const paymentAmount = preCheckoutQuery.total_amount;

JS

const preCheckoutQuery = ctx.update.pre_checkout_query;

const paymentId = preCheckoutQuery.invoice_payload;

const paymentAmount = preCheckoutQuery.total_amount;

Мы делали следующие проверки:
1) Заказ с данным id существует
2) Заказ с данным id не оплачен на данный момент
3) paymentAmount совпадает с суммой платежа в базе данных
Если вы конвертируете рубли или другую фиатную валюту в Telegram Stars, стоит добавить проверку на то, что счет создан не позднее определенного времени. К примеру, если счет создан более 24 часов, курс мог измениться, что сделает его неактуальным. В таком случае, можно отозвать данный счет следующим образом:

await ctx.answerPreCheckoutQuery(false, 'Счет устарел');

JS

await ctx.answerPreCheckoutQuery(false, 'Счет устарел');

Если же все хорошо, одобряем оплату счета:

await ctx.answerPreCheckoutQuery(true);

JS

await ctx.answerPreCheckoutQuery(true);

[3] Зачисляем платеж

Когда Звезды списываются со счета пользователя и передаются вам, тем самым производя оплату выставленного счета, Telegram отправляет событие successful_payment.

bot.on('successful_payment', handleSuccessefulTelegramStarsPayment);

JS

bot.on('successful_payment', handleSuccessefulTelegramStarsPayment);

Нам понадобятся следующие параметры:

const {
invoice_payload: invoicePayload,
telegram_payment_charge_id: telegramPaymentChargeId,
provider_payment_charge_id: providerPaymentChargeId,
} = ctx.message.successful_payment;

JS

const {

    invoice_payload: invoicePayload,

    telegram_payment_charge_id: telegramPaymentChargeId,

    provider_payment_charge_id: providerPaymentChargeId,

} = ctx.message.successful_payment;

С invoice_payload, содержащим номер заказа в нашем базе мы уже знакомы. Новые поля telegram_payment_charge_id и provider_payment_charge_id мы также должны сохранить в нашей базе данных. Это требование Telegram. В случае спорной ситуации по платежу или chargeback'а они будут нужны.
Далее можно сделать повторную проверку на то, что счет существует, он не был оплачен и т.п. После чего следует реализация логика выдачи товара, зачисления средств на баланс или другого действия.

[4] Последний момент

После завершения реализации вышеуказанных действий, добавляем ответ бота на команду /paysupport.

bot.command('paysupport', telegramPaysupportCommand);

JS

bot.command('paysupport', telegramPaysupportCommand);

Это тоже является требованием от Telegram. Мы в ответ на эту команду просто отдаем текст с контактами поддержки бота и призывом обратиться туда в случае вопросов, касающихся платежей Telegram Stars.

Вот и всё. В реализации функционала приема платежей в валюте Telegram Stars нет сложных моментов. Больше всего умственной работы тут занимает то, как переводить фиатные валюты в Звезды. К примеру, товар стоит 100 рублей, как высчитать его стоимость в Stars? Или как выводить Stars, учитывая их hold после получения и комиссию, достигающую 30%.

От себя добавим, что не стоить спешить с переходом на прием Telegram Stars. Чувствуется, что Telegram еще есть над чем поработать. Подкупает тут то, что пользователи со всего мира могут легко покупать Звезды со своих банковских карт. В том числе и выпущенных в РФ.

Будет интересно почитать тех, кто уже давно использует прием платежей в Telegram Stars и что они думают по поводу всего этого.

P.S. Статья для питонистов - https://habr.com/ru/articles/821415/