Telegram Bot API

텔레그램 스타 결제 봇 가이드: 인보이스, 결제 전 확인, 환불, 구독

· 9 분 분량

텔레그램 봇에서 스타(Stars) 결제를 받으려면 통화 XTR과 빈 provider_token으로 sendInvoice 인보이스를 보내고, pre_checkout_query 업데이트에 10초 안에 answerPreCheckoutQuery로 답한 뒤, successful_payment 메시지가 도착했을 때만 상품을 제공하면 됩니다. 텔레그램 앱에서 판매하는 디지털 상품과 서비스는 텔레그램 스타로 결제해야 합니다. 이 글에서는 동작하는 Python·JavaScript 봇으로 텔레그램 스타 결제 봇의 전체 흐름을 구현하고, 환불, 거래 내역, 구독, 유료 미디어까지 다룹니다.

텔레그램 스타 결제 봇의 동작 방식

텔레그램 스타는 앱 내 가상 아이템입니다. 사용자는 Apple·Google 인앱 결제나 @PremiumBot으로 스타를 구매해 봇에서 사용하며, 결제 화면에서 개인 정보를 입력할 필요가 없습니다. 흐름은 다음과 같습니다.

  1. 봇이 인보이스를 보냅니다. 채팅에는 sendInvoice, 링크가 필요하면 createInvoiceLink를 씁니다.
  2. 사용자가 결제 버튼을 누릅니다(필요하면 먼저 스타를 구매).
  3. 봇이 pre_checkout_query가 담긴 업데이트를 받습니다.
  4. 봇이 10초 안에 answerPreCheckoutQuery로 주문을 승인하거나 거절합니다.
  5. 텔레그램이 successful_payment가 담긴 서비스 메시지를 보냅니다.
  6. 봇이 telegram_payment_charge_id를 저장하고 상품을 제공합니다.

디지털 상품은 스타로 판매해야 합니다. 텔레그램은 다른 곳에서 운영하는 웹사이트나 결제 대행사와 관계없이, 봇이나 Mini App이 텔레그램 앱 안에서 디지털 상품과 서비스를 판매할 때는 텔레그램 스타를 써야 한다고 명시합니다. 그렇지 않으면 모바일 사용자에게 봇을 노출할 수 없습니다. 다른 통화와 결제 대행사는 provider token을 쓰는 별도 흐름의 실물 상품에만 해당합니다.

XTR로 sendInvoice 인보이스 보내기

50 스타짜리 최소 인보이스 예시입니다.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Pro 팩",
    "description": "계정에 이미지 생성 50회 추가",
    "payload": "pro-pack-v1",
    "provider_token": "",
    "currency": "XTR",
    "prices": [{"label": "Pro 팩", "amount": 50}]
  }'

이 메서드는 전송된 Message를 반환합니다. 스타 결제에서 중요한 파라미터는 다음과 같습니다.

파라미터텔레그램 스타 결제 규칙
title상품명, 1~32자.
description상품 설명, 1~255자.
payload1~128바이트, 사용자에게 보이지 않습니다. 주문 ID나 상품 ID를 넣으면 결제 전 확인 쿼리와 결제 정보에 그대로 돌아옵니다.
provider_token선택. 스타 결제에서는 빈 문자열을 넘깁니다.
currencyXTR.
pricesLabeledPrice 배열로, 항목이 정확히 하나여야 합니다. amount는 스타 단위 가격(정수)입니다.
start_parameter비워 두면 전달된 사본에도 결제 버튼이 유지됩니다. 값을 넣으면 전달된 사본에는 대신 봇으로 가는 딥링크 URL 버튼이 표시됩니다.
photo_url선택. 상품 이미지이며 photo_size, photo_width, photo_height와 함께 씁니다.

스타 결제에서는 팁(max_tip_amount)을 지원하지 않고, need_name, need_email, need_shipping_address, is_flexible 같은 필드는 무시됩니다. 직접 reply_markup을 추가한다면 첫 번째 버튼은 결제 버튼("pay": true)이어야 하며, 버튼 텍스트의 ⭐와 XTR은 스타 아이콘으로 바뀝니다. 인보이스는 개인 채팅, 그룹, 채널에 보낼 수 있습니다. 코드 없이 시험하려면 Bot API Tester의 sendInvoice에서 위 필드를 채워 자신에게 인보이스를 보내 보십시오.

