De Taler Bestelformule

3.1.6. De Taler Bestelformule#

Het Taler-bestelformaat beschrijft de JSON die moet worden gePOSTed naar de verkopersbackend om een bestelling aan te maken. Het is het prototype van waaruit de verkopersbackend de werkelijke contractvoorwaarden zal creëren.

Er zijn verschillende versies voor het bestelformaat; ze worden in detail beschreven in de Referentiehandleiding.

Notitie

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

Dit gedeelte geeft een overzicht van de meest voorkomende velden:

amount

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

max_fee

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_wire_fee

Maximale overschrijvingskosten die worden geaccepteerd door de verkoper (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 verkoper gemiddeld overschrijvingskosten af te schrijven? Als de overschrijvingskosten van de exchange boven de max_wire_fee liggen, wordt het verschil gedeeld door dit getal om de verwachte bijdrage van de klant aan de overschrijvingskosten 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.

pay_url

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

fulfillment_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.

summary

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.

timestamp

Tijd waarop de aanbieding werd gegenereerd.

pay_deadline

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

refund_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.

products

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

description

Beschrijving van het product.

quantity

Hoeveelheid van de items die moeten worden verzonden. Kan een eenheid opgeven (bijv. 1 kg) of alleen het aantal.

price

Prijs voor quantity 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

.

taxes

Kaart met toepasselijke belastingen die door de verkoper 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 verkoper 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 verkoper.

delivery_date

Tijd waarop het product moet worden afgeleverd op de delivery_location.

delivery_location

Dit moet een label geven in de locations 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 price niet worden gespecificeerd in het contract. Op dezelfde manier is er voor virtuele producten die rechtstreeks via de fulfillment-URI worden geleverd, geen delivery_location.

merchant
address

Dit moet een label geven in de locations map, die aangeeft waar de verkoper zich bevindt.

name

Dit moet een menselijk leesbare naam zijn voor het bedrijf van de verkoper.

jurisdiction

Dit moet een label geven in de locations map, die de jurisdictie specificeert waaronder dit contract bemiddeld moet worden.

locations

Associatieve kaart van locaties die in het contract worden gebruikt. Labels voor locaties in deze map 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 verkoper), 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:

name

Naam ontvanger voor levering, bedrijfs- of persoonsnaam.

country

Naam van het land voor bezorging, zoals te vinden op een postpakket, bijv. “Frankrijk”.

state

Naam van de staat voor bezorging, zoals te vinden op een postpakket, bijvoorbeeld “NY”.

region

Naam van de regio voor bezorging, zoals te vinden op een postpakket.

province

Naam van de provincie van levering, zoals die op een postpakket staat.

city

Naam van de stad voor bezorging, zoals te vinden op een postpakket.

zip_code

Postcode voor bezorging, zoals te vinden op een postpakket.

street

Straatnaam voor bezorging, zoals te vinden op een postpakket.

street_number

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.