Abonnements und automatische Zahlungen
Ein Händler kann einen Heth.me-Nutzer um die Zustimmung zu wiederkehrenden Zahlungen bitten. Der Zahler prüft und unterschreibt die Bedingungen mit seinem regulär entsperrten HethWallet. Ein separates E-Mail-Konto oder eine Anmeldung im Customer Portal ist nicht erforderlich. Die Zahlungen belasten das Heth-Kontoguthaben in der vereinbarten Währung und im vereinbarten Netzwerk.
Für Zahler
- Öffnen Sie Settings → Subscriptions and autopay. Neue Anfragen stehen getrennt von bestehenden Abonnements.
- Prüfen Sie Händler, Betrag je Zahlung, Währung/Netzwerk und Abrechnungsintervall. Der Bestätigungslink öffnet denselben Bildschirm. Ein gesperrtes Wallet fragt nach der üblichen PIN und kehrt zur Anfrage zurück.
- Wählen Sie Enable subscription oder Reject. Das Öffnen eines Links oder der Empfang einer Benachrichtigung erteilt keine Zustimmung.
- Nach der Zustimmung wird die erste Zahlung geplant. Die Liste zeigt Betrag, Intervall und nächsten Zahlungstermin; bei einem erneuten Zahlungsversuch dessen nächsten Zeitpunkt.
- Widerrufen Sie das Abonnement, um künftige Abbuchungen zu stoppen. Bereits ausgeführte Zahlungen werden dadurch nicht erstattet.
Die Bestätigung speichert die Zustimmung und plant eine Zahlung; sie bedeutet nicht, dass die Zahlung erfolgreich war. Prüfen Sie den Transaktionsstatus. Zum Ausführungszeitpunkt muss ausreichend Guthaben vorhanden sein.
Benachrichtigung über neue Anfragen
Bei einem erkannten Zahler sendet der Server eine Push-Benachrichtigung zur Abonnementanfrage an registrierte Geräte mit dem Link /subscriptions/confirm/<request_id>?env=<env>. Ein Eintrag wird auch unter der Benachrichtigungsglocke gespeichert, selbst wenn kein Gerät den Push empfangen kann. Offene Anfragen bleiben unter Settings → Subscriptions and autopay verfügbar.
Installierte PWAs verwenden Web-Push. Heth.me für iOS und Android verwendet ab Version 1.0.0 (Build 5) Systembenachrichtigungen. Aktivieren Sie Benachrichtigungen im Wallet und erlauben Sie diese in den Geräteeinstellungen. Durch Antippen einer Abonnementanfrage öffnet sich deren Bestätigungsseite; ein gesperrtes Wallet fragt zuerst nach der üblichen PIN oder einem verfügbaren Passkey. Der Empfang oder das Öffnen einer Benachrichtigung bestätigt das Abonnement nicht. Öffnen Sie bei fehlender Benachrichtigung die Liste offener Anfragen oder den Bestätigungslink des Händlers.
Für Händler
Öffnen Sie in HethWallet Business → Subscriptions and autopay. Geben Sie Wallet-Adresse, @username oder Heth-Kartennummer des Zahlers, Namen des Abonnements, Betrag je Zahlung, Währung/Netzwerk und Intervall ein. Senden Sie die Anfrage und kopieren Sie den Bestätigungslink. Hier können Sie eigene Anfragen einsehen und noch offene Anfragen stornieren.
Der Betreiber muss Heth-Abonnements für die Organisation aktivieren und einen funktionierenden Zahlungsweg konfigurieren. Die Erstellung einer Anfrage erlaubt keine Abbuchung.
Anfrage über die API erstellen
Verwenden Sie den API-Schlüssel des Händlers oder seine reguläre Partner-Bearer-Sitzung. Auf app.heth.me wird die Organisation anhand des Hosts ermittelt. Ein schreibgeschützter Schlüssel kann Anfragen weder erstellen noch stornieren.
curl -X POST 'https://app.heth.me/api/v1/heth/subscription-requests' \
-H "x-api-key: $HETH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"request_id": "b56b2c66-4ae5-4cb9-92ea-7a3297b72b55",
"payer": "@alice",
"description": "Monthly membership",
"amount": "1000000",
"currency": "USDT",
"network": "ETH",
"interval": "monthly",
"period": 1,
"env": "prod"
}'
| Feld | Beschreibung | Typ | Beispiel |
|---|---|---|---|
request_id | Eindeutige idempotente UUID. Bei Wiederholung derselben Anfrage mit identischen Bedingungen wiederverwenden. | String | b56b2c66-4ae5-4cb9-92ea-7a3297b72b55 |
payer | Wallet-Adresse, Benutzername oder Heth-Kartennummer. | String | @alice |
description | Name des Abonnements, 1–250 Zeichen ohne Zeilenumbrüche. | String | Monthly membership |
amount | Positive Ganzzahl in kleinsten Token-Einheiten. Bei USDT mit 6 Dezimalstellen bedeutet 1000000 genau 1 USDT. | String | 1000000 |
currency, network | Aktiviertes Token/Netzwerk-Paar der gewählten Umgebung. Netzwerke: ETH, TRX, BASE. | String | USDT, ETH |
interval | daily, weekly, monthly oder yearly. | String | monthly |
period | Anzahl der Intervalle, 1–365; Standardwert 1. | Number | 1 |
env | prod (Standard). Beim Öffnen und Bestätigen der Anfrage beibehalten. | String | prod |
HTTP 201 liefert die Anfrage direkt zurück, darunter id, status, amount_decimals, confirm_url, expires_at, subscription_id und next_charge_at. Anfragen verfallen nach sieben Tagen. Die erfolgreiche Erstellung verrät nicht, ob der angegebene Zahler existiert; nur der tatsächliche Empfänger kann die Anfrage lesen und bestätigen.
API-Operationen
Alle folgenden Pfade beginnen mit /api/v1. Händleroperationen erfordern seinen API-Schlüssel oder seine Partner-Bearer-Sitzung.
| Methode und Pfad | Zweck |
|---|---|
POST /heth/subscription-requests | Anfrage erstellen. |
GET /heth/subscription-requests?env=prod&limit=50 | Händleranfragen in data und total auflisten. |
POST /heth/subscription-requests/:id/cancel | Offene Anfrage stornieren; Body {"env":"prod"}. |
Lassen Sie page für die erste Seite weg. Verwenden Sie page=1 für die nächste Seite und erhöhen Sie danach den Wert; limit bestimmt die Seitengröße.
Wallet-Operationen erfordern die reguläre Wallet-Bearer-Sitzung des Zahlers. Der API-Schlüssel des Händlers kann nicht für den Zahler zustimmen.
| Methode und Pfad | Zweck |
|---|---|
GET /heth/subscriptions?env=prod&limit=50 | Eigene Abonnements in data/total, offene Anfragen in requests/requests_total. |
GET /heth/subscription-requests/:id?env=prod | Empfangene Anfrage und kanonische Signaturnachricht message lesen. |
POST /heth/subscription-requests/:id/confirm | Nach Prüfung der genauen Bedingungen mit {"signature":"<wallet signature>","env":"prod"} bestätigen. |
POST /heth/subscription-requests/:id/reject | Ablehnen; Body {"env":"prod"}. |
POST /heth/subscriptions/:id/revoke-mandate | Künftige Abbuchungen stoppen; Body {"env":"prod"}. |
Die Signatur bindet Händler, Zahler, Organisation, Umgebung, Beschreibung, Betrag und Dezimalstellen, Währung/Netzwerk, Intervall und Periode, erste Zahlungsregel, Nonce und Ablaufdatum. Neue Bedingungen erfordern eine neue Anfrage und Zustimmung. Wiederholte Bestätigungen oder geplante Zahlungen können denselben Zeitraum nicht doppelt belasten. API-Zeitstempel ohne Zeitzone sind UTC; die App zeigt die lokale Gerätezeit.
Status und Fehler
Anfragestatus: pending, signed, rejected, expired. Eine genehmigte Anfrage enthält eine subscription_id. Verfolgen Sie den tatsächlichen Zahlungsabschluss über die Transaktions-API und konfigurierte Webhooks.
401 bedeutet fehlende/ungültige Authentifizierung; 403 bedeutet deaktivierte Abonnements oder einen schreibgeschützten API-Schlüssel. Eine nicht zugängliche Anfrage liefert 404. 422 kennzeichnet ungültige Bedingungen, eine wiederverwendete UUID mit anderen Bedingungen, eine ungültige Signatur oder eine abgelaufene/geschlossene Anfrage. Ein Händler kann unterschriebene Bedingungen eines aktiven Abonnements nicht ohne erneute Zustimmung ändern.