Vai al contenuto
Konzepte

Zahlungen

Lebenszyklus, Kanäle, Methoden, Idempotenz und Fehler.

Lebenszyklus

pending ──▶ authorized ──▶ succeeded ──▶ refunded / partially_refunded
   │             │
   ▼             ▼
 failed       canceled
  • pending: erstellt, wartet auf die Kundschaft.
  • authorized: Betrag reserviert (nur mit capture_method: manual, online oder am Terminal).
  • succeeded: bezahlt. Fliesst in die nächste Auszahlung.
  • failed: abgelehnt oder Fehler. Das Feld failure_code sagt warum.
  • canceled: von dir oder der Kundschaft abgebrochen.
  • refunded, partially_refunded: ganz oder teilweise zurückerstattet.

Reservieren und später abschliessen

Mit capture_method: manual reservierst du einen Betrag zuerst und belastest erst, wenn der Endbetrag feststeht. Das passt etwa für Ladestationen, Mietgeräte oder Hotels. Das geht online (POST /v1/payments) und am Terminal (POST /v1/terminals/{id}/payments).

Sobald die Zahlung authorized ist, schliesst du sie ab:

curl https://api.freika.com/v1/payments/pay_3f9a1c0b2d4e5f60718a/capture \
  -H "Authorization: Bearer $FREIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ladung-4711-abschluss" \
  -d '{ "amount": 1240 }'
{
  "id": "pay_3f9a1c0b2d4e5f60718a",
  "status": "succeeded",
  "capture_method": "manual",
  "amount": 5000,
  "amount_captured": 1240,
  "amount_refunded": 0
}
  • Ohne amount (oder ohne Körper) wird der ganze reservierte Betrag belastet.
  • Mit amount wird nur dieser Teil belastet, höchstens der reservierte Betrag. Den Rest geben wir sofort frei. Ein höherer Betrag ergibt 422 invalid_request mit dem Feld available.
  • Abschliessen geht einmal. Danach gelten Rückerstattungen.
  • Wird nichts gebraucht, stornierst du die Reservation mit POST /v1/payments/{id}/cancel.

amount bleibt der reservierte Betrag. Was tatsächlich belastet wurde, steht in amount_captured (0, solange nichts belastet ist).

Kanäle

channelBeschreibung
terminalZahlung an einem gekoppelten Terminal
softposZahlung in der Freika-App auf einem Android-Gerät (ab November 2026)
onlineZahlungsseite, per API erstellt
payment_linkÜber einen Zahlungslink oder QR-Code

Zahlungsmethoden

twint, visa, mastercard, postfinance_pay, apple_pay, google_pay, american_express (auf Anfrage). Die Methode steht nach der Zahlung im Feld method, bei Karten zusätzlich card_brand und last4.

Welche Methoden aktiv sind, stellst du pro Kanal unter Einstellungen → Zahlungsmethoden ein. Mit allowed_methods schränkst du sie pro Zahlung weiter ein.

Idempotenz

Sende bei jedem schreibenden Aufruf einen Idempotency-Key (beliebige Zeichenkette, z. B. deine Bestellnummer). Wiederholungen mit gleichem Schlüssel und gleichem Inhalt geben die ursprüngliche Antwort zurück, 24 Stunden lang. Ein gleicher Schlüssel mit anderem Inhalt ergibt 409 idempotency_conflict.

Fehler

Fehler kommen als Problem Details:

{
  "type": "https://www.freika.com/docs/errors/validation",
  "title": "Ungültige Anfrage",
  "status": 422,
  "code": "validation_error",
  "errors": [{ "field": "amount", "message": "muss grösser als 0 sein" }]
}

Wichtige Codes: authentication_failed (401), permission_denied (403), not_found (404), idempotency_conflict (409), validation_error (422), rate_limited (429), terminal_busy (409), terminal_offline (409).

Limits

Standardmässig 600 Anfragen pro Minute und Schlüssel. Die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset zeigen den Stand. Brauchst du mehr, schreib an developer@freika.com.