Aufträge erstellen

3.1.3. Aufträge erstellen#

Diese Seite enthält die gesamte Dokumentation für das Video-Tutorial, das eine einfache Auftragserstellung über die API und die Überprüfung des Auftragsstatus erklärt.

3.1.3.1. Video#

3.1.3.2. Anforderungen#

Erforderlich für diese Lehrgangsreihe:

  • Ein Taler-Händler-Backend
    Wenn Sie Hilfe benötigen, um das Händler-Backend zum ersten Mal zu benutzen, können Sie sich das Taler-Händler-Einführung-Tutorial ansehen.
  • Eine Taler-Walletn-Instanz
    Anleitungen zur Einrichtung finden Sie unter https://wallet.taler.net.
  • Eine REST-API-Verwaltungssoftware oder entsprechende Programmierkenntnisse
    In dieser Videoreihe werden wir die kostenlose Software Insomnia verwenden, die unter https://insomnia.rest heruntergeladen werden kann.

3.1.3.3. Demo-Backend Hinweis#

Sie können Ihren eigenen Händler-Backend-Dienst oder den Online-Demonstrationsdienst unter https://backend.demo.taler.net/instances/sandbox/ für dieses Tutorial verwenden.

3.1.3.4. Zahlungsabwicklung für Händler#

  1. Anlegen eines Auftrags für eine Zahlung

Zahlungen in Taler basieren auf einer Bestellung, einer maschinenlesbaren Beschreibung des Geschäftsvorfalls, für den die Zahlung erfolgen soll. Bevor Sie als Händler eine Taler-Zahlung akzeptieren, müssen Sie einen solchen Auftrag erstellen.

Dies geschieht durch POSTing eines JSON-Objekts an den API-Endpunkt /private/orders des Backends. Mindestens die folgenden Felder müssen innerhalb des Feldes order angegeben werden:

  • Betrag: Der zu zahlende Betrag, als String im Format CURRENCY:DECIMAL_VALUE, zum Beispiel EUR:10 für 10 Euro oder KUDOS:1.5 für 1.5 KUDOS.

  • Zusammenfassung``: Eine von Menschen lesbare Zusammenfassung, worum es bei der Zahlung geht. Die Zusammenfassung sollte so kurz sein, dass sie in den Titel passt, obwohl es keine feste Grenze gibt.

  • Erfüllungs-Url“: Eine URL, die angezeigt wird, sobald die Zahlung abgeschlossen ist. Bei digitalen Gütern sollte dies eine Seite sein, die das gekaufte Produkt anzeigt. Bei erfolgreicher Zahlung fügt die Wallet automatisch die Order_id als Query-Parameter hinzu, ebenso wie die Session_sig für sitzungsgebundene Zahlungen (siehe unten).

Bestellungen können viele weitere Felder haben, siehe Das Taler-Bestellformat. Wenn Sie eine Bestellung POSTen, können Sie auch zusätzliche Details angeben, wie z.B. einen Override für die Erstattungsdauer und Anweisungen für die Bestandsverwaltung. Diese werden selten benötigt und in diesem Tutorial nicht behandelt; bitte lesen Sie das Referenzhandbuch für Details.

Ein minimales Python-Snippet zur Erstellung einer Bestellung würde wie folgt aussehen:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Das Backend ergänzt einige Details, die in der Bestellung fehlen, wie z. B. die Adresse der Händlerinstanz. Die vollständigen Details werden als Vertragsbedingungen bezeichnet.

Bemerkung

Die obige Anfrage deaktiviert die Verwendung von Anspruchstoken, indem sie die Option create_token auf false setzt. Wenn Sie Anspruchstoken benötigen, müssen Sie den Code anpassen, um den unten angegebenen URI taler://pay/ so zu konstruieren, dass er das Anspruchstoken enthält.

Nach erfolgreicher POST an /private/orders wird ein JSON mit nur einem Feld order_id mit einer Zeichenkette, welche die Bestell-ID darstellt, zurückgegeben. Wenn Sie auch ein Anspruchstoken erhalten, überprüfen Sie bitte, ob Sie die Anfrage wie oben beschrieben verwendet haben.

