3.1.2. Handelaar API handleiding#

3.1.2.1. Inleiding #

3.1.2.1.1. Over GNU Taler #

GNU Taler is een open protocol voor een elektronisch betalingssysteem met een vrije software referentie-implementatie. GNU Taler biedt veilige, snelle en eenvoudige betalingsverwerking met behulp van goed begrepen cryptografische technieken. GNU Taler staat klanten toe anoniem te blijven, terwijl het er voor zorgt dat handelaren verantwoordelijk gehouden kunnen worden door overheden. GNU Taler is daarom compatibel met anti-witwas (AML) en know-your-customer (KYC) regelgeving, evenals regelgeving voor gegevensbescherming (zoals GDPR).

3.1.2.1.2. Over deze handleiding #

Deze tutorial behandelt hoe je betalingen verwerkt met de GNU Taler Backend. Het publiek voor deze tutorial zijn ontwikkelaars van winkeliers (zoals webwinkels) die bezig zijn GNU Taler te integreren met de klantgerichte Frontend en de personeelsgerichte Backoffice.

In dit hoofdstuk worden enkele basisbegrippen uitgelegd. In het tweede hoofdstuk leer je hoe je basisbetalingen doet.

Deze versie van de tutorial heeft voorbeelden voor Python3. Het gebruikt de requests bibliotheek voor HTTP verzoeken. Versies voor andere talen/omgevingen zijn ook beschikbaar.

Als je enkele eenvoudige, lopende voorbeelden wilt bekijken, bekijk dan deze:

De essay merchant die losse hoofdstukken van een boek verkoopt.
De donatiepagina die donaties voor softwareprojecten accepteert en donatiebewijzen geeft.
De WooCommerce plugin die een uitgebreide integratie is in een webwinkel, inclusief het terugbetalingsproces.

3.1.2.1.3. Overzicht architectuur #

De Taler software stack voor een merchant bestaat uit de volgende hoofdcomponenten:

Een frontend die interageert met de browser van de klant. Met de frontend kan de klant een winkelwagentje samenstellen en een bestelling plaatsen. Na betaling wordt de betreffende bedrijfslogica geactiveerd om de bestelling uit te voeren. Deze component wordt niet meegeleverd met Taler, maar wordt verondersteld te bestaan bij de verkoper. Deze tutorial beschrijft hoe je een Taler frontend ontwikkelt.

Een Taler-specifiek betalingsbackend dat het makkelijk maakt voor de frontend om financiële transacties te verwerken met Taler. Voor deze tutorial gebruik je een publieke sandbox backend. Voor productiegebruik moet je je eigen backend opzetten of iemand anders vragen dit voor je te doen.

De volgende afbeelding illustreert de verschillende interacties van deze sleutelcomponenten:

Het backend biedt ondersteuning voor cryptografische protocollen, slaat Taler-specifieke financiële informatie op en communiceert met de GNU Taler uitwisseling over het internet. Het frontend heeft toegang tot het backend via een RESTful API. Hierdoor hoeft de frontend nooit direct te communiceren met de exchange en heeft ook geen te maken met gevoelige gegevens. In het bijzonder worden de handtekeningsleutels en bankgegevens van de merchant ingekapseld in de Taler backend.

Sommige functionaliteit van de backend (de “publieke interface”) is direct zichtbaar voor de browser van de klant. In de HTTP API worden alle privé eindpunten (voor de Backoffice) voorafgegaan door /private/. Deze tutorial richt zich op de /private/ eindpunten. De publieke interface wordt direct gebruikt door de portemonnee en is niet relevant voor de merchant (behalve dat de API moet worden blootgesteld).

3.1.2.1.4. Publieke Sandbox Backend en Authenticatie #

Hoe het frontend zich authentiseert bij het Taler backend hangt af van de configuratie. Zie Merchant Backend Bedieningshandleiding.

De publieke sandbox backend https://backend.demo.taler.net/instances/sandbox/ gebruikt een API sleutel in de Authorization header. De waarde van deze header moet Bearer secret-token:sandbox zijn voor de publieke sandbox backend.

