Auf dieser Seite
API-Schlüssel
Payment- und Payout-Schlüssel erstellen, ihre Geltungsbereiche und Präfixe verstehen, Zugangsdaten sicher wechseln und Test von Live trennen.
Paymos gibt je Umgebung zwei Schlüsselarten aus, jede auf einen festen Satz von Operationen beschränkt. Ein durchgesickerter Payment-Zugang kann keine Mittel bewegen — der Geltungsbereich wird zentral bei jeder Anfrage geprüft, sodass ein Payment-Schlüssel niemals einen Auszahlungsendpunkt erreicht, gleich über welche Route.
Schlüsselarten
| Art | Präfix | Geltungsbereich |
|---|---|---|
| Payment | pk_ |
Rechnungen erstellen, Rechnungsstatus lesen, Zahlungskanäle verwalten und deren Einzahlungen lesen |
| Payout | rk_ |
Auszahlungen erstellen, Auszahlungen stornieren, Guthaben lesen |
API-Geheimnisse nutzen das Präfix sk_. Geheimnisse zur Webhook-Signatur nutzen whsec_.
Umgebungen
Jeder Zugang gehört zu genau einer Umgebung. Die Umgebung steckt im Präfix:
| Umgebung | Präfix-Kennung | Beispiel |
|---|---|---|
| Produktion | _live_ |
pk_live_…, rk_live_… |
| Sandbox | _test_ |
pk_test_…, rk_test_… |
Ein vollständig eingerichteter Händler hält vier Schlüssel-IDs (pk_live_…, pk_test_…, rk_live_…, rk_test_…) und zwei Webhook-Geheimnisse (whsec_live_…, whsec_test_…).
Einzelheiten zum Geltungsbereich
Die Trennung der Geltungsbereiche wird zentral durchgesetzt, nicht je Route: Die Zugriffsstufe ergibt sich bei jeder Anfrage aus der Schlüsselart, sodass ein Payment-Schlüssel nur Endpunkte für eingehendes Geld erreicht und ein Payout-Schlüssel nur Auszahlungsendpunkte.
Zahlungskanäle zählen zum eingehenden Geld. Alle acht Endpunkte für Kanäle und Einzahlungen verlangen einen Payment-Schlüssel und antworten einem Payout-Schlüssel mit 403 payment_key_required — spiegelbildlich dazu, wie Auszahlungen einen Payment-Schlüssel abweisen.
Beim Guthaben überrascht die Trennung am ehesten: GET /v1/balances verlangt einen Payout-Schlüssel. Der Payment-Schlüssel liegt auf Shop-Servern, geht in jedes Deployment mit und ist derjenige, der abhandenkommt — deshalb bekommt er keinen Blick darauf, was Sie halten. Lesen Sie Guthaben von dort, wo Sie auch Auszahlungen anstoßen.
Für Payout gilt eine zusätzliche Sicherung. Ein Payout-Zugang bleibt inaktiv, bis Sie eine IP-Freigabeliste hinterlegen — jede Anfrage wird abgewiesen, solange im Dashboard nicht mindestens eine erlaubte IP eingetragen ist. Ein frisch erzeugter Payout-Schlüssel kann für sich allein keine Mittel bewegen.
Ein Payout-Schlüssel kann Mittel aus Ihrem Paymos-Guthaben abziehen — behandeln Sie ihn wie Ihr Bankpasswort. Die IP-Freigabeliste ist die Mauer zwischen einem gestohlenen Schlüssel und Ihrem Geld: Halten Sie sie so eng wie möglich und tragen Sie nur die Server-IPs ein, die die Auszahlungs-API tatsächlich aufrufen.
Lebenszyklus
| Status | Beschreibung |
|---|---|
| Aktiv | Der Zugang ist einsatzbereit und nimmt Anfragen an |
| Widerrufen | Endzustand. Der Zugang ist dauerhaft deaktiviert und lässt sich nicht reaktivieren |
Sicherheit in der Praxis
- —API-Geheimnisse niemals in Client-Code offenlegen
- —Geheimnisse regelmäßig über das Dashboard wechseln — eine Übergangsfrist hält das vorherige Geheimnis währenddessen gültig
- —Getrennte Zugangsdaten für Produktion und Sandbox verwenden
- —Payout-Zugänge nach IP-Adresse beschränken
- —API-Geheimnisse ausschließlich in Umgebungsvariablen oder einem Secrets-Manager ablegen
Das HMAC-SHA256-Signaturverfahren, das diese Zugangsdaten nutzt, steht unter Authentifizierung.