Kereskedői API bemutató

3.1.2. Kereskedői API bemutató#

3.1.2.1. Bevezetés#

3.1.2.1.1. A GNU Talerről#

A GNU Taler egy elektronikus fizetési rendszer nyílt protokollja, szabad szoftveres referencia implementációval. A GNU Taler biztonságos, gyors és egyszerű fizetési folyamatot kínál, jól ismert kriptográfiai technikákat használva. A GNU Taler lehetővé teszi az ügyfelek számára, hogy névtelenek maradjanak, miközben biztosítja, hogy a kereskedők a kormányok által felelősségre vonhatók legyenek. Ezért a GNU Taler kompatibilis a pénzmosás elleni (AML) és a know-your-customer (KYC) szabályozással, valamint az adatvédelmi szabályozással (mint például a GDPR).

3.1.2.1.2. Erről a bemutatóról#

Ez a bemutató a GNU Taler kereskedői Backend használatával történő fizetési műveletekkel foglalkozik. A bemutató célközönsége a kereskedők (például webáruházak) fejlesztői, akik a GNU Taler integrálásán dolgoznak az ügyfélre néző Frontenddel és a személyzetre néző Backoffice-zal.

Ez a fejezet néhány alapfogalmat ismertet. A második fejezetben megtanulja, hogyan végezhet alapvető kifizetéseket.

A bemutató ezen verziója Python3-ra tartalmaz példákat. A requests könyvtárat használja a HTTP-kérésekhez. Más nyelvekre/környezetekre készült változatok is rendelkezésre állnak.

Ha szeretnél néhány egyszerű, futó példát látni, nézd meg ezeket:

3.1.2.1.3. Építészeti áttekintés#

A Taler szoftvercsomag egy kereskedő számára a következő fő összetevőkből áll:

  • Frontend, amely kölcsönhatásba lép az ügyfél böngészőjével. A frontend lehetővé teszi a vásárló számára, hogy kosarat építsen és rendelést adjon le. Fizetéskor elindítja a megfelelő üzleti logikát a megrendelés teljesítéséhez. Ez a komponens nem tartozik a Talerhez, hanem feltételezhetően a kereskedőnél van. Ez a bemutató leírja, hogyan kell kifejleszteni egy Taler frontendet.

  • Egy Taler-specifikus fizetési backend, amely megkönnyíti a frontend számára a pénzügyi tranzakciók Talerrel történő feldolgozását. Ehhez a bemutatóhoz egy nyilvános sandbox backendet fog használni. Természetes használathoz vagy saját backendet kell létrehoznia, vagy meg kell kérnie egy másik személyt, hogy ezt megtegye ön helyett.

A következő kép e kulcsfontosságú összetevők különböző kölcsönhatásait szemlélteti:

../../_images/arch-api.png

A háttértár biztosítja a kriptográfiai protokolltámogatást, tárolja a Taler-specifikus pénzügyi információkat, és kommunikál a GNU Taler csereprogrammal az interneten keresztül. A frontend egy RESTful API-n keresztül fér hozzá a backendhez. Ennek eredményeképpen a frontendnek soha nem kell közvetlenül kommunikálnia a tőzsdével, és nem is kezel érzékeny adatokat. Különösen a kereskedő aláírási kulcsai és bankszámlaadatai vannak a Taler backendben kapszulázva.

A háttértár egyes funkciói (a „nyilvános interfész”) közvetlenül az ügyfél böngészője számára is elérhetőek. A HTTP API-ban az összes privát végpont (a Backoffice számára) a /private/ előtaggal van ellátva. Ez a bemutató a /private/ végpontokra összpontosít. A nyilvános interfészt közvetlenül a pénztárca használja, és nem releváns a kereskedő számára (azon kívül, hogy az API-t ki kell tenni).

3.1.2.1.4. Nyilvános Sandbox Backend és hitelesítés#

A konfigurációtól függ, hogy a frontend hogyan hitelesíti magát a Taler backendhez. Lásd: Merchant Backend Operator Manual.

