가이드 · PayStars

개발자를 위한 PayStars API: 봇에서 Stars와 Premium을 판매하는 전체 흐름

PayStars REST API의 작동 방식을 통합 계획으로 정리했습니다: X-API-Key, 사용자명 확인, USD 견적과 max_usd, 멱등 주문, 409 price_changed 오류, TxId 검증.

게시일: · 수정일:

개발자를 위한 PayStars API: 봇에서 Stars와 Premium을 판매하는 전체 흐름

내 봇이나 쇼핑몰, 앱에서 텔레그램 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%.

시작하기