Process Telegram Stars Payments in PHP: Invoices, Pre-Checkout, and Webhooks

<?php
// send_invoice.php

$botToken = getenv('TELEGRAM_BOT_TOKEN');
if (!$botToken) {
    die("TELEGRAM_BOT_TOKEN environment variable is not set.\n");
}

// Generate a unique payload for tracking
$orderId = bin2hex(random_bytes(8)); 
$payload = json_encode([
    'order_id' => $orderId,
    'user_id' => 123456789,
    'item_sku' => 'premium_status_30d'
]);

$parameters = [
    'chat_id' => 123456789, // The recipient's Telegram user ID
    'title' => '30 Days Premium Access',
    'description' => 'Unlock premium features in our Telegram Mini App.',
    'payload' => $payload,
    'provider_token' => '', // Must be empty for Telegram Stars
    'currency' => 'XTR',    // Must be XTR for Telegram Stars
    'prices' => [
        [
            'label' => '30 Days Premium',
            'amount' => 50 // Price in Stars (not multiplied by 100)
        ]
    ]
];

$ch = curl_init("https://api.telegram.org/bot{$botToken}/sendInvoice");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($parameters));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new Exception("Failed to send invoice. HTTP Code: {$httpCode}. Response: {$response}");
}

$responseData = json_decode($response, true);
if (!$responseData || !isset($responseData['ok']) || !$responseData['ok']) {
    throw new Exception("Telegram API Error: " . ($responseData['description'] ?? 'Unknown error'));
}

echo "Invoice sent successfully. Message ID: " . $responseData['result']['message_id'] . "\n";

<?php
// webhook.php

header('Content-Type: application/json');

$botToken = getenv('TELEGRAM_BOT_TOKEN');
$secretToken = getenv('TELEGRAM_SECRET_TOKEN'); // Set when configuring setWebhook

// 1. Validate the incoming request source
$headers = getallheaders();
$receivedToken = $headers['X-Telegram-Bot-Api-Secret-Token'] ?? '';

if ($secretToken && !hash_equals($secretToken, $receivedToken)) {
    http_response_code(403);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// 2. Parse the incoming JSON payload
$rawInput = file_get_contents('php://input');
$update = json_decode($rawInput, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid JSON']);
    exit;
}

// 3. Route: Pre-Checkout Query
if (isset($update['pre_checkout_query'])) {
    handlePreCheckout($update['pre_checkout_query'], $botToken);
    exit;
}

// 4. Route: Successful Payment
if (isset($update['message']['successful_payment'])) {
    handleSuccessfulPayment($update['message'], $botToken);
    exit;
}

// Fallback for other update types
echo json_encode(['status' => 'ignored']);

/**
 * Answer the pre-checkout query to authorize or deny the transaction.
 */
function handlePreCheckout(array $query, string $botToken): void
{
    $queryId = $query['id'];
    $payload = json_decode($query['invoice_payload'], true);

    // Perform server-side checks (e.g., check stock, verify user eligibility)
    $isAvailable = true; 

    if (!$payload || !$isAvailable) {
        sendPreCheckoutAnswer($queryId, false, "This item is currently unavailable.", $botToken);
        return;
    }

    // Approve the payment
    sendPreCheckoutAnswer($queryId, true, null, $botToken);
}

/**
 * Send the answerPreCheckoutQuery request to Telegram.
 */
function sendPreCheckoutAnswer(string $queryId, bool $ok, ?string $errorMessage, string $botToken): void
{
    $parameters = [
        'pre_checkout_query_id' => $queryId,
        'ok' => $ok
    ];

    if (!$ok && $errorMessage) {
        $parameters['error_message'] = $errorMessage;
    }

    $ch = curl_init("https://api.telegram.org/bot{$botToken}/answerPreCheckoutQuery");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($parameters));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);

    curl_exec($ch);
    curl_close($ch);
}

/**
 * Process the finalized payment and provision the digital product.
 */
function handleSuccessfulPayment(array $message, string $botToken): void
{
    $payment = $message['successful_payment'];
    $payload = json_decode($payment['invoice_payload'], true);

    if (!$payload) {
        // Log error: received a payment with an unparseable payload
        return;
    }

    // Verify currency and amount match your database records for this SKU
    $expectedCurrency = 'XTR';
    $expectedAmount = 50; // Stars

    if ($payment['currency'] !== $expectedCurrency || $payment['total_amount'] !== $expectedAmount) {
        // Log error: potential price tampering attempt
        return;
    }

    // TODO: Mark the order as paid in your database using $payload['order_id']
    // TODO: Provision the digital product to the user

    // Acknowledge the webhook to Telegram
    echo json_encode(['status' => 'success']);
}