>>> import requests
>>> requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders",
...              headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Als er een andere HTTP-statuscode dan 200 wordt geretourneerd, is er iets misgegaan. Je moet uitzoeken wat het probleem is voordat je verder gaat met deze tutorial.

De sandbox backend https://backend.demo.taler.net/instances/sandbox/ gebruikt KUDOS als denkbeeldige valuta. Munten in KUDOS kunnen worden opgenomen van https://bank.demo.taler.net/.

3.1.2.1.5. Handelaarsinstanties #

Een enkele Taler merchant backend server kan worden gebruikt door meerdere merchants die afzonderlijke bedrijfsentiteiten zijn. Aan elk van deze afzonderlijke bedrijfsentiteiten wordt een merchant instance toegewezen die wordt geïdentificeerd door een alfanumerieke instance id. Als de instantie wordt weggelaten, wordt de instantie id admin aangenomen.

De volgende merchant instanties zijn geconfigureerd op https://backend.demo.taler.net/:

GNUnet (Het GNUnet project), te bereiken via https://backend.demo.taler.net/instances/gnunet/
FSF (The Free Software Foundation), te bereiken via https://backend.demo.taler.net/instances/fsf/
Tor (The Tor Project), te bereiken via https://backend.demo.taler.net/instances/tor/
admin (Kudos Inc.), bereikbaar via https://backend.demo.taler.net/
sandbox (om te testen.), bereikbaar op https://backend.demo.taler.net/instances/sandbox/

Notitie

Dit zijn fictieve verkopers die gebruikt worden voor onze demonstrators en die niet verbonden zijn aan of officieel goedgekeurd zijn door de respectieve projecten.

Alle eindpunten voor instanties bieden dezelfde API. Welke instantie moet worden gebruikt, wordt dus eenvoudigweg opgenomen in de basis URL van het merchant backend.

3.1.2.2. Merchant Betalingsverwerking #

3.1.2.2.1. Een betalingsopdracht maken #

Betalingen in Taler draaien om een order, dat is een machineleesbare beschrijving van de zakelijke transactie waarvoor de betaling moet worden gedaan. Voordat je als merchant een Taler betaling accepteert, moet je zo’n order aanmaken.

Dit wordt gedaan door een JSON object te POSTEN naar het /private/orders API endpoint van de backend. Ten minste de volgende velden moeten worden opgegeven in het order veld:

bedrag: Het te betalen bedrag, als een string in het formaat CURRENCY:DECIMAL_VALUE, bijvoorbeeld EUR:10 voor 10 euro of KUDOS:1.5 voor 1.5 KUDOS.
samenvatting: Een door mensen leesbare samenvatting van waar de betaling over gaat. De samenvatting moet kort genoeg zijn om in titels te passen, maar er wordt geen harde limiet opgelegd.
fulfillment_url: Een URL die wordt weergegeven zodra de betaling is voltooid. Voor digitale goederen moet dit een pagina zijn die het gekochte product weergeeft. Bij een succesvolle betaling voegt de portemonnee automatisch de order_id toe als een query parameter, evenals de session_sig voor sessie-gebonden betalingen (hieronder besproken).

Bestellingen kunnen veel meer velden hebben, zie De Taler Bestelopmaak. Bij het POSTEN van een bestelling kun je ook extra details opgeven, zoals een overschrijding voor de terugbetalingsduur en instructies voor voorraadbeheer. Deze zijn zelden nodig en worden niet in deze tutorial behandeld; raadpleeg de referentiehandleiding voor meer informatie.

Een minimaal Python-fragment voor het maken van een bestelling ziet er als volgt uit:

>>> 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]>

De backend vult een aantal gegevens in die ontbreken in de bestelling, zoals het adres van de verkoper. De volledige details worden de contractvoorwaarden genoemd.

Notitie

