Das Taler-Bestellformat

3.1.6. Das Taler-Bestellformat#

Das Taler-Bestellformat beschreibt das JSON, das an das Händler-Backend gepostet werden muss, um eine Bestellung zu erstellen. Es ist der Prototyp, aus dem das Händler-Backend die eigentlichen Vertragsbedingungen erstellen wird.

Es gibt verschiedene Versionen für das Bestellformat; sie sind im Referenzhandbuch ausführlich beschrieben.

Bemerkung

Finanzbeträge werden immer als String im Format "CURRENCY:DECIMAL_VALUE" angegeben.

Dieser Abschnitt gibt einen Überblick über die gängigsten Felder:

amount

Gibt den Gesamtbetrag an, den der Kunde an den Händler zu zahlen hat.

max_fee

Dies ist der maximale Gesamtbetrag der Einzahlungsgebühren, den der Händler zu zahlen bereit ist. Wenn die Einzahlungsgebühren für die Münzen diesen Betrag übersteigen, muss der Kunde sie in die Gesamtsumme der Zahlung einrechnen. Die Gebühr wird in demselben Format angegeben wie amount.

max_wire_fee

Maximale vom Händler akzeptierte Überweisungsgebühr (der Kundenanteil wird durch den Faktor wire_fee_amortization geteilt und weiter reduziert, wenn die Einzahlungsgebühren unter max_fee liegen). Der Standardwert ist Null, wenn er fehlt.

wire_fee_amortization

Über wie viele Kundentransaktionen rechnet der Händler damit, die Überweisungsgebühren im Durchschnitt zu amortisieren? Liegt die Überweisungsgebühr der Exchange über der max_wire_fee, wird die Differenz durch diese Zahl geteilt, um den erwarteten Beitrag des Kunden zur Überweisungsgebühr zu berechnen. Der Beitrag des Kunden kann weiter um die Differenz zwischen max_fee und der Summe der tatsächlichen Einzahlungsgebühren reduziert werden. Optional, Standardwert bei Fehlen ist 1. Nullen und negative Werte sind ungültig und werden ebenfalls als 1 interpretiert.

pay_url

Welche URL Zahlungen annimmt. Dies ist die URL, unter der die Wallet Münzen POSTEN wird.

fulfillment_url

Zu welcher URL soll die Wallet gehen, um die Erfüllung zu erhalten, z. B. die HTML- oder PDF-Datei eines gekauften Artikels oder ein System zur Auftragsverfolgung für Sendungen oder eine einfache, von Menschen lesbare Webseite, die den Status des Vertrags angibt.

order_id

Alphanumerische Kennung, die vom Händler frei definiert werden kann. Wird vom Händler zur eindeutigen Identifizierung der Transaktion verwendet.

summary

Kurze, für den Menschen lesbare Zusammenfassung des Vertrags. Zu verwenden, wenn der Vertrag in nur einer Zeile angezeigt werden soll, z. B. in der Transaktionshistorie des Kunden.

timestamp

Zeitpunkt, zu dem das Angebot erstellt wurde.

pay_deadline

Zeitstempel des Zeitpunkts, bis zu dem der Händler möchte, dass die Exchange das aus diesem Vertrag fällige Geld endgültig überweist. Nach Ablauf dieser Frist fasst die Exchange alle Einzahlungen zusammen, bei denen die Verträge die refund_deadline überschritten haben, und führt eine große Überweisung für sie aus. Die Beträge werden auf die Überweisungseinheit abgerundet; wenn der Gesamtbetrag noch unter der Überweisungseinheit liegt, wird er nicht ausgezahlt.

refund_deadline

Zeitstempel, bis zu dem der Händler bereit (und in der Lage) ist, Erstattungen für den Vertrag mit Taler zu geben. Beachten Sie, dass die Taler-Exchange die Zahlung mindestens bis zu dieser Frist auf einem Treuhandkonto hält. Bis zu diesem Zeitpunkt wird der Händler in der Lage sein, eine Nachricht zu unterschreiben, um eine Rückerstattung an den Kunden auszulösen. Nach diesem Zeitpunkt ist eine Rückerstattung an den Kunden nicht mehr möglich. Muss kleiner sein als die pay_deadline.

products

Array der Produkte, die an den Kunden verkauft werden. Jeder Eintrag enthält ein Tupel mit den folgenden Werten:

