3.1.6. De Taler Bestelformule#

The Taler order format describes the JSON that must be POSTed to the merchant backend to create an order. It is the prototype from which the merchant backend will create the actual contract terms.

There are different versions for order format; they are described in detail in the Reference manual.

Notitie

Financiële bedragen worden altijd gespecificeerd als een tekenreeks in het formaat "CURRENCY:DECIMAL_VALUE".

This section provides an overview of the most common fields:

bedrag: Specificeert het totale bedrag dat de klant aan de verkoper moet betalen.

maximumtarief: Dit is het maximale totaalbedrag aan stortingskosten dat de verkoper bereid is te betalen. Als de stortingskosten voor de munten dit bedrag overschrijden, moet de klant dit opnemen in het betalingstotaal. De vergoeding wordt gespecificeerd in hetzelfde formaat als bedrag.

max_kabel_tarief: Maximale overboekingskosten die worden geaccepteerd door de merchant (klantaandeel te delen door de wire_fee_amortization factor, en verder verminderd als stortingskosten lager zijn dan max_fee). Als deze ontbreekt is de standaardwaarde nul.

wire_fee_amortization: Over hoeveel klanttransacties verwacht de merchant gemiddeld wire fees af te schrijven? Als de wire fee van de exchange boven de max_wire_fee ligt, wordt het verschil gedeeld door dit getal om de verwachte bijdrage van de klant aan de wire fee te berekenen. De bijdrage van de klant kan verder worden verminderd met het verschil tussen de max_fee en de som van de werkelijke stortingskosten. Optioneel, standaardwaarde als deze ontbreekt is 1. Nul- en negatieve waarden zijn ongeldig en worden ook geïnterpreteerd als 1.

betaaladres: Welke URL accepteert betalingen. Dit is de URL waar de portemonnee munten POST.

vervulling_url: Naar welke URL moet de portemonnee gaan voor het verkrijgen van de vervulling, bijvoorbeeld de HTML of PDF van een artikel dat is gekocht, of een ordervolgsysteem voor verzendingen, of een eenvoudige, menselijk leesbare webpagina die de status van het contract aangeeft.

order_id: Alfanumerieke identificatiecode, vrij te definiëren door de verkoper. Gebruikt door de verkoper om de transactie uniek te identificeren.

samenvatting: Korte, menselijk leesbare samenvatting van het contract. Te gebruiken wanneer het contract in slechts één regel wordt weergegeven, bijvoorbeeld in de transactiegeschiedenis van de klant.
tijdstempel: Tijd waarop de aanbieding werd gegenereerd.

betaal_deadline: Tijdstempel van het tijdstip waarop de handelaar wil dat de beurs het verschuldigde geld van dit contract definitief overmaakt. Zodra deze deadline verstrijkt, zal de beurs alle deposito’s samenvoegen waarvan de contracten voorbij de refund_deadline zijn en er één grote overboeking voor uitvoeren. Bedragen worden naar beneden afgerond op de overboekingseenheid; als het totaalbedrag nog steeds lager is dan de overboekingseenheid, wordt het niet uitbetaald.

restitutie_deadline: Tijdstempel tot wanneer de verkoper bereid (en in staat) is om terugbetalingen te doen voor het contract met Taler. Merk op dat de Taler exchange de betaling in escrow zal houden tot ten minste deze deadline. Tot die tijd kan de verkoper een bericht ondertekenen om een terugbetaling aan de klant te activeren. Na deze tijd is het niet meer mogelijk om de klant terug te betalen. Moet kleiner zijn dan de pay_deadline.

producten

Matrix van producten die worden verkocht aan de klant. Elk item bevat een tupel met de volgende waarden:

beschrijving: Beschrijving van het product.
hoeveelheid: Hoeveelheid van de items die moeten worden verzonden. Kan een eenheid opgeven (bijv. 1 kg) of alleen het aantal.
prijs: Prijs voor aantal eenheden van dit product verzonden naar de opgegeven delivery_location. Merk op dat meestal de som van alle prijzen moet optellen tot het totale bedrag van het contract, maar het kan anders zijn door kortingen of omdat individuele prijzen niet beschikbaar zijn.
product_id: Uniek ID van het product in de catalogus van de verkoper. Kan over het algemeen vrij gekozen worden omdat het alleen betekenis heeft voor de verkoper, maar moet een getal zijn in het bereik $[0,2^{51})$ .
belastingen: Kaart met toepasselijke belastingen die door de handelaar moeten worden betaald. Het label is de naam van de belasting, bijv. BTW, omzetbelasting of inkomstenbelasting, en de waarde is het toepasselijke belastingbedrag. Merk op dat willekeurige labels zijn toegestaan, zolang ze worden gebruikt om het toepasselijke belastingregime te identificeren. Details kunnen worden gespecificeerd door de regelgever. Dit wordt gebruikt om aan de klant te verklaren welke belastingen de handelaar van plan is te betalen, en kan door de klant als ontvangstbewijs worden gebruikt. De informatie zal waarschijnlijk ook worden gebruikt bij belastingcontroles van de handelaar.
leveringsdatum: Tijd waarop het product moet worden afgeleverd op de delivery_location.
afleverlocatie: Dit moet een label geven in de locaties map, die specificeert waar het item moet worden afgeleverd.

Waarden kunnen worden weggelaten als ze niet van toepassing zijn. Als een aankoop bijvoorbeeld gaat over een bundel producten die geen individuele prijzen of product-ID’s hebben, kunnen de product_id of prijs niet worden gespecificeerd in het contract. Op dezelfde manier is er voor virtuele producten die rechtstreeks via de URI voor uitlevering worden geleverd, geen delivery_location.

koopman

adres: Dit moet een label geven in de locaties map, die aangeeft waar de verkoper zich bevindt.
naam: Dit moet een menselijk leesbare naam zijn voor het bedrijf van de handelaar.
rechtsgebied: Dit moet een label geven in de locaties map, die de jurisdictie specificeert waaronder dit contract bemiddeld moet worden.

locaties

Associatieve kaart van locaties die in het contract worden gebruikt. Labels voor locaties op deze kaart kunnen vrij worden gekozen en gebruikt wanneer een locatie nodig is in andere delen van het contract. Op deze manier, als dezelfde locatie meerdere keren nodig is (zoals het bedrijfsadres van de klant of de handelaar), hoeft deze maar één keer vermeld (en doorgegeven) te worden en kan er anders via het label naar verwezen worden. Een niet-uitputtende lijst van locatieattributen is de volgende:

naam: Naam ontvanger voor levering, bedrijfs- of persoonsnaam.
land: Naam van het land voor bezorging, zoals te vinden op een postpakket, bijv. “Frankrijk”.
staat: Naam van de staat voor bezorging, zoals te vinden op een postpakket, bijvoorbeeld “NY”.
regio: Naam van de regio voor bezorging, zoals te vinden op een postpakket.
provincies: Naam van de provincie van levering, zoals die op een postpakket staat.
stad: Naam van de stad voor bezorging, zoals te vinden op een postpakket.
postcode: Postcode voor bezorging, zoals te vinden op een postpakket.
straat: Straatnaam voor bezorging, zoals te vinden op een postpakket.
straat_nummer: Straatnummer (huisnummer) voor bezorging, zoals te vinden op een postpakket.

Notitie

Locaties zijn niet verplicht om al deze velden te specificeren, en ze mogen ook extra velden hebben. Contractweergevers moeten ten minste de bovenstaande velden weergeven, en moeten velden die ze niet begrijpen weergeven als een sleutelwaardenlijst.