XDR⁵ API

Mit der XDR⁵ Hosted Checkout API kannst du in deinem Shop Zahlungen in der Währung TRYX annehmen – ohne eigene PHP-Skripte. Du brauchst nur ein paar JavaScript-Variablen und ein <script>-Tag.

Es gibt zwei Wege zur Integration:

Hosted Checkout mit xdr5_checkout.js (empfohlen, am einfachsten)
JSON-API für eigene, serverseitig gesteuerte Checkouts (optional)

1. Grundprinzip (Hosted Checkout)

Auf deiner Shop- bzw. Zahlungsseite definierst du den Betrag und bis zu 10 frei benennbare Werte.
Du bindest das Script https://xdr5.de/api/xdr5_checkout.js ein.
Das Script erzeugt automatisch an dieser Stelle einen „Mit TRYX bezahlen“-Button.
Nach der Zahlung landest du auf deiner Danke-Seite, wo das Script dir dieselben Werte wieder bereitstellt.

Im Hintergrund kümmert sich die XDR⁵-Plattform um Payment-Intent, TRYX-Guthabenprüfung und Abbuchung.

2. Shop-/Zahlungsseite: TRYX-Button einbinden

Minimaler Einbau – die wichtigsten Variablen:

<script>
var xdr5_amount = 7;

var xdr5_v_1  = ["Name", ""];
var xdr5_v_2  = ["Straße", ""];
var xdr5_v_3  = ["PLZ", ""];
var xdr5_v_4  = ["Beispielwert 1", ""];
var xdr5_v_5  = ["Beispielwert 2", ""];
var xdr5_v_6  = ["Beispielwert 3", ""];
var xdr5_v_7  = ["Beispielwert 4", ""];
var xdr5_v_8  = ["Beispielwert 5", ""];
var xdr5_v_9  = ["Beispielwert 6", ""];
var xdr5_v_10 = ["Beispielwert 7", ""];

var xdr5_return_url = "https://deinshop.de/tryx_danke/";
</script>

<script src="https://xdr5.de/api/xdr5_checkout.js"></script>

xdr5_amount – Preis in TRYX (Ganzzahl).
xdr5_v_1 bis xdr5_v_10 – jeweils ["Label", "Wert"], z. B. Kundendaten.
xdr5_return_url – Basis-URL der Danke-Seite deines Shops. Endet die URL auf /, ergänzt die XDR⁵-API automatisch danke.html.

Sobald das Script geladen ist, erscheint an dieser Stelle automatisch der Button „Mit TRYX bezahlen“.

2.1 Werte aus Formular / Server übernehmen

Typisch ist: Du hast bereits eine Bestellseite und setzt die Variablen serverseitig aus deinen Formulardaten:

<script>
var xdr5_amount = {{amount_tryx}};

var xdr5_v_1 = ["Name", "{{customer_name}}"];
var xdr5_v_2 = ["E-Mail", "{{customer_email}}"];
var xdr5_v_3 = ["Adresse", "{{customer_address}}"];
var xdr5_v_4 = ["Bestellnummer", "{{order_number}}"];
var xdr5_v_5 = ["Produkt", "{{product_name}}"];

var xdr5_v_6 = ["", ""];
var xdr5_v_7 = ["", ""];
var xdr5_v_8 = ["", ""];
var xdr5_v_9 = ["", ""];
var xdr5_v_10 = ["", ""];

var xdr5_return_url = "https://deinshop.de/tryx_danke/";
</script>

<script src="https://xdr5.de/api/xdr5_checkout.js"></script>

Die Platzhalter {{…}} stehen hier nur als Beispiel für dein Template-System (PHP, Twig, Blade, …).

3. Danke-Seite: Ergebnis anzeigen

Auf deiner Danke-Seite reicht das Minimum:

<div id="xdr5-tryx-result"></div>
<script src="https://xdr5.de/api/xdr5_checkout.js"></script>

Das Script liest automatisch die Rückgabeparameter, lädt die gespeicherten Daten der Bestellung aus dem Local Storage und schreibt eine Standard-Ausgabe in das <div id="xdr5-tryx-result">.

4. Verfügbare Variablen auf der Danke-Seite

Nach dem Laden von xdr5_checkout.js hast du z. B. Zugriff auf:

xdr5_status – "success", "cancel" oder leer
xdr5_order_id – Bestell-ID
xdr5_payment_id – Payment-ID der XDR⁵-API
xdr5_amount – Betrag in TRYX
xdr5_description – z. B. "TRYX Bestellung"
xdr5_v_1 … xdr5_v_10 – jeweils wieder [Label, Wert]
xdr5_result – komplettes Ergebnisobjekt

Beispiel: eigene Weiterverarbeitung per JavaScript

<script>
document.addEventListener("DOMContentLoaded", function () {
  console.log("Status:", xdr5_status);
  console.log("Bestell-ID:", xdr5_order_id);
  console.log("Name:", xdr5_v_1[0], xdr5_v_1[1]);
});
</script>

<script src="https://xdr5.de/api/xdr5_checkout.js"></script>

Damit ist die Integration bewusst schlank gehalten: Ein Script, ein paar Variablen – den Rest übernimmt XDR⁵.

5. Rückgabe & Status (Redirect)

Nach einer TRYX-Zahlung leitet die XDR⁵-Plattform auf die in xdr5_return_url definierte Danke-Seite zurück. Dabei werden folgende URL-Parameter angehängt:

status – success oder cancel
order_id – die Bestell-ID
payment_id – die interne Payment-ID der XDR⁵-Plattform

