API-Referenz: Überweisungen und Schecks

Mit diesen Methoden zahlst du Guthaben aus deiner App aus. Eine Überweisung sendet es in die Wallet eines Telegram-Nutzers oder hält es zurück, bis ein neuer Empfänger den Bot öffnet. Ein Scheck ist ein einlösbarer Link, dessen Betrag du im Voraus bereitstellst. Die allgemeinen Regeln (Authentifizierung, Antwortformat, Beträge, spend_id) stehen auf der Seite Händler-API-Referenz.

Alle drei Methoden, mit denen Geld die App verlässt, unterliegen dem Auszahlungsmodus der App: Eine neue App darf von Anfang an jeden bezahlen; hat der Inhaber den Modus enger gefasst, lassen sich nur Empfänger aus der Liste bezahlen (403 recipient_not_allowed) oder niemand (403 payouts_disabled). Den Modus legt der Inhaber in der Mini App fest; über die API lässt er sich nicht ändern. Wofür du Auszahlungen verwenden darfst, legen die Bedingungen der Händler-API fest.

transfer

POST /pay/api/transfer – Berechtigung payouts, Limit 30 pro Minute. Ein bekannter Empfänger erhält die Auszahlung sofort. Bei einem unbekannten username entsteht eine Überweisung mit dem Status pending: Der Betrag wird zurückgehalten, bis der Empfänger den Bot mit diesem Nutzernamen öffnet. Nicht eingelöste Beträge werden nach Ablauf der 30-tägigen Frist (expires_at) an das App-Guthaben zurückgegeben. Prüfe vor der Verbuchung, ob die Rückgabe durch status: "returned" bestätigt ist. Leite invite_url selbst weiter – der Bot kann niemanden anschreiben, der ihn noch nie gestartet hat. Der endgültige Status ist completed oder returned. Abonniere die Webhooks transfer_completed und transfer_returned oder frage den Status über getTransfers ab.

Parameter	Typ	Pflicht	Bedeutung
user_id	integer	genau eines von user_id / username	Telegram-Nutzer-ID des Empfängers; er muss die App bereits nutzen
username	string	genau eines von user_id / username	Nutzername des Empfängers mit oder ohne @; ein unbekannter Name erzeugt eine ausstehende Auszahlung
asset	string	ja	Asset-Code
amount	string	ja	positiver Dezimalstring; zusätzlich begrenzt durch das Minimum und das Maximum der Plattform pro Überweisung (ein geschätzter US-Dollar-Gegenwert zu aktuellen Kursen)
spend_id	string	ja	Idempotenzschlüssel, 1–64 Zeichen, eindeutig pro Auszahlung
comment	string	nein	bis zu 1024 Zeichen, wird dem Empfänger angezeigt
disable_send_notification	boolean	nein	true = bei sofortiger Auszahlung keine Telegram-Nachricht an den Empfänger senden; beim späteren Einlösen einer ausstehenden Auszahlung wird er immer benachrichtigt

Das Ergebnis ist das Überweisungsobjekt: transfer_id, hash, user_id, recipient_username, asset, amount, amount_minor, spend_id, comment, status (pending / completed / returned), created_at, completed_at, expires_at, invite_url. Solange die Überweisung auf einen neuen Empfänger wartet, kann user_id null sein. Bis zum Abschluss ist completed_at null.

Fehler: 403 payouts_disabled / 403 recipient_not_allowed (der Auszahlungsmodus), 404 user_not_found (die ID ist unbekannt oder der Empfänger nicht verfügbar), 400 invalid_recipient (ungültiger Nutzername des Empfängers), 400 amount_too_small / 400 amount_too_big (außerhalb der Grenzen pro Überweisung), 409 insufficient_funds, 400 unknown_asset, 400 invalid_amount und das spend_id-Paar 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch – Berechtigung payouts, Limit 10 pro Minute. Eine Erweiterung für Massenauszahlungen: bis zu 100 Überweisungen in einem Aufruf.

Ein Parameter: items – ein Array, in dem jedes Element ein vollständiger Parametersatz von transfer ist (user_id oder username, asset, amount, spend_id, optional comment und disable_send_notification). Die spend_ids müssen innerhalb des Stapels eindeutig sein, sonst schlägt der gesamte Aufruf mit 400 duplicate_spend_id fehl, bevor irgendetwas ausgeführt wird. Auch eine ungültige Elementstruktur, der Auszahlungsmodus der App oder ihr Tageslimit können die gesamte Anfrage vor jeder Auszahlung ablehnen. Bei angenommener Anfrage stehen die Ergebnisse in result.items.

