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