A nyilvános homokozós backend https://backend.demo.taler.net/instances/sandbox/ egy API-kulcsot használ az Authorization fejlécben. Ennek a fejlécnek az értékének Bearer secret-token:sandbox kell lennie a nyilvános homokozós backend esetében.

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

Ha a 200-tól eltérő HTTP státuszkódot kap vissza, akkor valami rosszul sült el. Mielőtt folytatná ezt a bemutatót, ki kell találnia, mi a probléma.

A sandbox backend https://backend.demo.taler.net/instances/sandbox/ a KUDOS-t használja képzeletbeli valutaként. A „KUDOS”-ban denominált érméket a https://bank.demo.taler.net/ oldalon lehet felvenni.

3.1.2.1.5. Kereskedői példányok#

Egyetlen Taler kereskedői backend-kiszolgálót több kereskedő is használhat, amelyek különálló üzleti egységek. Mindegyik ilyen különálló üzleti egységhez egy kereskedői példány tartozik, amelyet egy alfanumerikus instance id azonosít. Ha a példányt nem adjuk meg, akkor a admin példányazonosítót vesszük fel.

A következő kereskedői példányok vannak konfigurálva a https://backend.demo.taler.net/ oldalon:

Megjegyzés

Ezek fiktív kereskedők, akiket a bemutatóinkhoz használunk, és nem kapcsolódnak az adott projektekhez, illetve nem hagyják jóvá őket hivatalosan.

A példányok összes végpontja ugyanazt az API-t kínálja. Így azt, hogy melyik példányt kell használni, egyszerűen csak a kereskedői háttértár alap-URL-je tartalmazza.

3.1.2.2. Kereskedői fizetés feldolgozása#

3.1.2.2.1. Fizetési megbízás létrehozása#

A Talerben a fizetések egy megbízás körül forognak, amely egy gépileg olvasható leírása annak az üzleti tranzakciónak, amelyre a fizetést teljesíteni kell. Mielőtt kereskedőként elfogadna egy Taler-fizetést, létre kell hoznia egy ilyen megbízást.

Ez egy JSON objektum POSTolásával történik a backend /private/orders API végpontjára. A rendelés mezőn belül legalább a következő mezőket kell megadni:

  • összeg: A fizetendő összeg, egy karakterlánc formájában, a CURRENCY:DECIMAL_VALUE formátumban, például EUR:10 10 euróért vagy KUDOS:1.5 1.5 KUDOS-ért.

  • „Összefoglaló”: Ember által olvasható összefoglaló arról, hogy miről szól a fizetés. Az összefoglalónak elég rövidnek kell lennie ahhoz, hogy beleférjen a címekbe, bár nincs szigorú korlát.

  • fulfillment_url: URL, amely a fizetés befejezése után jelenik meg. Digitális áruk esetében ennek egy olyan oldalnak kell lennie, amely megjeleníti a megvásárolt terméket. Sikeres fizetés esetén a pénztárca automatikusan hozzáadja a order_id lekérdezési paraméterként, valamint a session_sig a munkamenethez kötött fizetések esetén (lásd alább).

A megrendeléseknek több mezője is lehet, lásd a A Taler megrendelés formátuma. A megrendelés POSTolásakor további részleteket is megadhat, például a visszatérítés időtartamának felülbírálását és a készletkezelésre vonatkozó utasításokat. Ezekre ritkán van szükség, és ebben a bemutatóban nem tárgyaljuk őket; a részletekért lásd a Hivatkozási kézikönyv.

Egy minimális Python részlet egy rendelés létrehozásához így nézne ki:

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

A backend kitölti a megrendelésből hiányzó néhány adatot, például a kereskedői példány címét. A teljes részleteket szerződési feltételeknek nevezzük.

Megjegyzés

A fenti kérés letiltja az igénylési tokenek használatát a create_token opció false értékre állításával. Ha igénylési tokenekre van szükség, akkor az alábbiakban megadott taler://pay/ URI kódot úgy kell módosítani, hogy az tartalmazza az igénylési tokent.

