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 (deren Dauer die Plattform festlegt) 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. Wird die Zahlung für die Verlängerung während grace eingezogen, beginnt der nächste Zeitraum beim bisherigen current_period_end, nicht zum Zeitpunkt der Zahlung.

Für die Ereignisse im Lebenszyklus gibt es optionale Webhooks: subscription_activated, subscription_charged, subscription_cancelled, subscription_expired. Der Übergang in grace hat keinen Webhook (der Abonnent erhält eine Nachricht in Telegram); frag bei Bedarf getSubscriptions mit status=grace ab. Wird deine App gelöscht, werden ihre Abos bei der nächsten Verlängerung mit cancelled_by: "merchant" beendet.

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 (bei einem zu kurzen Zeitraum in invalid_period angegeben) 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: 400 unknown_asset, 400 invalid_amount, 409 invalid_period (kürzer als das Plattformminimum), 400 invalid_request (period_days fehlt, ist nicht positiv oder liegt über 365; auch bei fehlendem name, asset oder amount), 503 subs_disabled (die Funktion ist nicht verfügbar) und 409 too_many_plans (höchstens 50 nicht archivierte Pläne – archiviere einen ungenutzten Plan, bevor du einen neuen erstellst).

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 (Standard 100, 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. Er kann über denselben Link erneut zustimmen, solange Plan und App verfügbar bleiben. Dabei wird sofort abgebucht und ein neuer Zeitraum beginnt. Das Ergebnis ist das aktualisierte Abo-Objekt.

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