Authentifizierung

Alle /v1/*-Routen authentifizieren sich per API-Schlüssel:

Authorization: Bearer sk_live_...

X-API-Key: sk_live_... wird gleichwertig akzeptiert, für HTTP-Clients, die Authorization für anderes reservieren.

Test- und Live-Schlüssel

Präfix	Modus	Echtes Geld
sk_test_…	Test	Nein — der gesamte Code läuft (Routing, Gebühren, Prüfungen), kein Geld bewegt sich
sk_live_…	Produktion	Ja

Im Testmodus erzeugte Objekte tragen is_test: true und erscheinen nie in Ihren Produktivberichten.

Der Testmodus deckt die Sofortzahlung nicht ab. Die PI- und Tontine-Familien lehnen Testschlüssel ab: sie sprechen mit einem externen System, für das es bei uns keine Sandbox gibt.

Das Geheimnis existiert genau einmal

Beim Anlegen (oder Rotieren) eines Schlüssels wird das Geheimnis einmal angezeigt. Serverseitig wird nur sein HMAC-Abdruck gespeichert: niemand — auch der Support nicht — kann es Ihnen zurückgeben. Verloren? Rotieren Sie: der alte Schlüssel wird widerrufen, der neue einmal angezeigt.

Warum antwortet mein Schlüssel client_inactive?

Ein Schlüssel wird sofort bei der Registrierung ausgegeben, lässt aber keinen Aufruf zu, solange das Konto nicht geprüft ist (KYB genehmigt, Konto im Status active). Das ist die Compliance-Tür: sie öffnet sich mit der Freigabe und schließt sich bei einer Sperre sofort wieder — derselbe Schlüssel, ohne jede weitere Änderung.

Geltungsbereiche

Jeder Schlüssel trägt Geltungsbereiche, und eine Operation außerhalb antwortet 403 insufficient_scope: einziehen, auszahlen, erstatten, lesen, Webhooks verwalten. Geben Sie den engsten Schlüssel aus, der die Arbeit erledigt — ein Leseschlüssel für Ihre Berichte muss nicht auszahlen können.

Idempotenz

Bei Erzeugungen (POST /v1/payments, POST /v1/payouts, POST /v1/refunds …) senden Sie einen Idempotency-Key Ihrer Wahl — zum Beispiel Ihre Bestellreferenz. Eine Wiederholung mit demselben Schlüssel gibt die ursprüngliche Operation zurück, nie ein Duplikat; derselbe Schlüssel mit anderem Inhalt wird mit 409 abgelehnt.

Ein Schlüssel je Operation, nie je übergeordnetem Objekt. Ein Einzug kann in mehreren Schritten erstattet werden: ein Idempotenzschlüssel mit der Kennung der Zahlung ließe die zweite Teilerstattung wie eine Wiederholung der ersten aussehen. Erfolg beim Händler, Kunde nicht erstattet.

Ratenbegrenzung

300 Anfragen pro Minute und Schlüssel. Darüber 429 mit einem Retry-After-Header — halten Sie ihn ein, statt sofort neu zu versuchen.

Gute Praxis

• Ein Schlüssel je Umgebung (Produktion, Staging), nie zwischen Diensten geteilt.
• Das Geheimnis lebt in einem Secret-Manager, nie im Code und nie im Frontend.
• Beim geringsten Zweifel sofort rotieren — ohne Unterbrechung, wenn Sie den neuen Schlüssel ausrollen, bevor Sie den alten widerrufen.