Referensi API: langganan

Penagihan berulang — ekstensi di luar Crypto Bot. Kamu membuat paket (jumlah + periode), mengirim link persetujuannya ke pengguna, lalu platform menagih mereka dari saldo dompetnya tiap periode dan menambahkan hasilnya ke saldo aplikasimu setelah dipotong biaya. Konvensi umumnya ada di halaman Referensi Merchant API.

Model penagihan

Paket adalah snapshot yang tidak bisa diubah: persetujuan pengguna berlaku untuk jumlah dan periode yang tercantum dalam paket. Untuk mengubah harga, buat paket baru lalu arsipkan yang lama — langganan yang sudah berjalan tetap diperpanjang dengan ketentuan yang mereka setujui. Periode pertama ditagih saat persetujuan.

Perpanjangan ditagih otomatis di akhir tiap periode. Kalau perpanjangan gagal (saldo tidak cukup, akun dibatasi), langganannya masuk status grace dan platform mencoba lagi tiap jam selama masa tenggang (durasinya ditentukan platform); kalau tetap tidak tertagih, langganannya jadi expired. Di sisi merchant, current_period_end adalah batas akhir aksesnya.

Setiap event siklus hidup punya webhook opsional yang perlu kamu aktifkan dulu: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan — scope subscriptions.

Parameter	Tipe	Wajib	Keterangan
name	string	ya	1–64 karakter, ditampilkan ke pelanggan
asset	string	ya	kode aset
amount	string	ya	jumlah yang ditagih tiap periode, string desimal positif
period_days	integer	ya	periode penagihan dalam hari, dari minimum platform (diberitahukan melalui invalid_period jika periodenya terlalu singkat) sampai 365

Hasilnya adalah objek paket: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url — link t.me yang kamu kirim ke pengguna untuk disetujui — dan created_at.

Error: 400 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (fitur tidak tersedia), dan 409 too_many_plans (arsipkan paket yang tidak digunakan sebelum membuat yang baru).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans — scope read, tanpa parameter. Mengembalikan {"items": [plan, …]}, diurutkan dari yang terbaru, masing-masing dengan satu field tambahan: active_subscribers — banyaknya langganan yang masih berjalan (active + grace) di paket itu.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan — scope subscriptions. Satu parameter: plan_id. Menghentikan persetujuan baru; langganan yang sudah ada tetap diperpanjang dengan snapshot-nya (hentikan satu per satu pakai cancelSubscription). Pengarsipan tidak bisa dibatalkan lewat API. Hasilnya adalah objek paket terbaru dengan archived: true. Error: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions — scope read. Filter: plan_id, user_id, status (active / grace / cancelled / expired), plus offset / count (maksimal 500). Mengembalikan {"items": [subscription, …]}, diurutkan dari yang terbaru.

Objek langganan: subscription_id, plan_id, user_id (ID Telegram pelanggan), ketentuan snapshot-nya (asset, amount, amount_minor, period_days), status, auto_renew, period_no (periode yang sudah dibayar sejauh ini), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user atau merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription — scope subscriptions. Satu parameter: subscription_id. Menghentikan perpanjangan (cancelled_by: "merchant"); periode yang sudah dibayar tetap bisa dipakai sampai current_period_end, statusnya langsung berubah jadi cancelled, dan pelanggannya diberi tahu. Pelanggan yang langganannya dibatalkan bisa menyetujui lagi lewat link yang sama selama paket dan aplikasi tetap tersedia. Persetujuan ulang langsung menagih pembayaran dan memulai periode baru. Hasilnya adalah objek langganan terbaru.

Error: 404 sub_not_found, 409 sub_not_active (sudah dibatalkan atau berakhir).