텔레그램 봇 구독 — 스타로 매달 결제받기

스타 구독이란

봇이 사용자에게 텔레그램 스타로 매달 결제를 받는 방식입니다. 사용자가 한 번 결제하면 기간이 끝날 때마다 스타 잔액에서 자동으로 다시 결제되고, 사용자가 해지하면 멈춥니다. 디지털 서비스(유료 기능·콘텐츠)를 파는 봇이라면 앱 스토어 규정상 스타로 받아야 합니다 — 한 번 결제는 봇 스타 결제에 있습니다.

규칙	내용(공식 문서)
통화	XTR(텔레그램 스타)만
기간	지금은 30일(2592000초) 하나뿐
가격	한 번에 최대 10,000 스타
동시 구독	한 봇에 여러 구독이 동시에 걸려도 된다 — 같은 사용자가 둘 이상 들어도 된다

결제 링크 만들기

createInvoiceLink 에 subscription_period 를 넣으면 구독 결제 링크가 됩니다. 이 링크를 버튼이나 미니 앱에서 열게 합니다.

curl https://api.telegram.org/bot123456:ABC-EXAMPLE/createInvoiceLink \
  -H "Content-Type: application/json" \
  -d '{"title":"프리미엄 기능","description":"광고 없이 무제한 사용",
       "payload":"sub_basic","currency":"XTR",
       "prices":[{"label":"한 달","amount":100}],
       "subscription_period":2592000}'

스타 결제에는 provider_token 이 필요 없습니다. 가격(amount)은 예시 값입니다.

결제와 갱신 알아보기

결제가 끝나면 봇은 successful_payment 가 든 메시지를 받습니다. 구독이면 칸이 몇 개 더 붙습니다.

칸	뜻
is_recurring	구독 결제다
is_first_recurring	그 구독의 첫 결제다 — 이후 갱신 결제에는 없다
subscription_expiration_date	이번 결제로 쓸 수 있는 마지막 시각(유닉스 시간)
telegram_payment_charge_id	결제 번호 — 해지·환불에 쓰므로 꼭 저장

내 서버에는 사용자별 만료 시각을 저장하고, 기능을 열어 줄 때마다 그 시각을 봅니다. 갱신 결제가 오면 만료 시각을 새 값으로 바꿉니다.

해지·되살리기·환불

• editUserStarSubscription — 봇 쪽에서 그 사용자의 다음 갱신을 막거나(해지) 다시 이어지게(되살리기) 합니다. 사용자 ID 와 결제 번호가 필요합니다.
• refundStarPayment — 결제 하나를 환불합니다.
• 사용자는 자기 텔레그램 설정의 스타 화면에서 구독을 보고 해지할 수 있습니다. 해지해도 이미 낸 기간이 끝날 때까지는 씁니다.

채널도 같은 30일 방식으로 유료 초대 링크를 만들 수 있습니다(createChatSubscriptionInviteLink) — 구독료를 내야 들어오는 비공개 채널입니다.