봇의 텔레그램 Stars 인보이스(XTR): 개발자를 위한 결제 흐름 단계별 정리
봇으로 디지털 상품을 Stars로 판매하기: XTR 통화의 sendInvoice, 10초 내 pre_checkout_query 응답, successful_payment, charge_id 저장, 전달 방식, 출시 체크리스트.
게시일:

봇이 구독, 콘텐츠, AI 요청 같은 디지털 상품을 판다면 결제는 Telegram Stars로만 가능합니다. 공식 Bot API 문서를 바탕으로 텔레그램 Stars 인보이스(XTR) 흐름을 단계별로 봅니다. 이유는 봇의 디지털 상품은 Stars로만을 참고하세요.
흐름 요약
| 단계 | 봇 | 텔레그램 |
|---|---|---|
| 1 | sendInvoice, currency = XTR | — |
| 2 | 대기 | pre_checkout_query |
| 3 | answerPreCheckoutQuery(10초 내) | — |
| 4 | 대기 | successful_payment |
| 5 | charge_id 저장, 상품 전달 | — |
1단계: 인보이스 생성
봇 인보이스는 sendInvoice로 만들고 provider_token은 빈 문자열, 통화는 XTR입니다. 개인 채팅, 그룹, 채널로 보낼 수 있습니다. 인라인 인보이스는 inputInvoiceMessageContent로 사용자가 공유하며 Pay 버튼을 여러 번 쓸 수 있습니다.
2단계: 전달 방식
start_parameter로 정합니다. 멀티 채팅 인보이스는 전달본에도 Pay 버튼이 있고, 단일 채팅 인보이스는 보낸 채팅에서만 결제되며 전달본에는 봇 딥링크가 표시됩니다. 봇과의 개인 채팅에 보낸 단일 채팅 인보이스는 한 번만 결제됩니다.
3단계: 사전 결제 확인
사용자가 Pay를 누르면 봇은 pre_checkout_query를 받고 10초 안에 answerPreCheckoutQuery로 응답해야 합니다. 거절 시 사용자가 이해할 수 있는 이유를 쓰세요.
4~5단계: 결제와 전달
successful_payment를 받은 뒤에만 전달하고 telegram_payment_charge_id를 저장합니다.
출시 전 체크
봇 소유자 계정의 2단계 인증, /terms, /support, /paysupport 제공, refundStarPayment로 분쟁 대응(Stars 환불과 /paysupport), 서버 안정성과 백업. 테스트는 전용 테스트 환경에서 무료로 하세요. 서비스에서 Stars를 자동 구매해야 한다면 PayStars API와 API 개요를 보세요.
자주 묻는 질문
Stars 대신 암호화폐나 다른 통화를 받을 수 있나요?
아닙니다. 텔레그램 앱 내 디지털 상품은 Stars로만 결제합니다.
결제 테스트는 어떻게 하나요?
텔레그램 전용 테스트 환경에서 Stars 결제를 무료로 테스트할 수 있습니다.
환불은 어떻게 하나요?
Bot API의 refundStarPayment 메서드를 사용합니다.
출처
USD(USDT)로 Stars와 Premium 구매
API 키: 0%(Fragment 가격). 웹사이트: 5%.
다른 뉴스
Telegram Stars 봇의 환불 정책 작성하기: 템플릿과 예시Telegram Stars 봇 환불 정책에 담아야 할 내용: 대상, 기한, /paysupport와 refundStarPayment, 그리고 그대로 고쳐 쓸 수 있는 예시 문구.읽기 →
계정에 접근할 수 없게 되면 Telegram Stars는 어떻게 될까Stars는 휴대폰이 아니라 Telegram 계정에 속합니다. 접근을 잃었을 때 Stars가 어떻게 되는지, 다시 로그인하는 방법과 잔액을 지키는 방법을 알아보세요.읽기 →
창작자와 사업자를 위한 Telegram Stars 수익 기록 관리Telegram Stars 수익을 깔끔하게 기록하는 법입니다. 무엇을 적을지, Fragment 출금 추적, 개인과 사업 분리, 회계사에게 물어볼 질문을 정리했습니다.읽기 →