createInvoiceLink는 같은 title, description, payload, currency, prices를 받지만 메시지를 보내는 대신 인보이스 링크를 문자열로 반환합니다. Mini App에서 Telegram.WebApp.openInvoice(url)로 열거나 일반 링크로 공유할 수 있습니다. 구독에도 이 메서드를 씁니다(아래 참고).

pre_checkout_query에 10초 안에 응답하기

사용자가 결제 버튼을 누르면 봇은 id, from, currency, total_amount, invoice_payload가 담긴 PreCheckoutQuery를 받습니다. 10초 안에 응답하지 않으면 거래가 취소됩니다.

이 핸들러는 빨라야 합니다. 페이로드와 재고만 확인해 응답하고 나머지는 나중에 처리하십시오. 쿼리를 승인했다고 해서 결제가 완료된 것은 아닙니다.

successful_payment 이후에 상품 제공하기

결제가 성공하면 successful_payment 필드가 있는 message가 도착합니다. 이 필드에는 currency, total_amount, invoice_payload, telegram_payment_charge_id가 들어 있습니다. 텔레그램의 규칙은 분명합니다. 상품을 제공하기 전에 반드시 successful_payment를 받았는지 확인해야 합니다. 환불에는 telegram_payment_charge_id와 구매자의 user id가 모두 필요하므로 함께 저장하십시오.

전체 예제: 텔레그램 스타로 판매하는 봇

이 롱 폴링 봇은 /buy를 받으면 인보이스를 보내고, 결제 전 확인 쿼리를 검증하고, 결제를 기록하며, /paysupport에 응답합니다. allowed_updates에 주의하십시오. 업데이트 종류를 제한한다면 pre_checkout_query를 넣어야 하며, 빠지면 결제가 봇에 도달하지 않습니다.

import json
import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
PAYLOAD = "pro-pack-v1"
PRICE = 50  # 텔레그램 스타 단위


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def handle(update):
    query = update.get("pre_checkout_query")
    if query:
        ok = (query["invoice_payload"] == PAYLOAD and query["currency"] == "XTR"
              and query["total_amount"] == PRICE)
        answer = {"pre_checkout_query_id": query["id"], "ok": ok}
        if not ok:
            answer["error_message"] = "이 상품은 판매가 종료되었습니다. /buy로 새 인보이스를 받으세요."
        call("answerPreCheckoutQuery", **answer)  # 10초 안에
        return

    msg = update.get("message")
    if not msg:
        return
    chat_id = msg["chat"]["id"]
    if "successful_payment" in msg:
        payment = msg["successful_payment"]
        with open("payments.jsonl", "a") as f:  # 환불에 필요한 charge id 저장
            f.write(json.dumps({"user_id": msg["from"]["id"],
                                "charge_id": payment["telegram_payment_charge_id"],
                                "payload": payment["invoice_payload"],
                                "amount": payment["total_amount"]}) + "\n")
        call("sendMessage", chat_id=chat_id, text="감사합니다! Pro 팩이 활성화되었습니다.")
    elif msg.get("text") == "/buy":
        call("sendInvoice", chat_id=chat_id, title="Pro 팩",
             description="계정에 이미지 생성 50회 추가",
             payload=PAYLOAD, provider_token="", currency="XTR",
             prices=[{"label": "Pro 팩", "amount": PRICE}])
    elif msg.get("text") == "/paysupport":
        call("sendMessage", chat_id=chat_id,
             text="결제에 문제가 있나요? 메시지 하나로 상황을 알려 주시면 24시간 안에 답변드립니다.")


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "pre_checkout_query"])
    for update in updates:
        offset = update["update_id"] + 1
        handle(update)
import { appendFile } from "node:fs/promises";

const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const PAYLOAD = "pro-pack-v1";
const PRICE = 50; // 텔레그램 스타 단위

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

