Telegram Stars Payments in GramIO

Official Telegram Documentation

Telegram Stars is an in-app virtual currency that allows users to purchase digital goods and services directly in bots. This guide will show you how to implement Stars payments in your GramIO bot.

Implementation Overview

1. Create Payment Handler

bot.command("buy", async (context) => {
    const invoice = await context.bot.api.sendInvoice({
        chat_id: context.chat.id,
        title: "Premium Subscription",
        description: "1 month of premium features",
        payload: "sub_123",
        currency: "XTR",
        prices: [{ label: "1 Month", amount: 500 }], // 500 Stars = $5
    });

    return context.send("Invoice created!");
});

2. Handle Pre-Checkout Queries

bot.on("pre_checkout_query", async (context) => {
    // Validate inventory/availability here
    await context.bot.api.answerPreCheckoutQuery({
        pre_checkout_query_id: context.id,
        ok: true,
    });
});

3. Process Successful Payments

bot.on("successful_payment", async (context) => {
    await context.send("Payment received! Delivering goods...");
    // Implement your delivery logic here
});

Key Implementation Details

Creating Invoices

Pay Button

// Substrings “⭐” and “XTR” in the buttons's text will be replaced with a Telegram Star icon.
const keyboard = new InlineKeyboard().pay("XTR Buy Now");

context.send("Premium Features", {
    reply_markup: keyboard,
    // ... other message parameters
});

Link

const link = await context.bot.api.createInvoiceLink({
    title: "Premium Subscription",
    description: "1 month of premium features",
    payload: "sub_123",
    currency: "XTR",
    subscription_period: 2592000,
    prices: [{ label: "1 Month", amount: 500 }], // 500 Stars = $5
});

Inline Query Message

context.anser(
    [
        InlineQueryResult.article(
            "id-1",
            "Premium Subscription",
            InputMessageContent.invoice({
                title: "Premium Subscription",
                description: "1 month of premium features",
                payload: "sub_123",
                currency: "XTR",
                prices: [{ label: "1 Month", amount: 500 }], // 500 Stars = $5
            })
        ),
    ],
    {
        cache_time: 0,
    }
);

Testing Payments

Enable test mode in GramIO configuration:

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        useTest: true, // Use Telegram's test environment
    },
});

Handling Disputes

Implement refund logic using GramIO's API:

bot.command("refund", async (context) => {
    const result = await context.api.refundStarPayment({
        user_id: context.from.id,
        telegram_payment_charge_id: paymentId,
    });
});

Always check current rates in Telegram's official documentation

Learn more about monetization