Het bovenstaande verzoek schakelt het gebruik van claim tokens uit door de create_token optie op false te zetten. Als je claim tokens nodig hebt, moet je de code aanpassen om de taler://pay/ URI te construeren die hieronder wordt gegeven om het claim token op te nemen.

Na een succesvolle POST naar /private/orders, zal een JSON met alleen een order_id veld met een string die de order ID weergeeft worden geretourneerd. Als je ook een claim token krijgt, controleer dan of je het verzoek hebt gebruikt zoals hierboven beschreven.

Samen met de merchant instance, identificeert de order id uniek de order binnen een merchant backend. Met behulp van de order-ID, kun je triviaal de respectievelijke taler://pay/ URI construeren die moet worden verstrekt aan de portemonnee. Laat example.com de domeinnaam zijn waar de publieke eindpunten van de instantie bereikbaar zijn. De Taler pay URI is dan simpelweg taler://pay/example.com/$ORDER_ID/ waarbij $ORDER_ID moet worden vervangen door de ID van de geretourneerde order.

Je kunt de taler:// URI als doel van een link zetten om de Taler portemonnee te openen via het taler:// schema, of het in een QR-code zetten. Voor een webwinkel is de eenvoudigste manier echter om de browser door te sturen naar https://example.com/orders/$ORDER_ID. Die pagina activeert dan de Taler portemonnee. Hier genereert de backend de juiste logica om de portemonnee te activeren, waarbij de verschillende soorten bestaande Taler portemonnees worden ondersteund. In plaats van de bovenstaande URL met de hand op te bouwen, is het ook mogelijk om deze te verkrijgen door te controleren op de betaalstatus zoals beschreven in de volgende sectie.

Als je deze URL handmatig aanmaakt, zorg er dan voor dat je het claim token opgeeft (tenzij het was uitgeschakeld) en als het backend zonder TLS draait om taler+http:// te gebruiken (merk op dat dit laatste alleen wordt ondersteund door wallets die in debug modus draaien).

Notitie

Een triviale manier om de juiste payment_redirect_url te verkrijgen is door de status van de betaling te controleren (zie hieronder). Dus als je nog steeds niet zeker weet hoe je dit moet construeren, kun je dit gewoon aan de backend vragen. In productie zou je het echter waarschijnlijk handmatig moeten maken en het extra verzoek aan de backend vermijden.

3.1.2.2.2. Betalingsstatus controleren en om betaling vragen #

Gegeven het order ID, kan de status van een betaling worden gecontroleerd met het /private/orders/$ORDER_ID eindpunt. Als de betaling nog moet worden voltooid door de klant, zal /private/orders/$ORDER_ID de frontend een URL geven (onder de naam payment_redirect_url) die de portemonnee van de klant zal triggeren om de betaling uit te voeren. Dit is in principe de https://example.com/orders/$ORDER_ID URL die we hierboven hebben besproken.

>>> 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())

Als het order_status veld in het antwoord betaald is, krijg je geen payment_redirect_url en in plaats daarvan informatie over de betaalstatus, inclusief:

contract_voorwaarden: De volledige contractvoorwaarden van de bestelling.
refunded: true als een (mogelijk gedeeltelijke) terugbetaling is toegekend voor deze aankoop.
terugbetaald_bedrag: Bedrag dat is terugbetaald

Zodra de frontend heeft bevestigd dat de betaling succesvol was, moet het meestal de bedrijfslogica voor de merchant activeren om de verplichtingen van de merchant onder het contract na te komen.

Notitie

U hoeft geen query te blijven uitvoeren om wijzigingen in de transactiestatus van de bestelling op te merken. De endpoints ondersteunen lange polling, geef gewoon een timeout_ms query parameter op met hoe lang je maximaal wilt wachten tot de orderstatus verandert in betaald.

3.1.2.3. Restituties geven #