Miután sikeresen POST```oltunk a ``/private/orders-be, egy JSON-t kapunk vissza, amely csak egy order_id mezőt tartalmaz a rendelés azonosítóját jelző karakterlánccal. Ha egy igénylési tokent is kap, kérjük, ellenőrizze, hogy a fent leírtak szerint használta-e a kérést.

A kereskedő „instancia” azonosítójával együtt a rendelés azonosítója egyedileg azonosítja a rendelést a kereskedői háttértárban. A rendelés azonosítójának felhasználásával triviálisan meg lehet alkotni a megfelelő taler://pay/ URI-t, amelyet a pénztárcának kell megadni. Legyen example.com az a tartománynév, ahol a példány nyilvános végpontjai elérhetőek. A Taler pay URI ekkor egyszerűen taler://pay/example.com/$ORDER_ID/`, ahol a $ORDER_ID-t a visszaküldött rendelés azonosítójával kell helyettesíteni.

A taler:// URI-t egy link célpontjaként használhatja a Taler tárca megnyitására a taler:// sémán keresztül, vagy egy QR-kódba helyezheti. Egy webshop esetében azonban a legegyszerűbb, ha egyszerűen átirányítja a böngészőt a https://example.com/orders/$ORDER_ID címre. Ez az oldal ezután elindítja a Taler pénztárcát. Itt a backend generálja a megfelelő logikát a tárca kiváltásához, támogatva a létező különböző típusú Taler tárcákat. Ahelyett, hogy a fenti URL-t kézzel szerkesztenénk, a fizetési státusz ellenőrzése révén is megkaphatjuk, ahogyan azt a következő szakaszban leírtuk.

Ha kézzel állítod össze ezt az URL-t, győződj meg róla, hogy megadod az igénylési tokent (hacsak nem tiltottad le), és ha a háttértár TLS nélkül fut, akkor használd a taler+http:// (vedd figyelembe, hogy ez utóbbit csak a debug módban futó pénztárcák támogatják).

Megjegyzés

A helyes payment_redirect_url elérésének triviális módja a fizetés státuszának ellenőrzése (lásd alább). Ha tehát még mindig bizonytalan vagy abban, hogyan kell ezt megkonstruálni, egyszerűen megkérheted a backendet, hogy tegye meg helyetted. Termelésben azonban valószínűleg kézzel kell megkonstruálnod, és elkerülni a backendhez intézett extra kérést.

3.1.2.2.2. Fizetési állapot ellenőrzése és fizetési felszólítás#

A rendelés azonosítójának megadásával a fizetés állapota ellenőrizhető a /private/orders/$ORDER_ID végponttal. Ha a fizetést még nem fejezte be a vásárló, a /private/orders/$ORDER_ID egy URL-t ad a frontendnek (payment_redirect_url néven), amely elindítja a vásárló pénztárcáját a fizetés végrehajtására. Ez lényegében a fentebb tárgyalt https://example.com/orders/$ORDER_ID URL.

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

Ha a „order_status” mező a válaszban „paid”, akkor nem a „payment_redirect_url”-t kapja meg, hanem a fizetés státuszára vonatkozó információkat, beleértve:

  • contract_terms: A megrendelés teljes szerződési feltételei.

  • refunded: true, ha (esetleg részleges) visszatérítés történt a vásárlásra.

  • refunded_amount: Visszatérített összeg

Miután a frontend megerősítette, hogy a fizetés sikeres volt, általában a kereskedőnek el kell indítania az üzleti logikát, hogy teljesítse a kereskedő szerződéses kötelezettségeit.

Megjegyzés

Nem kell folyamatosan lekérdezni, hogy észrevegye a megrendelés tranzakciós státuszának változásait. A végpontok támogatják a hosszú lekérdezést, egyszerűen adjuk meg a timeout_ms lekérdezési paramétert, amelyben megadjuk, hogy legfeljebb mennyi ideig szeretnénk várni, amíg a megrendelés státusza paid-re változik.

3.1.2.3. Visszatérítés nyújtása#