Auf der Danke-Seite liest xdr5_checkout.js diese Parameter aus, lädt die Bestelldaten aus dem Local Storage und stellt sie dir sowohl als HTML-Ausgabe als auch in JavaScript-Variablen zur Verfügung (siehe oben).

Hinweis: Wird keine xdr5_return_url gesetzt, verwendet die API automatisch den aktuellen Pfad und ergänzt danke.html als Standard-Ziel.

6. Erweiterte JSON-API (optional)

Neben dem Hosted-Checkout-Script xdr5_checkout.js bietet XDR⁵ eine einfache JSON-API, mit der du Zahlungen serverseitig steuern kannst. Die Endpunkte erwarten und liefern JSON.

6.1 Payment Intent erstellen

POST https://xdr5.de/api/api_create_payment_intent.php

Request-Body (JSON):

{
  "amount": 7,
  "currency": "TRYX",
  "description": "TRYX Bestellung",
  "success_url": "https://deinshop.de/tryx_danke/",
  "cancel_url": "https://deinshop.de/tryx_abbruch/",
  "metadata": {
    "value_1": "{\"label\":\"Name\",\"value\":\"Max Mustermann\"}",
    "value_2": "{\"label\":\"Bestellnummer\",\"value\":\"ABC-123\"}"
  }
}

Antwort (Beispiel):

{
  "success": true,
  "id": "pay_...",
  "status": "created",
  "amount": 7,
  "currency": "TRYX",
  "checkout_url": "https://xdr5.de/api/checkout_tryx.php?id=pay_..."
}

6.2 Payment Intent abfragen

GET https://xdr5.de/api/api_get_payment_intent.php?payment_id=pay_...

Antwort (verkürzt):

{
  "success": true,
  "id": "pay_...",
  "status": "created|succeeded|canceled",
  "amount": 7,
  "currency": "TRYX",
  "description": "TRYX Bestellung",
  "metadata": { ... },
  "success_url": "...",
  "cancel_url": "..."
}

6.3 Zahlung bestätigen

POST https://xdr5.de/api/api_confirm_payment_intent.php

Request-Body (JSON):

{
  "payment_id": "pay_..."
}

Antwort (Beispiel):

{
  "success": true,
  "payment_id": "pay_...",
  "status": "succeeded",
  "amount": 7,
  "currency": "TRYX",
  "new_balance": 42
}

Die JSON-API ist optional und richtet sich an fortgeschrittene Integrationen, bei denen du den Checkout-Prozess vollständig selbst steuern möchtest. Für die meisten Shops reicht der Hosted Checkout mit xdr5_checkout.js aus.

7. Datenübertragung & Speicherung

7.1 Welche Daten sendet dein Shop an XDR⁵?

Wenn du den Hosted Checkout mit xdr5_checkout.js verwendest, sendet dein Shop beim Klick auf „Mit TRYX bezahlen“ ein Formular per POST an https://xdr5.de/api/hosted_checkout.php. Dabei werden unter anderem folgende Felder übertragen:

amount – Betrag in TRYX
currency – aktuell immer TRYX
order_id – von dir oder dem Script erzeugte Bestell-ID
description – Beschreibung der Bestellung (z. B. „TRYX Bestellung“)
return_url – Ziel-URL für die Rückleitung nach der Zahlung
value_1 bis value_10 – optionale Metadaten, die aus xdr5_v_1 bis xdr5_v_10 erzeugt werden ({ "label": "...", "value": "..." })

Welche Informationen in den Metadaten xdr5_v_1 bis xdr5_v_10 stehen, bestimmst du als Shopbetreiber selbst (z. B. Name, E-Mail, Bestellnummer, Produktname).

7.2 Was speichert XDR⁵ auf dem Server?

Für jede Zahlung erzeugt die XDR⁵-Plattform einen Payment-Intent mit:

Payment-ID
Betrag in TRYX
Währung (TRYX)
Status der Zahlung (z. B. created, succeeded, canceled)
den von dir übergebenen Texten für description, success_url und cancel_url
den Metadaten aus value_1 bis value_10, soweit du diese befüllst

Diese Daten werden benötigt, um die Zahlung technisch abzuwickeln, Fehler analysieren zu können und Transaktionen in der MATRYX nachzuvollziehen.

7.3 Was bleibt nur im Browser (Local Storage)?

Das Script xdr5_checkout.js speichert zusätzlich eine Kopie der Bestelldaten im Local Storage des Browsers des Nutzers (unter einem Schlüssel wie tryx_order_<order_id>). Diese Daten werden genutzt, um auf der Danke-Seite die Bestellung erneut anzuzeigen und die JavaScript-Variablen xdr5_status, xdr5_order_id, xdr5_amount, xdr5_v_1–xdr5_v_10 usw. zu setzen.

Diese Local-Storage-Daten verbleiben im Browser des Nutzers und werden nicht erneut an die XDR⁵-Plattform gesendet. Sie können vom Nutzer durch Löschen von Website-Daten/Local Storage entfernt werden.

7.4 Umgang mit personenbezogenen Daten

In den Feldern xdr5_v_1 bis xdr5_v_10 kannst du personenbezogene Daten wie Name, E-Mail oder Adresse übergeben. Bitte verwende hier nur Daten, die für die Bestellabwicklung tatsächlich notwendig sind, und keine hochsensiblen Informationen (z. B. Passwörter, Zahlungsdaten anderer Dienste, Gesundheitsdaten usw.).

Als Shopbetreiber bleibt du Verantwortlicher für die von dir übermittelten Daten im Sinne der Datenschutzgesetze. XDR⁵ verarbeitet diese Daten ausschließlich zur Abwicklung der TRYX-Zahlung und zur Darstellung der Bestellung in deinem Shop.

XDR5 API