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 backendAls je hulp nodig hebt bij het eerste gebruik van het merchant backend, kun je de Taler merchant introductie tutorial bekijken.
- Een Taler portemonnee instantieInstallatie-instructies zijn beschikbaar op https://wallet.taler.net.
- Software voor REST API-beheer of relevante programmeervaardighedenIn 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#
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 formaatCURRENCY:DECIMAL_VALUE
, bijvoorbeeldEUR:10
voor 10 euro ofKUDOS: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 deorder_id
toe als een query parameter, evenals desession_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.
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.