Einen Laden anbinden

KINISI lässt sich als Zahlungsmittel annehmen — im eigenen Shop, an einem Preisschild, überall dort, wo sonst TRYX steht. Drei Aufrufe genügen. Wer bei XDR⁵ schon TRYX angebunden hat, erkennt alles wieder.

Der Ablauf

Der Shop kündigt die Zahlung an, schickt die Kundin zu uns, und fragt danach nach. Es zählt allein die dritte Antwort — die, die der Shop selbst bei uns abholt.

Ankündigen

Der Shop ruft payment_intent_create mit seinem Schlüssel und dem Betrag. Er bekommt eine payment_id und eine checkout_url. Ab hier steht der Betrag fest.

Umleiten

Die Kundin geht auf die checkout_url, meldet sich mit ihrer Bank-ID an und bestätigt. Sie verlässt den Shop dabei sichtbar, in einem eigenen Fenster.

Nachfragen

Der Shop ruft payment_intent_get und liefert erst, wenn dort status: "bezahlt" steht und der Betrag stimmt.

Ein Intent verfällt nach 15 Minuten. „Verfallen" wird bei jeder Abfrage aus der Uhrzeit gerechnet. Die Frist hängt damit allein an der Uhr und ist dadurch immer aktuell — ganz ohne Hintergrundlauf, der ausfallen könnte.

Was ein Laden braucht

Eine Bank-ID

Das Konto des Ladens — dorthin geht das Geld. Dieselbe Art ID wie bei jedem Menschen: reine Zufallszeichen. Was der Laden einnimmt, kann er ausgeben oder verschenken.

Einen Shop-Schlüssel

Den vergeben wir. Er wird serverseitig mitgeschickt und gehört ausschließlich auf den Server des Ladens.

⚠ Der Empfänger hängt am Schlüssel

Wer den Schlüssel hat, bekommt das Geld auf genau das Konto, das bei uns dazu hinterlegt ist — und nur dorthin. payment_intent_create nimmt deshalb ausschließlich Betrag und Referenz entgegen. Ein übernommener Shop-Server kann das Ziel damit nur ändern, indem der Schlüssel selbst getauscht wird; das merkt der Laden.

Die Aufrufe

Alles geht an einen Endpunkt, unterschieden durch das Feld action. Immer POST, immer JSON.

Endpunkt

POST http://kinisi.xdr5.de/api/kinisi_json.php
Content-Type: application/json

Derzeit http — und das ist gemessen: kinisi.xdr5.de liefert das Standardzertifikat des Hosters (*.alfahosting-server.de, nachgemessen 25.08.2026), eine TLS-Prüfung schlägt also fehl. Wer aus einem Shop bei demselben Hoster anbindet, bleibt dabei im Rechenzentrum (alle Domains lösen auf dieselbe Adresse auf). Von außen laufen Schlüssel und Antwort im Klartext; der Schlüssel berechtigt allein dazu, Zahlungen auf dieses eine Konto auszustellen. Sobald ein passendes Zertifikat steht, gilt https — die checkout_url folgt dabei automatisch dem Schema, unter dem angefragt wurde.

1 · Zahlung ankündigen

{
  "action":      "payment_intent_create",
  "shop_key":    "…",
  "betrag":      70,
  "referenz":    "Bestellung 4711",
  "erfolg_url":  "https://mein-laden.de/danke",
  "abbruch_url": "https://mein-laden.de/warenkorb"
}

{
  "ok":           true,
  "payment_id":   "pi_a1b2c3d4e5f60718",
  "betrag":       70,
  "checkout_url": "http://kinisi.xdr5.de/zahlen.php?pi=pi_a1b2c3d4e5f60718",
  "gueltig_bis":  1756403600
}

Rückleit-Adressen sind eingeschränkt: erlaubt sind http/https mit reinem Hostnamen, und zwar mit dem Host, der für den Laden hinterlegt ist. So bleibt kinisi.xdr5.de eine geschlossene Weiterleitung. Eine Rückleitung gibt es, sobald ein Host hinterlegt ist.

2 · Stand abfragen

{"action": "payment_intent_get", "shop_key": "…", "payment_id": "pi_…"}

{"ok": true, "status": "bezahlt", "betrag": 70,
 "zahler": "XDR5…", "zeit": 1756400900, "beleg": "9f8e7d6c5b4a3210"}