description

Beschreibung des Produkts.

quantity

Menge der zu versendenden Artikel. Kann eine Einheit (z.B. 1 kg) oder nur die Anzahl angeben.

price

Preis für quantity Einheiten dieses Produkts, die an den angegebenen delivery_location geliefert werden. Beachten Sie, dass die Summe aller Preise in der Regel den Gesamtbetrag des Vertrages ergeben sollte, sie kann aber aufgrund von Rabatten oder weil einzelne Preise nicht verfügbar sind, abweichen.

product_id

Eindeutige ID des Produkts im Katalog des Händlers. Kann im Allgemeinen frei gewählt werden, da sie nur für den Händler von Bedeutung ist, sollte aber eine Zahl im Bereich

sein.

taxes

Karte der anwendbaren Steuern, die vom Händler zu zahlen sind. Die Bezeichnung ist der Name der Steuer, d. h. Mehrwertsteuer, Umsatzsteuer oder Einkommensteuer, und der Wert ist der anwendbare Steuerbetrag. Beliebige Bezeichnungen sind zulässig, solange sie zur Identifizierung der geltenden Steuerregelung verwendet werden. Die Einzelheiten können von der Aufsichtsbehörde festgelegt werden. Dies dient dazu, dem Kunden zu erklären, welche Steuern der Händler zu zahlen beabsichtigt, und kann vom Kunden als Quittung verwendet werden. Die Informationen werden wahrscheinlich auch bei Steuerprüfungen des Händlers verwendet.

delivery_date

Zeitpunkt, zu dem das Produkt an den delivery_location geliefert werden soll.

delivery_location

Dies sollte eine Bezeichnung in der Karte locations ergeben, die angibt, wohin der Gegenstand geliefert werden soll.

Werte können weggelassen werden, wenn sie nicht zutreffend sind. Wenn es sich bei einem Kauf beispielsweise um ein Bündel von Produkten handelt, die keine individuellen Preise oder Produkt-IDs haben, müssen product_id oder price im Vertrag nicht angegeben werden. Ebenso gibt es für virtuelle Produkte, die direkt über den Fulfillment-URI geliefert werden, kein delivery_location.

merchant
address

Dies sollte eine Bezeichnung in der Karte locations ergeben, die angibt, wo sich der Händler befindet.

name

Dies sollte ein für Menschen lesbarer Name für das Geschäft des Händlers sein.

jurisdiction

Dies sollte eine Bezeichnung in der Karte locations ergeben, welche die Gerichtsbarkeit angibt, unter der dieser Vertrag geschlichtet werden soll.

locations

Assoziative Karte der im Vertrag verwendeten Orte. Die Bezeichnungen für die Orte in dieser Karte können frei gewählt und immer dann verwendet werden, wenn ein Ort in anderen Teilen des Vertrages benötigt wird. Auf diese Weise muss derselbe Ort, wenn er mehrfach benötigt wird (z. B. die Geschäftsadresse des Kunden oder des Händlers), nur einmal aufgeführt (und übermittelt) werden und kann ansonsten über die Bezeichnung referenziert werden. Eine nicht erschöpfende Liste von Ortsattributen ist die folgende:

name

Name des Empfängers für die Zustellung, entweder Firmen- oder Personenname.

country

Name des Zustellungslandes, wie er auf einem Postpaket steht, z. B. „Frankreich“.

state

Name des Zustellungsstaats, wie er auf einem Postpaket steht, z. B. „NY“.

region

Name der Zustellregion, wie er auf einem Postpaket steht.

province

Name der zustellenden Provinz, wie er auf einem Postpaket steht.

city

Name des Zustellungsortes, wie er auf einem Postpaket steht.

zip_code

Postleitzahl für die Zustellung, wie sie auf einem Postpaket steht.

street

Straßenname für die Zustellung, wie er auf einem Postpaket steht.

street_number

Straßennummer (Hausnummer) für die Zustellung, wie sie auf einem Postpaket steht.

Bemerkung

Standorte müssen nicht alle diese Felder angeben und können auch zusätzliche Felder haben. Vertragsrenderer müssen mindestens die oben aufgeführten Felder rendern und sollten Felder, die sie nicht verstehen, als Schlüsselwertliste rendern.