Orders maken

3.1.3. Orders maken#

Deze pagina bevat alle documentatie voor de videotutorial met uitleg over het eenvoudig aanmaken van een bestelling via de API en het controleren van de status ervan.

3.1.3.1. Video#

3.1.3.2. Vereisten#

Vereist voor deze tutorialserie:

  • Een Taler merchant backend
    Als je hulp nodig hebt bij het eerste gebruik van het merchant backend, kun je de Taler merchant introductie tutorial bekijken.
  • Een Taler portemonnee instantie
    Installatie-instructies zijn beschikbaar op https://wallet.taler.net.
  • Software voor REST API-beheer of relevante programmeervaardigheden
    In deze videoserie gebruiken we de gratis software Insomnia, te downloaden op https://insomnia.rest.

3.1.3.3. Demonstratie backend kennisgeving#

Je kunt voor deze tutorial gebruikmaken van je eigen merchant backend service of de online demonstratieservice op https://backend.demo.taler.net/instances/sandbox/.

3.1.3.4. Merchant Betalingsverwerking#

  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.

  1. 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.3.5. Meer tutorials#

Om aanvullende tutorials te bekijken, kun je op deze site kijken of naar https://docs.taler.net gaan voor de nieuwste documentatie over de Taler services.