A visszatérítés a GNU Talerben a fizetés „visszavonásának” módja. Ezt a kereskedőnek kell engedélyeznie. A visszatérítés az eredetileg kifizetett összeg bármely töredékére vonatkozhat, de nem haladhatja meg az eredeti kifizetés összegét. A visszatérítések időben korlátozottak, és csak addig történhetnek, amíg a pénzváltó letétben tartja az adott kifizetéshez tartozó pénzeszközöket. A visszatérítés lehetséges időtartamát a refund_deadline beállításával lehet szabályozni a megbízásban. A visszatérítési határidő alapértelmezett értéke a kereskedő backendjének konfigurációjában van megadva.

A frontend utasíthatja a kereskedő backendjét, hogy engedélyezze a visszatérítést a POST végpontra történő /private/orders/$ORDER_ID/refund végponttal.

A visszatérítési kérelem JSON objektumának csak két mezője van:

  • visszatérítés: Visszatérítendő összeg. Ha ugyanarra a megrendelésre már engedélyeztek egy korábbi visszatérítést, az új összegnek magasabbnak kell lennie, különben a műveletnek nincs hatása. Az érték a visszatérítendő teljes összeget jelzi, nem a visszatérítés növelését.

  • reason: Ember által olvasható indoklás a visszatérítéshez. Az indoklást csak a Back Office használja, és az ügyfél nem látja meg.

Ha a kérés sikeres (ezt a 200-as HTTP státuszkód jelzi), a válasz tartalmaz egy taler_refund_uri kódot. A frontendnek át kell irányítania az ügyfél böngészőjét erre az URL-re, hogy a pénztárca feldolgozhassa a visszatérítést.

Ez a kódrészlet a visszatérítés megadását szemlélteti:

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

Megjegyzés

A visszatérítés megadása után a nyilvános https://example.com/orders/$ORDER_ID végpont a pénztárca interakcióját a fizetés kéréséről visszatérítés felajánlására változtatja. Így a frontendek ismét átirányíthatják a böngészőket erre a végpontra. Ehhez azonban egy h_contract mezőt kell hozzáadni (?h_contract=$H_CONTRACT), mivel a nyilvános végpontnak szüksége van rá az ügyfél hitelesítéséhez. A szükséges $H_CONTRACT értéket a visszatérítési válaszban a h_contract mező alatt kapjuk vissza.

3.1.2.4. Visszavásárlás észlelése és teljesítési URL-ek#

A digitális cikkekhez való hozzáférést értékesítő kereskedők számára problémát jelenthet, hogy a vásárló fizetett egy cikkért egy eszközön, de aztán egy másik eszközön szeretné elolvasni, esetleg olyan eszközön, amelyen nincs is telepítve Taler pénztárca.

Természetesen ezen a ponton a vásárlót először még mindig arra kérnék, hogy fizessen újra a cikkért. Ha az ügyfél ezután megnyitja a taler:// linket abban a pénztárcában, amely korábban fizetett a cikkért (például a QR-kód beolvasásával az asztali számítógépen az Android alkalmazással), a pénztárca igényt tart a szerződésre, felismeri, hogy a teljesítési URL azonos azzal, amelyért korábban már fizetett, és újravásárlási átirányítást kezdeményez: Itt a tárca kapcsolatba lép a kereskedővel, és újrajátssza a korábbi fizetést, csak ezúttal a böngésző (aktuális) munkamenet-azonosítóját használja (a munkamenet-azonosítót a QR-kódból tanulja meg).

A kereskedői háttértár ezután frissíti a meglévő megrendelés munkamenet-azonosítóját a böngésző aktuális munkamenet-azonosítójára. Amikor az „új” nem fizetett megrendelés fizetési státuszát ellenőrzik (vagy már a hosszú lekérdezés során), a backend észleli, hogy a böngésző session ID-je és teljesítési URL-je esetében van egy meglévő fizetett szerződés. Ezután utasítja a böngészőt, hogy azonnal irányítsa át a teljesítési URL-re, ahol a már kifizetett cikk elérhető.

