1. Autorisierung
Ein Plattformadministrator legt Ihren Partner an und stellt einen widerrufbaren Test-API-Schlüssel aus. Der Händler autorisiert Ihren Partner ausdrücklich. Bewahren Sie den Schlüssel ausschließlich in Ihrem Server auf.
2. Zahlungsauftrag erstellen
POST /api/v1/payment-sessions
Authorization: Bearer pl_test_…
Idempotency-Key: eindeutige-verkaufs-id
Content-Type: application/json
{"merchantId":"UUID","amount":2490,"currency":"eur","reference":"BON-42"}3. PayLink öffnen
Fordern Sie über POST /payment-sessions/{id}/launch einen kurzlebigen Link an. Der Händler öffnet diesen Link auf seinem registrierten Gerät. Der Link enthält keine Beträge und keine API-Schlüssel.
4. Ergebnis bestätigen
Lesen Sie GET /payment-sessions/{id} oder prüfen Sie den signierten Webhook. Ein Rücksprung in Ihre Kasse ist keine Zahlungsbestätigung. Nur succeeded erlaubt den Abschluss des Verkaufs. Bei unknown behalten Sie dieselbe Session bei.
Webhook-Prüfung
Prüfen Sie HMAC-SHA256 über timestamp + Punkt + unveränderten Request-Body. Der Header PayLink-Signature enthält t und v1. Akzeptieren Sie maximal fünf Minuten Zeitabweichung und deduplizieren Sie die Ereignis-ID. Zustellungen werden mit exponentiellem Abstand bis zu zehn Mal versucht.
Fehlercodes
- IDEMPOTENCY_CONFLICT: Gleicher Schlüssel mit abweichendem Auftrag.
- MERCHANT_NOT_AUTHORIZED: Händlerfreigabe fehlt oder wurde widerrufen.
- RECONCILE_EXISTING_PAYMENT: Bestehende Zahlung zuerst abgleichen.
- LAUNCH_EXPIRED: Neuen Startlink anfordern.
- RATE_LIMITED: Anfrage später mit demselben Idempotenzschlüssel wiederholen.
Interaktive OpenAPI-Dokumentation: Backend-Pfad /api/docs. Vollständige Flutter- und Windows-Beispiele liegen im Verzeichnis examples.
Sandbox: ausschließlich Testzahlungen, kein Live-Modus.