가이드 · 텔레그램 Stars

봇의 텔레그램 Stars 인보이스(XTR): 개발자를 위한 결제 흐름 단계별 정리

봇으로 디지털 상품을 Stars로 판매하기: XTR 통화의 sendInvoice, 10초 내 pre_checkout_query 응답, successful_payment, charge_id 저장, 전달 방식, 출시 체크리스트.

게시일:

봇의 텔레그램 Stars 인보이스(XTR): 개발자를 위한 결제 흐름 단계별 정리

봇이 구독, 콘텐츠, AI 요청 같은 디지털 상품을 판다면 결제는 Telegram Stars로만 가능합니다. 공식 Bot API 문서를 바탕으로 텔레그램 Stars 인보이스(XTR) 흐름을 단계별로 봅니다. 이유는 봇의 디지털 상품은 Stars로만을 참고하세요.

흐름 요약

단계봇텔레그램
1sendInvoice, currency = XTR—
2대기pre_checkout_query
3answerPreCheckoutQuery(10초 내)—
4대기successful_payment
5charge_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%.

시작하기