Annak érdekében, hogy ez a mechanizmus a terveknek megfelelően működjön, a kereskedőknek ügyelniük kell arra, hogy ne használják ugyanazt a teljesítési URL-címet különböző termékekhez vagy olyan fizikai termékekhez, amelyek esetében a vásárlók várhatóan többször is megvásárolják a terméket. Hasonlóképpen alapvető fontosságú, hogy a kereskedők következetesen ugyanazt a teljesítési URL-t használják ugyanazon digitális termékhez, ahol az ismételt vásárlás észlelése kívánatos.

Megjegyzendő, hogy a munkamenet-azonosító másik eszközre történő átállításához a fizetést végző pénztárca bevonása szükséges, ami ésszerűen korlátozza a digitális vásárlások széles körű megosztásának lehetőségét. A visszavásárlás észlelése szintén csak a HTTP(S) teljesítési URL-ek esetében történik. Ez különösen azt jelenti, hogy az olyan teljesítési URI-k, mint a taler://fulfillment-success/$MESSAGE nem minősülnek olyan erőforrás azonosításának, amelyért fizetni lehet, és így nem kell egyedinek lenniük.

3.1.2.5. Haladó témák#

3.1.2.5.1. Munkamenethez kötött kifizetések#

Néha nem elég ellenőrizni, hogy a megrendelés kifizetésre került-e. Például az online médiához való hozzáférés értékesítése esetén a kiadó azt szeretné, ha minden egyes vásárló pontosan ugyanazt a terméket fizetné ki. A Taler támogatja ezt a modellt azzal, hogy a mechant ellenőrizheti, hogy a „fizetési bizonylat” elérhető-e a felhasználó aktuális eszközén. Ez megakadályozza, hogy a felhasználók egyszerűen megosszák a médiához való hozzáférést a teljesítési oldalra mutató link továbbításával. Természetesen a kifinomult felhasználók a fizetési bizonylatokat is megoszthatnák, de ez nem olyan egyszerű, mint egy link megosztása, és ebben az esetben valószínűbb, hogy csak közvetlenül a médiát osztják meg.

E funkció használatához a kereskedőnek először a felhasználó aktuális böngészőjéhez kell rendelnie egy efemer „session_id”-t, általában egy munkamenet-süti segítségével. A fizetés végrehajtásakor vagy újrajátszásakor a pénztárca kap egy további aláírást (session_sig). Ez az aláírás igazolja, hogy a pénztárca az aktuális munkamenetben az adott megbízásról szóló fizetési bizonylatot mutatott.

A munkamenethez kötött fizetéseket a „session_id” paraméter átadásával lehet elindítani a „check-payment” végponton. A pénztárca ezután átirányít a teljesítési oldalra, de egy további session_sig paramétert is tartalmaz. A frontend lekérdezheti a /check-payment-t mind a session_id, mind a session_sig értékkel, hogy ellenőrizze az aláírás helyességét.

Az utolsó munkamenet azonosítója, amelyet sikeresen használtak annak bizonyítására, hogy a fizetési bizonylat a felhasználó pénztárcájában van, szintén elérhető last_session_id néven a /check-payment válaszban.

3.1.2.5.2. Termék azonosítása#

Bizonyos helyzetekben előfordulhat, hogy a felhasználó már fizetett valamilyen digitális áruért, de a frontend nem ismeri a pontos rendelési azonosítót, és így nem tudja utasítani a pénztárcát, hogy mutassa meg a meglévő fizetési bizonylatot. Ez a bejelentkezési rendszer nélküli egyszerű üzleteknél gyakori. Ebben az esetben a felhasználót újra felszólítanák a fizetésre, annak ellenére, hogy már megvásárolta a terméket.

Ahhoz, hogy a pénztárca a meglévő fizetési bizonylatot megtalálja, az üzletnek minden termékhez egyedi teljesítési URL-t kell használnia. Ezután a frontendnek egy további resource_url paramétert kell megadnia a /check-payment paraméterhez. Ennek azonosítania kell ezt az egyedi teljesítési URL-t a termékhez. A pénztárca ezután ellenőrzi, hogy fizetett-e már korábban egy szerződésért ugyanazzal a resource_url-rel, és ha igen, akkor lejátssza az előző fizetést.

