API-Dokumentation

Einführung

Die Payman API ist eine JSON REST API. Alle Anfragen gehen über HTTPS an https://payman33.com/v1.

Authentifizierung

Senden Sie den Zugriffstoken, den Sie bei der Kontoerstellung erhalten haben, als Bearer-Token. Er wird nur einmal angezeigt und kann nicht neu ausgestellt werden. Halten Sie ihn daher geheim und verwenden Sie ihn nie in clientseitigem Code.

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxx

Nachricht senden

POST /messages

Feld	Typ	Beschreibung
`to`	string[]	Empfänger im E.164-Format. Bis zu 10.000 pro Anfrage.
`text`	string	Nachrichtentext: eine SMS, bis zu 160 Zeichen (GSM-7), oder 70, wenn er andere Buchstaben oder Emojis enthält. Längerer Text wird abgelehnt.
`schedule_at`	string	Optionaler ISO-8601-Zeitpunkt für späteren Versand, bis zu 30 Tage im Voraus.
`callback_url`	string	Optionale HTTPS-URL, die Zustellberichte empfängt.

{
  "id": "msg_01J9Z3K8V2",
  "status": "queued",
  "recipients": 1,
  "segments": 1,
  "cost": 0.0063
}

Fügen Sie einen Idempotency-Key-Header hinzu, um gefahrlos zu wiederholen: Derselbe Schlüssel liefert innerhalb von 24 Stunden die ursprüngliche Antwort, statt erneut zu senden.

Nachrichtenstatus

GET /messages/{id}

Status: zuerst queued, dann sent, dann delivered oder failed. Eine geplante Nachricht bleibt scheduled, bis sie versendet wird; stornieren Sie sie (mit Rückerstattung der Kosten) mit POST /messages/{id}/cancel.

Webhooks

Trifft ein Zustellbericht ein, senden wir ihn per POST an Ihre callback_url. Jede Anfrage enthält einen X-Payman-Signature-Header mit dem HMAC-SHA256 des Bodys, berechnet mit Ihrem Webhook-Secret (Dashboard, Tab API), damit Sie die Anfrage verifizieren können. Fehlgeschlagene Zustellungen werden bis zu 3-mal wiederholt.

{
  "id": "msg_01J9Z3K8V2",
  "to": "+14155550123",
  "status": "delivered",
  "delivered_at": "2026-10-09T08:12:03Z"
}

Guthaben

GET /balance

Gibt Ihr aktuelles Guthaben in USDT zurück. Preise sind in USD angegeben; 1 USDT = 1 USD.

Fehler

HTTP	Code	Bedeutung
400	`invalid_request`	Feld fehlt oder ist fehlerhaft.
401	`unauthorized`	API-Schlüssel fehlt oder ist ungültig.
402	`insufficient_balance`	Laden Sie Guthaben auf, um weiter zu senden.
403	`verification_required`	Nicht verifizierte Konten haben das heutige Empfängerlimit erreicht.
404	`not_found`	Keine solche Nachricht in Ihrem Konto.
429	`rate_limited`	Zu viele Anfragen. Versuchen Sie es nach der im `Retry-After`-Header angegebenen Zeit erneut.

Rate Limits

Das Standardlimit beträgt 50 Anfragen pro Sekunde und Konto. Nutzen Sie Massenversand (mehrere Nummern in to) für große Kampagnen. Nicht verifizierte Konten können an bis zu 500 Empfänger pro Tag senden.