async function handle(update) {
  const query = update.pre_checkout_query;
  if (query) {
    const ok = query.invoice_payload === PAYLOAD && query.currency === "XTR"
      && query.total_amount === PRICE;
    const answer = { pre_checkout_query_id: query.id, ok };
    if (!ok) answer.error_message = "이 상품은 판매가 종료되었습니다. /buy로 새 인보이스를 받으세요.";
    await call("answerPreCheckoutQuery", answer); // 10초 안에
    return;
  }

  const msg = update.message;
  if (!msg) return;
  const chatId = msg.chat.id;
  if (msg.successful_payment) {
    const payment = msg.successful_payment;
    await appendFile("payments.jsonl", JSON.stringify({ // 환불에 필요한 charge id 저장
      user_id: msg.from.id,
      charge_id: payment.telegram_payment_charge_id,
      payload: payment.invoice_payload,
      amount: payment.total_amount,
    }) + "\n");
    await call("sendMessage", { chat_id: chatId, text: "감사합니다! Pro 팩이 활성화되었습니다." });
  } else if (msg.text === "/buy") {
    await call("sendInvoice", {
      chat_id: chatId, title: "Pro 팩",
      description: "계정에 이미지 생성 50회 추가",
      payload: PAYLOAD, provider_token: "", currency: "XTR",
      prices: [{ label: "Pro 팩", amount: PRICE }],
    });
  } else if (msg.text === "/paysupport") {
    await call("sendMessage", {
      chat_id: chatId,
      text: "결제에 문제가 있나요? 메시지 하나로 상황을 알려 주시면 24시간 안에 답변드립니다.",
    });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", {
    offset, timeout: 30, allowed_updates: ["message", "pre_checkout_query"],
  });
  for (const update of updates) {
    offset = update.update_id + 1;
    await handle(update);
  }
}

JavaScript 버전은 bot.mjs로 저장합니다(Node.js 18 이상). 운영 환경에서는 실제 데이터베이스를 쓰고, telegram_payment_charge_id 기준으로 상품 제공이 한 번만 이루어지도록(멱등성) 구현하십시오. 웹훅에서도 핸들러는 같습니다. 설정 방법과 allowed_updates는 텔레그램 웹훅 설정 가이드를 참고하십시오.

refundStarPayment로 결제 환불하기

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/refundStarPayment" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123456789, "telegram_payment_charge_id": "CHARGE_ID_FROM_SUCCESSFUL_PAYMENT"}'

성공하면 true가 반환되고, 스타가 사용자에게 돌아가며, 채팅에 refunded_payment가 담긴 서비스 메시지가 생깁니다. 제공했던 상품은 회수하십시오. 구매자가 Apple이나 Google에 지불 거절(차지백)을 신청하면 환불된 스타가 봇 잔액에서 차감되며, 텔레그램은 이를 자신이 통제할 수 없는 부분이라고 설명합니다.

잔액과 거래 내역: getMyStarBalance, getStarTransactions

텔레그램 스타 구독

createInvoiceLink에 subscription_period를 넘기면 30일마다 사용자에게 요금을 청구합니다.

채널 유료 입장에는 createChatSubscriptionInviteLink를 씁니다. subscription_period는 2592000, subscription_price는 1~10000 스타이며, 봇에 can_invite_users 관리자 권한이 필요합니다.

sendPaidMedia는 가격을 걸어 둔 사진이나 동영상을 최대 10개까지 보냅니다. star_count는 1~25000이고 payload(0~128바이트)는 선택입니다. 채널에서는 수익이 채널 잔액으로, 그 밖의 곳에서는 봇 잔액으로 들어갑니다. 페이로드가 비어 있지 않고 채널이 아닌 채팅이라면 봇은 구매자와 페이로드가 담긴 purchased_paid_media 업데이트를 받으므로, 업데이트를 필터링한다면 allowed_updates에 추가하십시오.

테스트 환경에서 스타 결제 테스트하기

텔레그램은 전용 테스트 환경에서 스타 결제를 무료로 테스트할 수 있게 해 줍니다. 그곳에서 테스트 계정과 봇을 만든 다음 https://api.telegram.org/bot<token>/test/METHOD_NAME으로 API 요청을 보냅니다. 저희 테스터에도 같은 용도의 TEST 스위치가 있습니다. 단계별 방법은 텔레그램 테스트 서버 가이드에 있습니다. 실제 서비스를 시작할 때는 봇을 운영 환경으로 전환하십시오.

출시 체크리스트와 문제 해결

봇이 처음이라면 텔레그램 봇 만들기부터 시작하십시오. 공식 레퍼런스는 텔레그램 스타 결제 문서와 Bot API의 Payments 섹션에 있습니다.

자주 묻는 질문

텔레그램 봇에서 스타 결제를 받으려면 어떻게 하나요?

