API 레퍼런스: 구독

Crypto Bot에는 없던 확장 기능, 정기 결제예요. 요금제(금액 + 주기)를 만들어 승인 링크를 사용자에게 보내면, 주기마다 플랫폼이 그 사람의 지갑 잔액에서 결제하고 수수료를 뺀 금액을 앱 잔액에 넣어 줘요. 공통 규칙은 Merchant API 레퍼런스에 있어요.

구독 모델

요금제는 한번 정하면 바뀌지 않는 스냅샷이에요. 사용자가 승인하는 약정은 딱 이 금액, 이 주기예요. 가격을 바꾸려면 새 요금제를 만들고 예전 것은 보관 처리하세요. 이미 구독 중인 사람은 승인했던 조건 그대로 갱신돼요. 첫 주기는 승인할 때 결제돼요.

갱신은 주기가 끝날 때마다 자동으로 청구돼요. 갱신이 실패하면(잔액 부족, 계정 제한 등) 구독이 grace로 넘어가고, 유예 기간(지금은 48시간) 안에서 한 시간마다 다시 시도해요. 그래도 받지 못하면 구독은 expired가 돼요. 가맹점은 current_period_end를 이용 만료 시각으로 보면 돼요.

구독의 모든 단계마다 원할 때만 켜는 webhook이 있어요. subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — subscriptions 권한.

파라미터	타입	필수	설명
name	string	예	1~64자, 구독하는 사람에게 보여요
asset	string	예	자산 코드
amount	string	예	주기마다 청구할 금액, 양수 소수점 문자열
period_days	integer	예	결제 주기(일). 플랫폼 최소값(지금은 7)부터 365까지

결과는 요금제 객체예요. plan_id, name, asset, amount, amount_minor, period_days, archived, 사용자에게 승인을 받으러 보내는 t.me 링크인 mini_app_subscribe_url, 그리고 created_at이 들어 있어요.

오류: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled(플랫폼에서 이 기능을 꺼 둔 경우).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — read 권한, 파라미터 없음. {"items": [plan, …]}를 최신순으로 돌려주고, 요금제마다 필드가 하나 더 붙어요. active_subscribers — 살아 있는 구독(active + grace) 수예요.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — subscriptions 권한. 파라미터는 plan_id 하나예요. 새로운 승인만 막고, 이미 있는 구독은 각자의 스냅샷대로 계속 갱신돼요(하나씩 끝내려면 cancelSubscription을 쓰세요). 보관 처리는 API로 되돌릴 수 없어요. 결과는 archived: true가 된 요금제 객체예요. 오류: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — read 권한. 필터: plan_id, user_id, status(active / grace / cancelled / expired), 그리고 offset / count(최대 500). {"items": [subscription, …]}를 최신순으로 돌려줘요.

구독 객체에는 subscription_id, plan_id, user_id(구독하는 사람의 Telegram ID), 스냅샷 조건(asset, amount, amount_minor, period_days), status, auto_renew, period_no(지금까지 결제된 주기 수), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by(user 또는 merchant), expired_at이 들어 있어요.

cancelSubscription

POST /pay/api/cancelSubscription — subscriptions 권한. 파라미터는 subscription_id 하나예요. 갱신을 멈춰요(cancelled_by: "merchant"). 이미 결제한 주기는 current_period_end까지 그대로 쓸 수 있고, 상태는 바로 cancelled로 바뀌고, 구독하던 사람에게는 알림이 가요. 취소한 사람도 같은 요금제 링크로 나중에 다시 승인할 수 있어요. 결과는 최신 상태의 구독 객체예요.

오류: 404 sub_not_found, 409 sub_not_active(이미 취소했거나 만료된 경우).