API-Referenz: Überweisungen und Schecks

Die Methoden für Ausschüttungen. Eine Überweisung bewegt Guthaben aus deiner App direkt in die Wallet eines Telegram-Nutzers; ein Scheck ist ein einlösbarer Link, den du im Voraus finanzierst. Die Konventionen (Authentifizierung, Hülle, Beträge, spend_id) stehen auf der Seite Händler-API-Referenz.

transfer

POST /pay/api/transfer – Berechtigung payouts, Limit 30 pro Minute. Wird sofort und atomar abgewickelt; es gibt keinen ausstehenden Zustand.

Parameter	Typ	Pflicht	Bedeutung
user_id	integer	ja	die Telegram-Nutzer-ID des Empfängers. Der Empfänger muss bereits Nutzer der App sein – eine Ausschüttung an eine unbekannte ID führt zu einem Fehler, statt Guthaben stranden zu lassen
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 Ausschüttung
comment	string	nein	bis zu 1024 Zeichen, wird dem Empfänger angezeigt
disable_send_notification	boolean	nein	true = den Empfänger nicht in Telegram benachrichtigen

Das Ergebnis ist das Überweisungsobjekt: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (immer completed), created_at, completed_at.

Fehler: 404 user_not_found (der Empfänger hat die App nie genutzt), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (außerhalb der Grenzen pro Überweisung), 409 insufficient_funds, 404 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 Massenausschüttungen: 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, 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.

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 Ausschüttung über deinen eigenen Schlüssel), dazu offset / count. Liefert {"items": [transfer, …]}, neueste zuerst.

createCheck

POST /pay/api/createCheck – Berechtigung checks, Limit 60 pro Minute. Erstellt einen einmalig einlösbaren Scheck, finanziert aus deinem App-Guthaben; jeder mit dem Link – oder nur der festgelegte Nutzer – kann ihn in seine Wallet einlösen. Der Betrag wird im Moment der Erstellung einbehalten (er wandert in getBalance von available nach onhold).

Parameter	Typ	Pflicht	Bedeutung
asset	string	ja	Asset-Code
amount	string	ja	positiver Dezimalstring
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

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. Eine Einlösung löst den optionalen Webhook check_activated aus.

Fehler: 404 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 nicht eingelösten Scheck und gibt den einbehaltenen Betrag an dein App-Guthaben zurück; liefert true. Fehler: 404 check_not_found, 409 check_not_active (bereits eingelöst 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.