Tài liệu API: gói đăng ký

Thu phí định kỳ — một phần mở rộng so với Crypto Bot. Bạn tạo một gói (số tiền + chu kỳ), gửi cho người dùng liên kết đăng ký, rồi nền tảng tự trừ tiền từ số dư ví của họ mỗi kỳ và cộng vào số dư ứng dụng của bạn phần đã trừ phí. Các quy ước chung nằm ở trang tài liệu Merchant API.

Mô hình

Một gói là bản ghi cố định, không sửa được: người dùng đăng ký đúng số tiền này cho đúng chu kỳ này. Muốn đổi giá thì tạo gói mới và lưu trữ gói cũ — người đang đăng ký vẫn gia hạn theo đúng điều khoản họ đã đồng ý. Kỳ đầu tiên được thu ngay khi đăng ký.

Phí gia hạn được thu tự động vào cuối mỗi kỳ. Khi một lần gia hạn thất bại (số dư không đủ, tài khoản bị hạn chế), gói đăng ký chuyển sang grace và nền tảng thử lại mỗi giờ trong thời gian gia hạn (thời lượng do nền tảng quy định); nếu vẫn không thu được, gói đăng ký thành expired. Dùng current_period_end làm mốc kết thúc quyền truy cập. Nếu phí gia hạn được thu trong lúc grace, kỳ tiếp theo bắt đầu từ current_period_end cũ chứ không phải từ lúc thanh toán.

Các sự kiện trong vòng đời có webhook riêng và cần được bật thủ công: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired. Việc chuyển sang grace không có webhook (người đăng ký nhận tin nhắn trong Telegram); nếu cần, hãy gọi định kỳ getSubscriptions với status=grace. Nếu ứng dụng của bạn bị xóa, các gói đăng ký của nó sẽ bị hủy ở lần gia hạn kế tiếp với cancelled_by: "merchant".

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — scope subscriptions.

Tham số	Kiểu	Bắt buộc	Ý nghĩa
name	string	có	1–64 ký tự, hiện cho người đăng ký
asset	string	có	mã tài sản
amount	string	có	số tiền thu mỗi kỳ, chuỗi thập phân dương
period_days	integer	có	chu kỳ tính phí theo ngày, từ mức tối thiểu của nền tảng (lỗi invalid_period cho biết mức này khi chu kỳ quá ngắn) tới 365

Kết quả là đối tượng plan: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — liên kết t.me bạn gửi cho người dùng để họ đăng ký — và created_at.

Lỗi: 400 unknown_asset, 400 invalid_amount, 409 invalid_period (chu kỳ ngắn hơn mức tối thiểu của nền tảng), 400 invalid_request (thiếu period_days, giá trị không dương hoặc lớn hơn 365; cũng áp dụng khi thiếu name, asset hoặc amount), 503 subs_disabled (tính năng không khả dụng), và 409 too_many_plans (tối đa 50 gói chưa lưu trữ — lưu trữ một gói không dùng trước khi tạo gói khác).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — scope read, không có tham số. Trả về {"items": [plan, …]}, mới nhất trước, mỗi gói kèm thêm một trường: active_subscribers — số gói đăng ký còn hiệu lực (active + grace) trên gói đó.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — scope subscriptions. Một tham số: plan_id. Chặn các lượt đăng ký mới; các gói đăng ký đang có vẫn gia hạn theo đúng điều khoản đã chốt của chúng (muốn dừng thì kết thúc từng cái bằng cancelSubscription). Việc lưu trữ không hoàn tác được qua API. Kết quả là đối tượng plan đã cập nhật với archived: true. Lỗi: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — scope read. Bộ lọc: plan_id, user_id, status (active / grace / cancelled / expired), cùng offset / count (mặc định 100, tối đa 500). Trả về {"items": [subscription, …]}, mới nhất trước.

Đối tượng subscription: subscription_id, plan_id, user_id (Telegram ID của người đăng ký), các điều khoản đã chốt (asset, amount, amount_minor, period_days), status, auto_renew, period_no (số kỳ đã trả tới nay), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user hoặc merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — scope subscriptions. Một tham số: subscription_id. Dừng gia hạn (cancelled_by: "merchant"); kỳ đã trả vẫn dùng được tới current_period_end, trạng thái chuyển sang cancelled ngay lập tức, và người đăng ký được báo. Người dùng bị hủy gói vẫn có thể đăng ký lại sau qua đúng liên kết gói đó nếu gói và ứng dụng vẫn khả dụng. Đăng ký lại sẽ thu tiền ngay và bắt đầu một kỳ mới. Kết quả là đối tượng subscription đã cập nhật.

Lỗi: 404 sub_not_found, 409 sub_not_active (đã hủy hoặc đã hết hạn).