پرداخت و استارز
مرداد ۱۴۰۵
راهنمای جامع پیادهسازی پرداخت با استارز تلگرام (Telegram Stars)
استارز تلگرام (Telegram Stars) سیستم پرداخت رسمی و درونبرنامهای تلگرام است که به توسعهدهندگان و کسبوکارها اجازه میدهد محصولات دیجیتال، خدمات و اشتراکهای ویژه را بدون خروج کاربر از محیط تلگرام و با رعایت قوانین اپاستور و گوگلپلی به فروش برسانند.
۱. ایجاد لینک فاکتور پرداخت با متد createInvoiceLink
برای ایجاد فاکتور تلگرام استارز، متد createInvoiceLink را در Bot API با واحد پول XTR فراخوانی کنید:
async function generateStarsInvoice(botToken, { title, description, payload, starsAmount }) {
const url = `https://api.telegram.org/bot${botToken}/createInvoiceLink`;
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
title: title,
description: description,
payload: JSON.stringify(payload),
currency: 'XTR',
prices: [{ label: title, amount: starsAmount }]
})
});
const data = await response.json();
if (!data.ok) throw new Error(data.description);
return data.result;
}
۲. باز کردن پنجره پرداخت در مینیاپ تلگرام
در فرانتاند مینیاپ، متد openInvoice از تلگرام SDK به کاربر اجازه میدهد بدون ترک صفحه فاکتور را پرداخت کند:
function buyWithStars(invoiceLink) {
if (window.Telegram?.WebApp) {
window.Telegram.WebApp.openInvoice(invoiceLink, (status) => {
if (status === 'paid') {
window.showToast('پرداخت موفقیتآمیز بود!', 'success');
} else if (status === 'cancelled') {
console.log('کاربر پرداخت را لغو کرد.');
}
});
}
}
۳. اعتبارسنجی وبهوکهای pre_checkout_query و successful_payment
پاسخ به pre_checkout_query باید در کمتر از ۱۰ ثانیه ارسال شود تا تلگرام مجوز کسر استارز از حساب کاربر را تایید نماید.
export default {
async fetch(request, env) {
const update = await request.json();
if (update.pre_checkout_query) {
await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/answerPreCheckoutQuery`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
pre_checkout_query_id: update.pre_checkout_query.id,
ok: true
})
});
return new Response('OK');
}
if (update.message?.successful_payment) {
const payment = update.message.successful_payment;
await fulfillOrder(JSON.parse(payment.invoice_payload));
}
return new Response('OK');
}
};