Server-SDKs

Paymos pflegt offizielle serverseitige SDKs für acht Sprachökosysteme. Jedes SDK deckt denselben Vertrag ab: Rechnungen, Auszahlungen, Zahlungskanäle, Kanaleinzahlungen, Guthaben, Serverzeit, Cursor-Navigation, Fehler, Wiederholungen, Signatur der Anfrage und Prüfung von Webhooks.

Alle acht sind in der Registry ihres Ökosystems veröffentlicht. Installieren Sie von dort; im Repository liegen Quellcode und Release-Historie.

Sprache	Registry	Installation	Offizielle Quelle
JavaScript / TypeScript	npm	npm i @paymos/sdk	Paymos-labs/typescript-sdk
Python	PyPI	pip install paymos-sdk	Paymos-labs/python-sdk
PHP	Packagist	composer require paymos/php-sdk	Paymos-labs/php-sdk
Go	Go modules	go get github.com/Paymos-labs/go-sdk/v2	Paymos-labs/go-sdk
.NET	NuGet	dotnet add package Paymos	Paymos-labs/dotnet-sdk
Java	Maven Central	io.paymos:paymos-java	Paymos-labs/java-sdk
Ruby	RubyGems	gem install paymos	Paymos-labs/ruby-sdk
Rust	crates.io	cargo add paymos	Paymos-labs/rust-sdk

Für Java gibt es keinen Installationsbefehl in einer Zeile: Tragen Sie io.paymos:paymos-java als Abhängigkeit in Ihre pom.xml oder in Ihren Gradle-Build ein.

Verwenden Sie ein unveränderliches Release-Tag vMAJOR.MINOR.PATCH. Die Release-Seite jedes Repositories nennt die unterstützte Laufzeitumgebung, das Änderungsprotokoll und den Quell-Commit, aus dem das Release entstanden ist.

Gemeinsame API-Oberfläche

Alle Clients stellen sechs Ressourcen bereit:

• —system — Serverzeit abrufen, um die Uhr für Anfragen abzugleichen
• —invoices — erstellen, abrufen, auflisten, stornieren, Zahlung bestätigen und in der Sandbox simulieren
• —withdrawals — erstellen, abrufen, auflisten, stornieren und den Abschluss in der Sandbox simulieren
• —paymentChannels — erstellen, abrufen, auflisten, sperren, entsperren und eine Einzahlung in der Sandbox simulieren
• —paymentChannelDeposits — eine Einzahlung abrufen und den Feed bestätigter Einzahlungen abfragen
• —balances — verfügbare Guthaben nach Währung gruppiert auflisten

Jeder Client schreibt die beiden Kanal-Ressourcen in der Konvention seiner Sprache: paymentChannels in TypeScript, PHP und Java, payment_channels in Python, Ruby und Rust, PaymentChannels in Go und .NET.

Die Hilfsfunktionen zum Auflisten nutzen Cursor-Navigation mit einer Obergrenze je Seite und weisen einen zweimal zurückgegebenen Cursor ab. Automatische Wiederholungen beachten Retry-After; verändernde Anfragen werden bei Transportfehlern oder allgemeinen Serverfehlern nicht wiederholt. Eine wegen der Anfragegrenze abgewiesene Anfrage darf wiederholt werden, weil die API sie gar nicht zur Verarbeitung angenommen hat.

Ein Vertrag für acht Sprachen

Gemeinsam ist den acht nicht nur die Liste der Endpunkte, sondern das Verhalten. Eine einzige sprachneutrale Prüfsammlung legt fest, welche Bytes in eine Anfragesignatur einfließen, wie die Wiederholungen oben laufen, wie die Cursor-Iteratoren arbeiten und wie der Webhook geprüft wird. Ein Release erscheint erst, wenn die eigenen Tests des SDK gegen diese Sammlung laufen.

Praktisch heißt das: Eine Anbindung, die von einer dieser Sprachen in eine andere umzieht, behält Signatur, Seitenlauf, Wiederholungen und Webhook-Verhalten. Zwei SDKs signieren dieselbe gefilterte Listenanfrage mit denselben Bytes.

Was PHP zusätzlich mitbringt

Das PHP-SDK trägt eine Schicht für Shop-Anbindungen, die kein anderer Client hat: Gegenprüfung eines Webhooks über einen frischen API-Aufruf, eine Kontrolle von Betrag und Währung, bevor eine Bestellung freigegeben wird, Schutz vor doppelter Verarbeitung über einen austauschbaren Ereignisspeicher, ein Prüfer, der das Sandbox- und das Live-Geheimnis gleichzeitig hält, ein Abgleich, eine Zuordnung vom Ereignis zur Bestellaktion und verschlüsselte Ablage der Zugangsdaten.

Diese Schicht ist der Grund, warum die CMS-Plugins so dünn sind: Die Logik der Bestellzustände liegt einmal im SDK darunter statt achtmal darüber. Für die anderen sieben gilt davon nichts — sie bestehen aus Client, Signatur, Ressourcen, Seitenlauf und Webhook-Prüfung, und mehr ist dort nicht zu finden.

Sicherheitsregeln

Die Authentifizierung von Anfragen und die von Webhooks nutzen unterschiedliche Signaturen. API-Anfragen nutzen HMAC-SHA256 in Base64 über die kanonische Anfrage. Webhooks nutzen HMAC-SHA256 in Hex über {timestamp}.{exakter Rohtext}. Übergeben Sie dem Prüfer des SDK die ungeparsten Bytes der Anfrage, bevor Sie das JSON dekodieren. Der Prüfer weist einen Zeitstempel, der mehr als fünf Minuten von jetzt abweicht, standardmäßig ab und nimmt einen Header mit zwei v1-Werten an — ein Wechsel des Geheimnisses kostet Sie also keine Codeänderung.

Schemata und Beispiele der Endpunkte finden Sie unter Authentifizierung, Rechnungen, Auszahlungen, Guthaben und Webhooks.