팝업레이어 알림
팝업레이어 알림이 없습니다.
텔레그램 봇/미니앱 개발자를 위한 스타즈 결제 API(sendInvoice) 구현 가이드
developer_mode Developer Payment API Guide
텔레그램 봇/미니앱 개발자를 위한
스타즈 결제 API(sendInvoice) 구현 가이드
텔레그램 봇 API 환경에서 인앱결제 수수료 부담이 없는 가상 상품 결제 수단 '스타즈(Stars)'의 결제 인보이스 생성(sendInvoice)부터 Webhook 기반의 실시간 트랜잭션 수신 및 검증, 영수증 발급까지 개발자 구현 가이드를 제공합니다.
schedule권장 리딩 타임 약 4분 30초 api호출 엔드포인트 sendInvoice & answerPreCheckoutQuery terminal결제 화폐 단위 XTR (Telegram Stars)
안녕하세요! 텔레그램 한글사이트(telegram.pe.kr) 공식 개발사 및 가이드 파트너입니다. 텔레그램은 미니앱(Mini Apps) 및 봇 생태계 내에서 유저가 별도의 외부 카드결제 모듈 없이 간편하게 디지털 재화나 유료 콘텐츠를 구매할 수 있도록 결제 API를 지원하고 있습니다.
특히 결제 수단으로 스타즈(Stars, 통화 코드: XTR)를 매핑할 경우, 복잡한 신용카드사나 PG사 승인 연동이 필요 없으며 텔레그램 인프라 위에서 즉각적인 트랜잭션이 완료됩니다. 오늘은 개발자가 봇 API 명세를 활용해 인보이스를 발행하고, 유저가 결제 완료 버튼을 눌렀을 때의 Webhook 이벤트를 캡처하여 안전하게 영수증을 검증하는 흐름을 완벽 가이드합니다.
account_tree 01 / 스타즈 API 결제 라이프사이클 3단계 명세
텔레그램 스타즈 API 결제는 총 3가지 API 호출 및 Webhook 이벤트 수신 단계를 거쳐 안전하게 에스크로(Escrow) 처리됩니다.
1. sendInvoice 인보이스 생성
결제창을 생성하여 유저에게 전송하는 API 요청 단계입니다.
sendInvoice메소드를 호출할 때 화폐 코드는 반드시XTR,provider_token은 빈 값""혹은 전용 샌드박스 값을 지정합니다.- 메소드 성공 시 인라인 결제 버튼이 포함된 메시지가 유저 채팅방으로 전송되며 유저가 클릭하면 텔레그램 보안 결제창이 팝업됩니다.
2. PreCheckoutQuery 사전 검증
결제 승인 직전에 웹훅으로 수신되는 사전 확인 요청입니다.
- 유저가 지갑 암호 및 결제 동의를 끝내면, 최종 출금 처리 전에 봇 서버 웹훅으로
PreCheckoutQuery이벤트가 전달됩니다. - 봇 서버는 10초 이내에 재고 및 가격 유효성을 확인 후
answerPreCheckoutQueryAPI를ok=true로 응답해야 결제가 실시간 승인됩니다.
3. SuccessfulPayment 결제 완료
출금 완료 후 수신되는 최종 영수증 및 트랜잭션 보존 단계입니다.
- 결제 금액 차감이 완료되면 봇 웹훅으로
successful_payment오브젝트가 포함된 메시지 업데이트가 수신됩니다. - 오브젝트 내부의
telegram_payment_charge_id(텔레그램 고유 영수증 ID) 값을 DB에 기록하고, 해당 유저에게 디지털 재화 지급을 승인 처리합니다.
code 02 / sendInvoice API 필수 파라미터 구조
개발자가 봇 API를 호출할 때 전달해야 하는 JSON 페이로드 구조 중 핵심이 되는 속성 정의 목록입니다.
일반 카드 결제 시에는 스트라이프(Stripe) 등 PG사에서 발급받은 공급자 토큰이 필요하지만, 스타즈(XTR) 결제 시에는 텔레그램 시스템 내부 결제 모델을 사용하므로 provider_token 값은 반드시 빈 문자열 ""로 지정해야 정상적으로 텔레그램 스타즈 결제 인터페이스가 활성화됩니다.
상품 가격 리스트를 정의하는 prices 속성은 LabeledPrice 배열을 전달받습니다. 단, 스타즈 화폐 단위(XTR)를 사용할 때는 소수점 단위가 전혀 인정되지 않으므로, 1 Star는 API 상에서 amount: 1로 직접 대입합니다. (일반 달러/원화 결제 시에는 센트 단위 배율을 위해 100배수를 적용하는 것과 상이하므로 실수를 피해야 합니다.)
유저 결제 시 봇 내부 DB 주문 고유번호를 식별하기 위한 개발자 임의 데이터 영역입니다. 외부에는 노출되지 않고 봇 웹훅의 PreCheckoutQuery 및 SuccessfulPayment 수신 시점에 그대로 반환받게 되므로, 이를 이용해 유저 어뷰징이나 결제 위변조를 예방할 수 있습니다.
terminal 1. 인보이스 상품 단가 설정 (Stars)
- 10 Stars (소형 앱 아이템)
- 100 Stars (중형 구독 패스)
- 500 Stars (대형 프리미엄 권한)
2. 사용자 결제 테스트 시나리오
- 결제 승인 및 성공 (Successful Payment)
- PreCheckout 검증 실패 (품절/오류 반환)
- 사용자가 팝업창에서 수동 취소
Bot Webhook Console API v2.0 진단 로그
play_arrow API 웹훅 연동 시뮬레이션 가동
사용자의 결제창이 켜지고 텔레그램 서버가 봇 서버에 던지는 PreCheckoutQuery는 10초의 엄격한 유효 타임아웃이 걸려 있습니다. 만약 봇 서버가 10초 이내에 answerPreCheckoutQuery API를 호출해 응답을 전송하지 않으면 텔레그램 서버는 유저 지갑에서 돈을 인출하지 않고 결제를 강제 취소합니다. 또한, 네트워크 지연으로 인한 중복 결제(이중 인출)를 막기 위해 전달된 payload 또는 id 값을 봇 서버 메모리 캐시(Redis 등)에 즉시 저장하여 결제가 한 번만 처리되도록 뮤텍스(Mutex) 락을 구현해야 안전합니다.
스타즈 출금 및 비즈니스 정산 가이드
개발자가 획득한 스타즈 수익금 출금 요령 및 수수료 절약 꿀팁은 아래 가이드를 참고해 보세요.