Die Elemente werden unabhängig und der Reihe nach abgewickelt – ein fehlgeschlagenes Element macht die anderen nie rückgängig. Der Aufruf liefert HTTP 200 mit ok: true, auch wenn einzelne Elemente fehlgeschlagen sind – prüfe deshalb immer jedes Element:

• Erfolg: {"ok": true, "spend_id": "…", "result": <transfer object>}
• Fehlschlag: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} mit denselben Fehlernamen wie bei einer einzelnen transfer.

Stapelelemente teilen sich den Namensraum für Idempotenz mit einzelnen Überweisungen: Den ganzen Stapel zu wiederholen – oder ein Element erneut als einzelne transfer mit derselben spend_id zu senden – gibt das Ergebnis wieder, statt zweimal zu zahlen.

getTransfers

GET /pay/api/getTransfers – Berechtigung read. Filter: asset, transfer_ids (kommagetrennt), spend_id (exakte Übereinstimmung – finde eine Auszahlung über deinen eigenen Schlüssel), status (pending / completed / returned), dazu offset / count. Liefert {"items": [transfer, …]}, neueste zuerst.

createCheck

POST /pay/api/createCheck – Berechtigung checks, Limit 60 pro Minute. Erstellt standardmäßig einen einmalig einlösbaren Scheck aus deinem App-Guthaben. Jeder mit dem Link oder nur der festgelegte Nutzer kann ihn einlösen. Die Erweiterung recipients erstellt eine Empfängerliste mit einem eigenen Betrag pro Person. Die Summe wird bei der Erstellung einbehalten (in getBalance wechselt sie von available zu onhold). Für Schecks gelten dieselben Betrags- und Tageslimits wie für Überweisungen.

Parameter	Typ	Pflicht	Bedeutung
asset	string	ja	Asset-Code
amount	string	außer wenn recipients gesetzt ist	positiver Dezimalstring; mit recipients wird die Summe aus der Liste berechnet
pin_to_user_id	integer	nein	nur diese Telegram-Nutzer-ID darf einlösen
pin_to_username	string	nein	nur dieser @username darf einlösen (das @ ist optional; wird ignoriert, wenn auch pin_to_user_id gesetzt ist). Der Username muss zu einem bestehenden Nutzer der App gehören
spend_id	string	nein	Idempotenzschlüssel (Erweiterung) – nutze einen
recipients	array	nein	Erweiterung: 1–100 Einträge mit jeweils user_id oder username und einem positiven Dezimalstring amount. Nicht mit einem festgelegten Nutzer kombinierbar
password	string	nein	Erweiterung: Passwort zum Einlösen; bis zu 64 Zeichen
expires_in	integer	nein	Erweiterung: Laufzeit in Sekunden; weggelassen oder 0 = kein Ablauf

Das Ergebnis ist das Scheckobjekt: check_id, hash, asset, amount, amount_minor, bot_check_url (der t.me-Link zum Einlösen), status (active / activated), pin_to_user_id, created_at, activated_at, expires_at und recipients (bei einem gewöhnlichen Scheck null; sonst pro Eintrag user_id, username, amount, amount_minor, claimed_at). Jede Einlösung löst den optionalen Webhook check_activated aus; bei einer Empfängerliste enthält er auch activated_slot. Beim Ablauf wird der nicht eingelöste Rest zurückgegeben. Läuft ein Scheck mit Empfängerliste ab, kann check_expired gesendet werden.

Die aktuelle Antwort gibt für jeden nicht vollständig eingelösten Scheck status: "active" zurück, auch wenn er abgelaufen ist. Prüfe deshalb zusätzlich expires_at; active allein beweist nicht, dass der Link noch einlösbar ist.

Fehler: 403 payouts_disabled / 403 recipient_not_allowed (der Auszahlungsmodus – im Modus allowlist muss jeder festgelegte oder namentlich genannte Empfänger auf der Liste stehen), 400 unknown_asset, 400 invalid_amount, 404 user_not_found (der festgelegte Username passt zu niemandem), 409 insufficient_funds und das spend_id-Paar.

deleteCheck

POST /pay/api/deleteCheck – Berechtigung checks. Ein Parameter: check_id. Storniert einen aktiven Scheck und gibt den nicht eingelösten Rest an dein App-Guthaben zurück; liefert true. Fehler: 404 check_not_found, 409 check_not_active (vollständig eingelöst, abgelaufen oder gelöscht).

getChecks

GET /pay/api/getChecks – Berechtigung read. Filter: asset, check_ids (kommagetrennt), status (active / activated), dazu offset / count. Liefert {"items": [check, …]}, neueste zuerst; gelöschte Schecks werden nie zurückgegeben.