sendInvoice(또는 createInvoiceLink)로 currency를 XTR, provider_token을 빈 값, prices에 항목 하나만 넣어 인보이스를 보냅니다. pre_checkout_query 업데이트에는 10초 안에 answerPreCheckoutQuery로 답하고, successful_payment 메시지가 오면 상품을 제공합니다.

텔레그램 스타 결제에 provider token이 필요한가요?

아닙니다. provider_token은 실물 상품과 서비스에만 필요합니다. 텔레그램 스타 결제에서는 빈 문자열을 넘기거나 파라미터를 생략합니다.

텔레그램 봇에서 디지털 상품을 원화, 카드, 암호화폐로 팔 수 있나요?

아닙니다. 텔레그램에 따르면 App Store와 Google Play 정책 때문에 텔레그램 앱 안에서 판매하는 디지털 상품과 서비스는 텔레그램 스타로만 결제해야 합니다. 다른 통화와 결제 대행사는 실물 상품과 서비스에만 쓸 수 있습니다.

텔레그램 스타 결제는 어떻게 환불하나요?

구매자의 user_id와 successful_payment 메시지의 telegram_payment_charge_id를 넘겨 refundStarPayment를 호출합니다. 결제마다 이 ID를 저장해 두지 않으면 나중에 환불할 수 없습니다.

봇에서 텔레그램 스타 구독은 어떻게 동작하나요?

createInvoiceLink에 subscription_period = 2592000(30일, 현재 유일하게 허용되는 값)을 지정해 인보이스 링크를 만듭니다. 가격은 10000 스타를 넘을 수 없습니다. 갱신 결제는 is_recurring이 붙은 successful_payment로 들어오며, editUserStarSubscription으로 갱신을 취소하거나 다시 켤 수 있습니다.

텔레그램 스타 결제를 무료로 테스트할 수 있나요?

텔레그램의 전용 테스트 환경을 쓰면 됩니다. 그곳에서 테스트 계정과 봇을 만들고 /bot<token>/test/METHOD_NAME으로 API를 호출합니다. 텔레그램은 테스트 환경에서 스타 결제를 자유롭게 테스트할 수 있다고 안내합니다.

텔레그램 봇 만들기: @BotFather로 생성하고 첫 메시지 보내기

텔레그램 봇 만들기 가이드입니다. @BotFather의 /newbot으로 봇을 생성하고 토큰을 getMe로 확인한 뒤, getUpdates와 sendMessage로 첫 메시지를 보내는 과정을 curl과 Python 예제로 설명합니다.

텔레그램 봇 배포와 호스팅: VPS, Docker, 서버리스

텔레그램 봇 배포 방법: 폴링과 웹훅 선택, VPS의 systemd 서비스, Docker, secret_token을 검증하는 Cloudflare Workers, 출시 전 체크리스트까지 정리했습니다.

텔레그램 봇 API 10.0~10.5 변경 사항: 봇 설정, 위젯, 리치 메시지, 임시 메시지, 게스트 모드

텔레그램 봇 API 10.0~10.5의 새 기능을 정리했습니다. setMySettings와 BotFullInfo, HTML 위젯, 리치·임시 메시지, 게스트 모드를 JSON 예제와 함께 설명합니다.

텔레그램 봇 API 오류 총정리: 오류별 의미와 해결 방법

텔레그램 봇 API 오류를 코드별로 정리했습니다. 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after의 원인과 해결, 처리 코드까지 다룹니다.

텔레그램 봇 API 제한 총정리: 전송 속도, 429 오류, 파일 크기, 메시지 길이

텔레그램 봇 API 전송 제한을 정리했습니다. 초당 30건, 채팅당 초당 1건, 그룹 분당 20건 기준과 429 retry_after 처리, 파일 크기·메시지 길이 제한까지 다룹니다.

텔레그램 봇 명령어 가이드: setMyCommands, 명령어 스코프, /start 딥링크

텔레그램 봇 명령어 설정 방법: @BotFather /setcommands, 스코프·언어별 setMyCommands, /start 딥링크 파라미터, 그룹의 /cmd@bot 처리를 예제로 설명합니다.

텔레그램 봇 키보드: 인라인 키보드, 콜백 버튼, 리플라이 키보드

텔레그램 봇 버튼 만드는 법을 정리했습니다. callback_data 인라인 키보드, answerCallbackQuery, 버튼을 누른 뒤 메시지 수정, 리플라이 키보드와 ForceReply까지 다룹니다.