3.1.2.5.3. A Taler rendelési formátum#

A Taler megbízás számos részletet megadhat a fizetéssel kapcsolatban. Ez a szakasz részletesen ismerteti az egyes mezőket.

A pénzügyi összegeket mindig karakterláncként kell megadni a "CURRENCY:DECIMAL_VALUE" formátumban.

összeg

Megadja a vásárló által a kereskedőnek fizetendő teljes összeget.

max_fee

Ez a kereskedő által fizetni hajlandó betéti díjak maximális összege. Ha az érmék letéti díjai meghaladják ezt az összeget, akkor azt a vásárlónak bele kell számolnia a fizetés végösszegébe. A díj megadása az összeg esetében használt formátumban történik.

max_wire_fee

A kereskedő által elfogadott maximális átutalási díj (az ügyfél részesedését el kell osztani a wire_fee_amortization tényezővel, és tovább kell csökkenteni, ha a befizetési díjak a max_fee alatt vannak). Ha hiányzik, az alapértelmezett érték nulla.

wire_fee_amortizáció

Hány ügyféltranzakció során várhatóan átlagosan mennyi átutalási díj amortizálódik a kereskedőnél? Ha a tőzsdei átutalási díj a max_wire_fee fölött van, a különbséget el kell osztani ezzel a számmal, hogy kiszámítsuk a várható ügyfél hozzájárulását az átutalási díjhoz. Az ügyfél hozzájárulása tovább csökkenthető a max_díj és a tényleges befizetési díjak összege közötti különbséggel. Opcionális, alapértelmezett érték, ha hiányzik, 1. A nulla és a negatív értékek érvénytelenek és szintén 1-nek értelmezhetők.

pay_url

Melyik URL fogadja el a fizetéseket. Ez az az URL, ahol a pénztárca POSTolja az érméket.

fulfillment_url

Melyik URL-címre menjen a pénztárca a teljesítés megszerzéséhez, például egy megvásárolt cikk HTML- vagy PDF-formátumához, vagy egy rendeléskövető rendszerhez a szállításokhoz, vagy egy egyszerű, ember által olvasható weboldalhoz, amely a szerződés állapotát jelzi.

order_id

A kereskedő által szabadon meghatározható alfanumerikus azonosító. A kereskedő által a tranzakció egyedi azonosítására használt azonosító.

összefoglaló

A szerződés rövid, ember által olvasható összefoglalója. Akkor használandó, ha a szerződést csak egy sorban jeleníti meg, például az ügyfél tranzakciótörténetében.

időbélyegző

Az ajánlat létrehozásának időpontja.

pay_deadline

Annak az időpontnak az időbélyege, ameddig a kereskedő azt szeretné, hogy a tőzsde véglegesen átutalja az ebből a szerződésből származó pénzt. Ha ez a határidő lejár, a tőzsde összesíti az összes olyan betétet, ahol a szerződések a „refund_deadline”-on túl vannak, és egyetlen nagy átutalást hajt végre. Az összegeket az átutalási egységre kerekítjük; ha a teljes összeg még mindig az átutalási egység alatt van, akkor nem kerül kifizetésre.

refund_deadline

Időbélyeg, ameddig a kereskedő hajlandó (és képes) visszatérítést adni a szerződésért a Taler segítségével. Ne feledje, hogy a Taler cseréje legalább addig a határidőig letétben tartja a fizetést. Addig az időpontig a kereskedő képes lesz aláírni egy üzenetet, hogy kiváltsa a visszatérítést az ügyfélnek. Ezt követően már nem lesz lehetőség a vásárlónak visszatérítésre. Kisebbnek kell lennie, mint a pay_deadline.

termékek

A vásárlónak eladott termékek sorozata. Minden egyes bejegyzés egy tuple-t tartalmaz a következő értékekkel:

leírás

A termék leírása.

mennyiség