Een terugbetaling in GNU Taler is een manier om een betaling “ongedaan te maken”. Het moet worden goedgekeurd door de verkoper. Restituties kunnen voor elke fractie van het oorspronkelijk betaalde bedrag zijn, maar ze kunnen niet hoger zijn dan de oorspronkelijke betaling. Terugbetalingen zijn beperkt in de tijd en kunnen alleen plaatsvinden terwijl de exchange het geld voor een bepaalde betaling in escrow houdt. De tijd waarin een terugbetaling mogelijk is, kan worden geregeld door de refund_deadline in een order in te stellen. De standaardwaarde voor deze terugbetalingstermijn wordt gespecificeerd in de configuratie van de backend van de merchant.

De frontend kan de merchant backend opdracht geven om een restitutie te autoriseren door POST naar het /private/orders/$ORDER_ID/refund eindpunt te sturen.

Het refund request JSON object heeft slechts twee velden:

terugbetaling: Bedrag dat moet worden terugbetaald. Als voor dezelfde bestelling al eerder een terugbetaling is gedaan, moet het nieuwe bedrag hoger zijn, anders heeft de bewerking geen effect. De waarde geeft het totale terug te betalen bedrag aan, niet een verhoging van de terugbetaling.
reden: Menselijk leesbare rechtvaardiging voor de terugbetaling. De reden wordt alleen gebruikt door de Back Office en is niet zichtbaar voor de klant.

Als het verzoek succesvol is (aangegeven met HTTP-statuscode 200), bevat het antwoord een taler_refund_uri. De frontend moet de browser van de klant omleiden naar die URL zodat de terugbetaling kan worden verwerkt door de portemonnee.

Dit stukje code illustreert het geven van een restitutie:

>>> import requests
>>> refund_req = dict(refund="KUDOS:10",
...                   reason="Customer did not like the product")
>>> requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders/"
...               + order_id + "/refund", json=refund_req,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Notitie

Na het toekennen van een restitutie zal het publieke https://example.com/orders/$ORDER_ID eindpunt zijn portemonnee-interactie veranderen van het vragen om betaling naar het aanbieden van een restitutie. Frontends kunnen browsers dus weer omleiden naar dit eindpunt. Hiervoor moet echter een h_contract veld worden toegevoegd (?h_contract=$H_CONTRACT) omdat het publieke eindpunt dit nodig heeft om de cliënt te authenticeren. De vereiste $H_CONTRACT waarde wordt geretourneerd in het restitutie antwoord onder het h_contract veld.

3.1.2.4. URL’s voor herkoop en uitvoering #

Een mogelijk probleem voor verkopers die toegang tot digitale artikelen verkopen, is dat een klant voor een artikel op het ene apparaat heeft betaald, maar het vervolgens op een ander apparaat wil lezen, mogelijk een apparaat waarop niet eens een Taler-portemonnee is geïnstalleerd.

Natuurlijk wordt de klant dan eerst nog gevraagd om opnieuw voor het artikel te betalen. Als de klant vervolgens de taler:// link opent in de portemonnee die eerder voor het artikel heeft betaald (bijvoorbeeld door de QR-code op de desktop te scannen met de Android App), zal de portemonnee het contract claimen, detecteren dat de vervulling URL identiek is aan een waarvoor het al een betaling heeft gedaan in het verleden, en repurchase redirection initiëren: Hier zal de portemonnee contact opnemen met de verkoper en de vorige betaling herhalen, behalve deze keer met behulp van de (huidige) sessie-ID van de browser (het leert de sessie-ID van de QR-code).

De merchant backend werkt dan de sessie ID van de bestaande bestelling bij naar de huidige sessie ID van de browser. Wanneer de betaalstatus voor de “nieuwe” onbetaalde bestelling wordt gecontroleerd (of al in long-polling is), detecteert de backend dat er voor de sessie ID en fulfillment URL van de browser een bestaand betaald contract is. Het vertelt de browser dan om onmiddellijk door te verwijzen naar de URL waar het reeds betaalde artikel beschikbaar is.

