Dokumentation

Freika ist eine Zahlungsplattform für das Präsenzgeschäft mit einer REST-API, Terminals und Zahlungslinks. Diese Dokumentation zeigt dir den Weg von der Registrierung bis zur ersten Zahlung in der Kasse.

So ist die Dokumentation aufgebaut

• Erste Schritte: Konto, Sandbox, erste Zahlung per API in rund zehn Minuten.
• Konzepte: Organisationen, Standorte, der Lebenszyklus einer Zahlung, Auszahlungen.
• Vor Ort: Terminal koppeln, Kasse anbinden, Trinkgeld und Belege.
• Online: Zahlungslinks, Zahlungsseite, Rückerstattungen.
• Webhooks: Ereignisse empfangen, Signaturen prüfen, Wiederholungen.
• API-Referenz: alle Endpunkte, aus der OpenAPI-Spezifikation erzeugt.

Grundsätze der API

• Beträge sind immer Ganzzahlen in Rappen: 2450 steht für CHF 24.50.
• Jede Ressource hat eine ID mit Präfix: pay_, ref_, lnk_, trm_, loc_, whk_.
• Schreibende Aufrufe nimmst du mit dem Header Idempotency-Key gegen doppelte Ausführung ab.
• Test- und Live-Umgebung unterscheiden sich nur im Schlüssel: fk_test_... und fk_live_....
• Fehler kommen als Problem Details (RFC 9457) mit stabilem code.

Schnellstart

curl https://api.freika.com/v1/payments \
  -H "Authorization: Bearer fk_test_..." \
  -H "Idempotency-Key: 5f8c2b1e" \
  -d amount=2450 \
  -d currency=CHF \
  -d channel=online \
  -d success_url=https://deinshop.ch/danke

Die Antwort enthält eine checkout_url. Leite deine Kundschaft dorthin, den Rest erledigt die Zahlungsseite. Der Status kommt per Webhook zurück.