n8n 텔레그램 연동 가이드: 봇 연결, 워크플로 트리거, 메시지 보내기

n8n 텔레그램 연동 방법: 봇 토큰을 Access Token으로 등록하고, 공개 HTTPS로 Telegram Trigger 웹훅을 받고, chat id로 메시지를 보내며 자주 나는 오류를 해결합니다.

텔레그램 봇 API로 메시지 보내기: sendMessage 사용법과 예제

텔레그램 봇 API 메시지 보내기 가이드입니다. sendMessage를 curl·Python·JavaScript로 호출하는 예제, HTML·MarkdownV2 서식, 인라인 버튼, 그룹·채널 전송, 400·403·429 오류 해결법을 정리했습니다.

텔레그램 봇 토큰: 발급부터 확인, 폐기, 안전한 보관까지

텔레그램 봇 토큰을 @BotFather에서 발급받는 법, 기존 봇의 토큰 찾기, getMe로 유효성 확인, 유출 시 폐기 방법을 정리했습니다. n8n·AI 비서 연동에 필요한 bot token과 chat id도 안내합니다.

텔레그램 웹훅 설정 가이드: setWebhook, secret_token, getWebhookInfo

텔레그램 봇 웹훅 설정 방법을 단계별로 정리했습니다. setWebhook 파라미터, secret_token 헤더 검증 코드, getWebhookInfo 상태 확인, deleteWebhook으로 되돌리기, 409·HTTPS 오류 해결까지 다룹니다.

텔레그램 chat id 확인방법: 개인, 그룹, 채널, 토픽별 chat id 찾기

텔레그램 chat id 확인방법을 개인 채팅, 그룹, 슈퍼그룹, 채널, 포럼 토픽별로 정리했습니다. getUpdates로 chat id를 찾는 법, -100으로 시작하는 ID의 의미, 결과가 비어 있을 때 해결법까지 설명합니다.

텔레그램 인라인 봇 가이드: 인라인 모드 활성화와 인라인 쿼리 응답

텔레그램 인라인 봇 만드는 법: @BotFather나 setMySettings로 인라인 모드를 켜고 inline_query에 answerInlineQuery로 답하는 과정을 Python·JS 예제로 설명합니다.

텔레그램 테스트 서버: 텔레그램 봇 테스트 환경에서 봇을 테스트하는 방법

텔레그램 테스트 서버 사용법을 정리했습니다. 테스트 환경 로그인, 테스트용 봇 만들기, /test/ 주소로 Bot API 호출하기, Bot API Tester의 TEST 스위치까지 다룹니다.

텔레그램 웹사이트 위젯: 로그인 위젯, 게시물 임베드, 댓글, 공유 버튼

웹사이트에 텔레그램을 붙이는 방법을 정리했습니다. 새 Telegram Login(OIDC), 기존 로그인 위젯과 hash 검증 코드, 게시물 임베드, 댓글, 공유 버튼까지 다룹니다.

TelegramWidget JavaScript API: 텔레그램 위젯 API 레퍼런스와 오류 코드, 제한

텔레그램 위젯의 TelegramWidget JavaScript API를 정리했습니다. 속성, request(), 이벤트, 오류 코드, CSS 변수, widget_query와 answerWidgetQuery, 모든 제한값까지 담았습니다.

텔레그램 위젯 예제: HTML과 Python 봇 코드 전체 공개

바로 실행할 수 있는 텔레그램 위젯 예제 모음입니다. 정적 주문 카드, widget_query 카운터, 실시간 공유 투표, 브라우저 미리보기까지 HTML과 Python 코드로 설명합니다.

텔레그램 위젯 가이드: 봇 메시지 안에서 동작하는 HTML 위젯

Bot API 10.4에 추가된 텔레그램 위젯의 개념, sendWidget 사용법, chat_data와 public_data, 현재 사용 가능한 범위와 Mini App과의 차이를 정리했습니다.

텔레그램 미니앱 테스트 가이드: 브라우저 목 모드부터 실제 텔레그램까지

텔레그램 미니앱 테스트 방법을 단계별로 정리했습니다. 브라우저 목(mock) 모드, HTTPS 터널로 localhost 열기, 테스트 환경, 플랫폼별 DevTools, initData 검증까지 다룹니다.