status: offen · bezahlt · abgebrochen · verfallen. zahler, zeit und beleg erscheinen bei bezahlt, und zwar gegenüber dem Laden, dem gezahlt wurde.

3 · Zurückziehen (optional)

{"action": "payment_intent_cancel", "shop_key": "…", "payment_id": "pi_…"}

Abbrechen darf der Laden, solange die Zahlung offen ist. Für die Kundin erledigt sich das von selbst: Nach der Frist verfällt die Zahlung.

4 · Einen Beleg prüfen (ohne Schlüssel)

{"action": "beleg_pruefen", "beleg": "9f8e7d6c5b4a3210"}

Öffentlich, und das ist der Sinn eines Belegs: Wer einen Ausdruck in der Hand hält, soll ihn prüfen können — auch mit bloßem Papier und ohne Konto. Herausgegeben werden Betrag, Zeit und Art. Ein Beleg belegt den Vorgang; die Beteiligten bleiben bei sich.

Die eine Regel, an der alles hängt

Liefere erst, wenn wir es sagen

Beweis ist allein die Antwort auf payment_intent_get, zusammen mit dem Betrag, den der Shop selbst angekündigt hat. Die Rückkehr des Browsers auf die erfolg_url ist bloß ein Hinweis: Jeder, der die Adresse kennt, kann sie auslösen.

Und ein zweites Netz gehört dazu: Ein regelmäßiger Nachlauf fragt offene Bestellungen noch einmal ab. Er fängt die Kundin auf, die nach dem Bezahlen den Browser schließt und die Erfolgsseite dadurch verpasst.

Wenn ein Aufruf abgelehnt wird

Jede Antwort trägt ok. Ist es false, steht in error, woran es lag.

Fehler	Bedeutung
`shop_unbekannt`	Der Schlüssel ist hier unbekannt oder kürzer als 32 Zeichen — so lang muss er mindestens sein.
`betrag_ungueltig`	Beträge sind ganze, positive Zahlen — KIN gibt es nur am Stück.
`erfolg_url_ungueltig`	Die Rückleit-Adresse liegt außerhalb der erlaubten Form (siehe oben).
`intent_unbekannt`	Diese `payment_id` ist für deinen Schlüssel unbekannt — sei es, weil sie hier fehlt, sei es, weil sie einem anderen Laden gehört. Beides antwortet gleich, damit der Endpunkt allein über eigene Zahlungen Auskunft gibt.
`intent_verfallen`	Älter als 15 Minuten. Der Laden stellt eine neue aus.
`intent_schon_bezahlt`	Doppelt bestätigt. Es wurde nur einmal abgebucht.
`insufficient_funds`	Der Betrag liegt über dem Guthaben der Kundin. Ihr Stand steht im Feld `stand`.
`unbekannte_action`	Das Feld `action` trägt einen Namen außerhalb der Liste oben. Antwortet mit HTTP 404.

Wenn der Shop in TRYX rechnet

Der häufigste Fall — und er kommt mit einer einzigen Preisliste aus.

KINISI ist dann ein zweiter Weg, denselben Preis zu bezahlen. Was 10 TRYX kostet, kostet in KIN eben 10 × Kurs. Den Kurs liefert {"action": "kurs"} im Feld kurs — er sagt, wie viele KIN ein TRYX gerade wert ist.

Rechne einmal um und schreibe das Ergebnis fest. Der Betrag im Intent gilt, was auch der Kurs danach tut. Halte den benutzten Kurs bei der Bestellung fest — dann bleibt später nachvollziehbar, warum es diese Zahl war.

Biete KIN an, solange kurs mit ermittelt: true antwortet. Unter einer Mindestmenge im Umlauf steht dort false — dann lass den Zahlungsweg im Kassenbereich weg. Die Kundin hat ihre Daten dort schon eingegeben; ein Weg, der erst an dieser Stelle scheitert, kostet sie den ganzen Vorgang.

Anfangen

Schreib uns, mit welcher Bank-ID der Laden Geld empfangen soll und unter welchem Host die Rückleitung liegt. Du bekommst einen Schlüssel zurück. Anbinden ist frei und formlos: eine Nachricht, ein Schlüssel zurück — KINISI ist Kunst.

Die vollständige Beschreibung aller Aktionen samt Begründungen steht in kinisi_api.md im Projekt. Für WooCommerce entsteht gerade die KINISI-Erweiterung des Plugins XDR5 TRYX Gateway; bis sie erprobt ist, bindet man die drei Aufrufe oben von Hand ein.