Zahlungen

Lebenszyklus

pending ──▶ authorized ──▶ succeeded ──▶ refunded / partially_refunded
   │             │
   ▼             ▼
 failed       canceled

• pending: erstellt, wartet auf die Kundschaft.
• authorized: Betrag reserviert (nur bei Kartenzahlungen mit getrennter Erfassung).
• 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.

Kanäle

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.