Zusammen mit der Instanz des Händlers identifiziert die Bestell-ID die Bestellung eindeutig innerhalb eines Händler-Backends. Mit Hilfe der Bestell-ID können Sie trivialerweise die entsprechende taler://pay/ URI konstruieren, die der Wallet zur Verfügung gestellt werden muss. Lassen Sie example.com den Domainnamen sein, unter dem die öffentlichen Endpunkte der Instanz erreichbar sind. Der Taler pay URI ist dann einfach taler://pay/example.com/$ORDER_ID/, wobei $ORDER_ID durch die ID der zurückgegebenen Bestellung ersetzt werden muss.

Sie können die taler:// URI als Ziel eines Links setzen, um die Taler-Wallet über das taler:// Schema zu öffnen, oder sie in einen QR-Code einfügen. Für einen Webshop ist es jedoch am einfachsten, den Browser einfach auf https://example.com/orders/$ORDER_ID umzuleiten. Diese Seite wird dann die Taler-Wallet auslösen. Hier generiert das Backend die richtige Logik, um die Wallet auszulösen, und unterstützt die verschiedenen Arten von Taler-Wallets. Anstatt die obige URL von Hand zu erstellen, ist es auch möglich, sie durch die Überprüfung des Zahlungsstatus zu erhalten, wie im nächsten Abschnitt beschrieben.

Wenn Sie diese URL manuell erstellen, stellen Sie sicher, dass Sie das Claim-Token angeben (es sei denn, es wurde deaktiviert) und wenn das Backend ohne TLS läuft, verwenden Sie taler+http:// (beachten Sie, dass Letzteres nur von Geldbörsen unterstützt wird, die im Debug-Modus laufen).

Bemerkung

Ein trivialer Weg, die korrekte payment_redirect_url zu erhalten, ist, den Status der Zahlung zu überprüfen (siehe unten). Wenn Sie also immer noch unsicher sind, wie Sie es konstruieren sollen, können Sie einfach das Backend bitten, dies für Sie zu tun. In der Produktion sollten Sie sie aber wahrscheinlich manuell konstruieren und die zusätzliche Anfrage an das Backend vermeiden.

  1. Überprüfung des Zahlungsstatus und Aufforderung zur Zahlung

Anhand der Bestell-ID kann der Status einer Zahlung mit dem Endpunkt /private/orders/$ORDER_ID überprüft werden. Wenn die Zahlung durch den Kunden noch nicht abgeschlossen ist, gibt /private/orders/$ORDER_ID dem Frontend eine URL (unter dem Namen payment_redirect_url), die das Wallet des Kunden veranlasst, die Zahlung auszuführen. Dies ist im Grunde die URL https://example.com/orders/$ORDER_ID, die wir oben besprochen haben.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Wenn das Feld order_status in der Antwort paid lautet, erhalten Sie keine payment_redirect_url und stattdessen Informationen über den Zahlungsstatus, einschließlich:

  • Vertragsbedingungen: Die vollständigen Vertragsbedingungen der Bestellung.

  • refunded: true, wenn für diesen Kauf eine (möglicherweise teilweise) Rückerstattung gewährt wurde.

  • Erstatteter_Betrag“: Betrag, der erstattet wurde

Sobald das Frontend bestätigt hat, dass die Zahlung erfolgreich war, muss es in der Regel die Geschäftslogik für den Händler auslösen, damit dieser seine Verpflichtungen aus dem Vertrag erfüllen kann.

Bemerkung

Sie müssen die Abfrage nicht ständig wiederholen, um Änderungen des Transaktionsstatus der Bestellung zu bemerken. Die Endpunkte unterstützen lange Abfragen, geben Sie einfach einen timeout_ms Abfrageparameter an, der angibt, wie lange Sie höchstens warten wollen, bis der Bestellstatus auf bezahlt wechselt.

3.1.3.5. Mehr Tutorials#

Weitere Anleitungen finden Sie auf dieser Website oder unter https://docs.taler.net, wo Sie die neueste Dokumentation über die Taler-Dienste finden.