A szállítandó tételek mennyisége. Megadhat egy egységet (pl. 1 kg) vagy csak a darabszámot.

ár

A termék adott quantity egységének ára, amelyet az adott delivery_location re szállítanak. Vegye figyelembe, hogy általában az összes ár összegének ki kell adnia a szerződés teljes összegét, de ez eltérhet a kedvezmények miatt vagy azért, mert az egyes árak nem állnak rendelkezésre.

product_id

A termék egyedi azonosítója a kereskedő katalógusában. Általában szabadon választható, mivel csak a kereskedő számára van jelentősége, de a [0,2^{51}) tartományba eső számnak kell lennie.

adók

A kereskedő által fizetendő adók térképe. A címke az adó neve, azaz HÉA, forgalmi adó vagy jövedelemadó, az érték pedig az alkalmazandó adó összege. Megjegyzendő, hogy tetszőleges címkék megengedettek, amennyiben az alkalmazandó adórendszer azonosítására szolgálnak. A részleteket a szabályozó hatóság határozhatja meg. Ez arra szolgál, hogy a vásárlónak nyilatkozzon arról, hogy a kereskedő mely adókat kívánja megfizetni, és a vásárló nyugtaként használhatja. Az információt valószínűleg a kereskedőnél végzett adóellenőrzések során is felhasználják.

delivery_date

Az az időpont, amikorra a terméket a delivery_location helyre kell szállítani.

delivery_location

Ennek meg kell adnia egy címkét a locations térképen, amely meghatározza, hogy hova kell szállítani az elemet.

Az értékek elhagyhatók, ha nem alkalmazhatóak. Például, ha egy vásárlás olyan termékcsomagról szól, amelynek nincsenek egyedi árai vagy termékazonosítói, a product_id vagy az ár nem adható meg a szerződésben. Hasonlóképpen, a közvetlenül a teljesítési URI-n keresztül szállított virtuális termékek esetében nincs szállítási_hely.

kereskedő
cím:

Ennek egy címkét kell adnia a locations térképen, amely megadja, hogy hol található a kereskedő.

név

Ennek egy ember által olvasható nevet kell adnia a kereskedő vállalkozásának.

joghatóság

Ennek meg kell adnia egy címkét a helyszínek térképen, amely meghatározza azt a joghatóságot, amely szerint ezt a szerződést választottbírósági eljárás alá kell vonni.

helyszínek

A szerződésben használt helyszínek asszociatív térképe. A térképen szereplő helyek címkéi szabadon választhatók és használhatók, amikor a szerződés más részeiben egy helyre van szükség. Így ha ugyanarra a helyszínre többször is szükség van (például az ügyfél vagy a kereskedő üzleti címére), akkor azt csak egyszer kell feltüntetni (és továbbítani), és egyébként a címkén keresztül lehet rá hivatkozni. A hely attribútumok nem teljes körű listája a következő:

név

A címzett neve a kézbesítéshez, akár cégnév, akár személynév.

ország

A kézbesítendő ország neve, ahogyan az a postai csomagon szerepel, pl. „Franciaország”.

állam

A kézbesítendő állam neve, ahogyan az a postai csomagon szerepel, pl. „NY”.

régió

A kézbesítendő régió neve, ahogyan az a postai csomagon található.

tartományok

A kézbesítendő tartomány neve, ahogyan az a postai csomagon található.

város

A kézbesítendő város neve, ahogyan az egy postai csomagon található.

irányítószám

Postai irányítószám a kézbesítéshez, ahogyan az egy postai csomagon található.

utca

A kézbesítéshez használt utcanév, ahogyan az egy postai csomagon található.

street_number

A házszám (házszám) a kézbesítéshez, ahogyan az a postai csomagon található.

Megjegyzés

A helyszíneknek nem kötelező az összes ilyen mezőt megadniuk, és további mezők is lehetnek. A szerződéses renderelőknek legalább a fent felsorolt mezőket kell megjeleníteniük, és azokat a mezőket, amelyeket nem kulcs-érték listaként értelmeznek, meg kell jeleníteniük.