Om ervoor te zorgen dat dit mechanisme werkt zoals het bedoeld is, moeten winkeliers ervoor zorgen dat ze niet dezelfde URL gebruiken voor verschillende producten of voor fysieke producten waarvan verwacht kan worden dat klanten het artikel herhaaldelijk kopen. Op dezelfde manier is het van cruciaal belang dat verkopers consequent dezelfde URL gebruiken voor hetzelfde digitale product als ze een herhalingsaankoop willen detecteren.

Merk op dat het veranderen van de sessie-ID naar een ander apparaat de betrokkenheid vereist van de portemonnee die de betaling heeft gedaan, waardoor de mogelijkheid van het breed delen van de digitale aankopen redelijk wordt beperkt. Detectie van terugkopen wordt ook alleen gedaan voor HTTP(S) vervulling URLs. Dit betekent in het bijzonder dat URI’s zoals taler://fulfillment-success/$MESSAGE niet worden beschouwd als een bron waarvoor je kunt betalen en dus niet uniek hoeven te zijn.

3.1.2.5. Gevorderde onderwerpen #

3.1.2.5.1. Sessiegebonden betalingen #

Soms is het niet voldoende om te controleren of een bestelling is betaald. Als je bijvoorbeeld toegang tot online media verkoopt, wil de uitgever dat elke klant voor precies hetzelfde product betaalt. Taler ondersteunt dit model door de handelaar toe te staan om te controleren of het “betalingsbewijs” beschikbaar is op het huidige apparaat van de gebruiker. Dit voorkomt dat gebruikers gemakkelijk mediatoegang kunnen delen door een link naar de fulfillmentpagina door te sturen. Natuurlijk zouden geavanceerde gebruikers ook betalingsbewijzen kunnen delen, maar dit is niet zo eenvoudig als het delen van een link, en in dit geval is de kans groter dat ze gewoon de media direct delen.

Om deze functie te gebruiken, moet de verkoper eerst de huidige browser van de gebruiker een kortstondige session_id toewijzen, meestal via een sessiecookie. Bij het uitvoeren of opnieuw uitvoeren van een betaling ontvangt de portemonnee een extra handtekening (session_sig). Deze handtekening bevestigt dat de portemonnee een betalingsbewijs heeft getoond voor de betreffende bestelling in de huidige sessie.

Sessiegebonden betalingen worden geactiveerd door de session_id parameter door te geven aan het /check-payment eindpunt. De portemonnee zal dan doorsturen naar de fulfillment pagina, maar een extra session_sig parameter toevoegen. De frontend kan /check-payment bevragen met zowel de session_id als de session_sig om te controleren of de handtekening correct is.

De laatste sessie-ID die met succes is gebruikt om te bewijzen dat het betalingsbewijs in de portemonnee van de gebruiker zit, is ook beschikbaar als last_session_id in het antwoord op /check-payment.

3.1.2.5.2. Productidentificatie #

In sommige situaties heeft de gebruiker betaald voor een digitaal goed, maar weet de frontend niet de exacte ID van de bestelling en kan dus de portemonnee geen opdracht geven om het bestaande betalingsbewijs te onthullen. Dit komt vaak voor bij eenvoudige winkels zonder inlogsysteem. In dit geval wordt de gebruiker opnieuw om betaling gevraagd, ook al heeft hij het product al gekocht.

Om de portemonnee in plaats daarvan het bestaande betalingsbewijs te laten vinden, moet de winkel een unieke vervulling-URL gebruiken voor elk product. Dan moet de frontend een extra resource_url parameter geven aan /check-payment. Het moet deze unieke URL voor het product identificeren. De portemonnee zal dan controleren of het al eerder heeft betaald voor een contract met dezelfde resource_url, en zo ja, de vorige betaling opnieuw uitvoeren.

3.1.2.5.3. De Taler Bestelformule #

Een Taler order kan veel details over de betaling specificeren. Deze sectie beschrijft elk van de velden in detail.

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

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.

Handelaar API handleiding

Inhoud

3.1.2. Handelaar API handleiding#