API-Referenz: Abos

Wiederkehrende Abrechnung – eine Erweiterung gegenüber Crypto Bot. Du erstellst einen Plan (Betrag + Zeitraum), schickst Nutzern seinen Zustimmungslink, und die Plattform bucht ihnen in jedem Zeitraum den Betrag vom Guthaben ihrer Wallet ab und schreibt ihn abzüglich der Gebühr deinem App-Guthaben gut. Die Konventionen stehen auf der Seite Händler-API-Referenz.

Das Modell

Ein Plan ist eine unveränderliche Momentaufnahme: Das Mandat, dem ein Nutzer zustimmt, lautet auf genau diesen Betrag pro genau diesem Zeitraum. Um den Preis zu ändern, erstellst du einen neuen Plan und archivierst den alten – bestehende Abonnenten verlängern weiter zu den Bedingungen, denen sie zugestimmt haben. Der erste Zeitraum wird bei der Zustimmung abgebucht.

Verlängerungen werden am Ende jedes Zeitraums automatisch abgerechnet. Schlägt eine Verlängerung fehl (unzureichendes Guthaben, eingeschränktes Konto), geht das Abo in grace über und die Plattform versucht es innerhalb der Kulanzfrist (derzeit 48 Stunden) stündlich erneut; lässt sich dann immer noch nichts einziehen, wird das Abo expired. Händler lesen current_period_end als Stichtag für den Zugang.

Jedes Ereignis im Lebenszyklus hat einen optionalen Webhook: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired.

createSubscriptionPlan

POST /pay/api/createSubscriptionPlan – Berechtigung subscriptions.

Parameter	Typ	Pflicht	Bedeutung
name	string	ja	1–64 Zeichen, wird dem Abonnenten angezeigt
asset	string	ja	Asset-Code
amount	string	ja	die Abbuchung pro Zeitraum, positiver Dezimalstring
period_days	integer	ja	Abrechnungszeitraum in Tagen, vom Minimum der Plattform (derzeit 7) bis 365

Das Ergebnis ist das Planobjekt: plan_id, name, asset, amount, amount_minor, period_days, archived, mini_app_subscribe_url – der t.me-Link, den du Nutzern zur Zustimmung schickst – und created_at.

Fehler: 404 unknown_asset, 400 invalid_amount, 409 invalid_period, 503 subs_disabled (die Funktion ist plattformseitig abgeschaltet).

getSubscriptionPlans

GET /pay/api/getSubscriptionPlans – Berechtigung read, keine Parameter. Liefert {"items": [plan, …]}, neueste zuerst, jeweils mit einem zusätzlichen Feld: active_subscribers – die Anzahl der laufenden Abos (active + grace) für diesen Plan.

archiveSubscriptionPlan

POST /pay/api/archiveSubscriptionPlan – Berechtigung subscriptions. Ein Parameter: plan_id. Stoppt neue Zustimmungen; bestehende Abos verlängern sich weiter auf Basis ihrer Momentaufnahme (beende sie einzeln mit cancelSubscription). Das Archivieren lässt sich über die API nicht rückgängig machen. Das Ergebnis ist das aktualisierte Planobjekt mit archived: true. Fehler: 404 plan_not_found.

getSubscriptions

GET /pay/api/getSubscriptions – Berechtigung read. Filter: plan_id, user_id, status (active / grace / cancelled / expired), dazu offset / count (max. 500). Liefert {"items": [subscription, …]}, neueste zuerst.

Das Abo-Objekt: subscription_id, plan_id, user_id (die Telegram-ID des Abonnenten), die Bedingungen der Momentaufnahme (asset, amount, amount_minor, period_days), status, auto_renew, period_no (bisher bezahlte Zeiträume), current_period_start / current_period_end, created_at, cancelled_at, cancelled_by (user oder merchant), expired_at.

cancelSubscription

POST /pay/api/cancelSubscription – Berechtigung subscriptions. Ein Parameter: subscription_id. Stoppt die Verlängerungen (cancelled_by: "merchant"); der bezahlte Zeitraum bleibt bis current_period_end nutzbar, der Status wechselt sofort auf cancelled, und der Abonnent wird benachrichtigt. Ein gekündigter Abonnent kann später über denselben Plan-Link erneut zustimmen. Das Ergebnis ist das aktualisierte Abo-Objekt.

Fehler: 404 sub_not_found, 409 sub_not_active (bereits gekündigt oder abgelaufen).