개발자를 위한 PayStars API: 봇에서 Stars와 Premium을 판매하는 전체 흐름
PayStars REST API의 작동 방식을 통합 계획으로 정리했습니다: X-API-Key, 사용자명 확인, USD 견적과 max_usd, 멱등 주문, 409 price_changed 오류, TxId 검증.
게시일: · 수정일:

내 봇이나 쇼핑몰, 앱에서 텔레그램 Stars와 Premium을 팔고 싶다면 PayStars API가 하나의 HTTPS 인터페이스와 웹사이트와 공유되는 USD 잔액을 제공합니다. 이 글은 API 문서를 반복하지 않고, 통합을 처음부터 끝까지 어떻게 구성하는지 보여 줍니다.
구조 한눈에 보기
내 시스템은 USDT로 잔액 충전, 가격 조회, 주문 생성 세 가지만 합니다. 텔레그램 공식 구매 흐름을 통한 전달은 PayStars가 처리합니다.
| 구성 | 역할 |
|---|---|
| 접근 | X-API-Key 헤더, 키는 대시보드에서 생성 |
| 잔액 | USD, USDT(TON, BEP20 또는 TRC20)로 충전 |
| 가격 | Fragment 가격 × 1.05, 센트 단위 올림 |
| 제한 | 키당 초당 10회 |
| 투명성 | 완료 주문마다 공개 TxId |
1단계: 잔액 충전
POST /usd/invoice에 금액과 체인("ton", "bsc" 또는 "trc20")을 보내면 30분간 유효한 정확한 금액을 받습니다. 최소 0.1 USDT입니다.
2단계: 받는 사람 확인
POST /api/v1/check-username이 받는 사람을 확인하고 단기 확인 토큰을 돌려줍니다. 고객이 오타를 내도 차감 전에 알 수 있습니다.
3단계: 가격 조회와 상한 설정
POST /api/v1/usd/quote는 현재 가격(usd)과 마크업(markup_percent: 5)을 반환합니다. 가격은 시장을 따르므로 주문마다 새 견적을 받고, max_usd를 견적 금액으로 넣고, 항상 currency: "USD"를 보내세요. 생략하면 계정에 저장된 설정이 쓰입니다.
4단계: 주문 생성
POST /api/v1/stars/buy 또는 /api/v1/premium/buy. 모든 요청에 Idempotency-Key가 필수라 연결이 끊겨 재시도해도 두 번 차감되지 않습니다. 키를 주문 ID와 함께 DB에 저장하세요.
5단계: 상태 추적
GET /api/v1/order/{id}와 /api/v1/orders로 상태와 내역을 봅니다. 대부분 몇 분 안에 전달되며, 완료 주문은 TxId를 받아 PayStars 공개 원장에서 나와 고객 모두 확인할 수 있습니다.
오류 처리
- 409 price_changed: 가격이 max_usd를 넘어 아무것도 차감되지 않았습니다. 새 견적을 받아 고객에게 보여 주세요.
- 요청 제한: 초당 10회를 넘지 않도록 큐나 지연을 두세요.
- 재시도: 항상 같은 Idempotency-Key로 합니다.
출시 전 점검
API 키는 코드가 아닌 서버 환경 변수에 두고, 50 Stars 소액 실주문으로 전체 흐름을 시험하고, 고객에게 TxId를 보여 주세요. 전체 문서는 PayStars Stars API와 API USD 가격, 봇 내 결제는 봇의 디지털 상품은 Stars로만을 참고하세요.
자주 묻는 질문
샌드박스가 있나요?
별도 샌드박스는 없으며, 통합 중에는 소액 실주문(50 Stars)으로 테스트하는 것을 권합니다.
어떤 언어로 연동하나요?
HTTPS 요청이 가능한 모든 언어입니다. Python, Node.js, PHP 퀵스타트가 있습니다.
잔액은 어떻게 충전하나요?
TON, BEP20 또는 TRC20 USDT로 최소 0.1 USDT부터 충전하며, 인보이스는 정확한 금액으로 30분간 유효합니다.
출처
USD(USDT)로 Stars와 Premium 구매
API 키: 0%(Fragment 가격). 웹사이트: 5%.
다른 뉴스
우즈베키스탄에서 Telegram Stars·Premium 사기: 카드 또는 USDT우즈베키스탄에서 Telegram Stars나 Premium을 사는 방법: @StarKerakBot의 Uzcard·Humo, paystars.uz/uz/의 USDT, 공식 경로와 알아 둘 현지 규정.읽기 →
대회 우승자에게 Telegram Stars나 Premium 상품 주기: 주최자 플레이북직접 진행한 퀴즈, 공모전, 해커톤 우승자에게 Telegram Stars나 Premium을 전달하는 방법: 예산, @username 수집, PayStars를 통한 전달, 결과 공지.읽기 →
PayStars FAQ: 로그인, USDT 충전, Stars·Premium 주문에 관한 자주 묻는 질문PayStars에 관해 가장 많이 묻는 질문을 한 페이지에: 텔레그램 로그인, USDT(TON, BEP20, TRC20) 충전, Stars·Premium 주문, 전달 시간, 보안, API.읽기 →