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ý.

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. Hãy đọc current_period_end như hạn chót của quyền truy cập.

Mỗi sự kiện trong vòng đời đều có webhook riêng, loại cần bật thủ công: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

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, 503 subs_disabled (tính năng không khả dụng) và 409 too_many_plans (lưu trữ một gói không dùng trước khi tạo thêm).

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 (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).