diff options
Diffstat (limited to 'taler-merchant-api-tutorial.rst')
| -rw-r--r-- | taler-merchant-api-tutorial.rst | 134 |
1 files changed, 34 insertions, 100 deletions
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 0be0f4e3..15e21e21 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2020 Taler Systems SA + Copyright (C) 2014-2023 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -19,8 +19,12 @@ .. _merchant-api-tutorial: -GNU Taler Merchant API Tutorial -############################### +Merchant API Tutorial +##################### + +.. contents:: Table of Contents + :depth: 2 + :local: Introduction ============ @@ -63,10 +67,6 @@ If you want to look at some simple, running examples, check out these: that accepts donations for software projects and gives donation receipts. -- The - `survey <https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/survey>`__ - that gives users who answer a question a small reward. - - The `WooCommerce plugin <https://git.taler.net/gnu-taler-payment-for-woocommerce.git/>`__ which is a comprehensive integration into a Web shop including the refund business process. @@ -98,7 +98,7 @@ components: The following image illustrates the various interactions of these key components: -.. image:: arch-api.png +.. image:: images/arch-api.png The backend provides the cryptographic protocol support, stores Taler-specific financial information and communicates with the GNU Taler @@ -125,13 +125,13 @@ configuration. See :doc:`taler-merchant-manual`. The public sandbox backend https://backend.demo.taler.net/ uses an API key in the ``Authorization`` header. The value of this header must be -``ApiKey sandbox`` for the public sandbox backend. +``Bearer secret-token:sandbox`` for the public sandbox backend. .. code-block:: python >>> import requests - >>> requests.get("https://backend.demo.taler.net", - ... headers={"Authorization": "ApiKey sandbox"}) + >>> requests.get("https://backend.demo.taler.net/private/orders", + ... headers={"Authorization": "Bearer secret-token:sandbox"}) <Response [200]> If an HTTP status code other than 200 is returned, something went wrong. @@ -147,9 +147,9 @@ https://bank.demo.taler.net/. Merchant Instances ------------------ -The same Taler merchant backend server can be used by multiple separate +A single Taler merchant backend server can be used by multiple merchants that are separate business entities. Each of these separate -business entities is called a *merchant instance*, and is identified by +business entities is assigned a *merchant instance* which is identified by an alphanumeric *instance id*. If the instance is omitted, the instance id ``default`` is assumed. @@ -223,10 +223,10 @@ A minimal Python snippet for creating an order would look like this: >>> 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/private/order", + ... create_token=False) + >>> response = requests.post("https://backend.demo.taler.net/private/orders", ... json=body, - ... headers={"Authorization": "ApiKey sandbox"}) + ... headers={"Authorization": "Bearer secret-token:sandbox"}) <Response [200]> @@ -244,19 +244,23 @@ address of the merchant instance. The full details are called the you must adjust the code to construct the ``taler://pay/`` URI given below to include the claim token. -After successfully ``POST``\ ing to ``/private/orders``, an ``order_id`` will be -returned. Together with the merchant ``instance``, the order id uniquely -identifies the order within a merchant backend. Using the order ID, you -can trivially construct the respective ``taler://pay/`` URI that must -be provided to the wallet. Let ``example.com`` be the domain name where -the public endpoints of the instance are reachable. The Taler pay URI is -then simply ``taler://pay/example.com/$ORDER_ID/`` where ``$ORDER_ID`` -must be replaced with the ID of the order that was returned. +After successfully ``POST``\ ing to ``/private/orders``, a JSON with just an +``order_id`` field with a string representing the order ID will be returned. +If you also get a claim token, please double-check that you used the request +as described above. + +Together with the merchant ``instance``, the order id uniquely identifies the +order within a merchant backend. Using the order ID, you can trivially +construct the respective ``taler://pay/`` URI that must be provided to the +wallet. Let ``example.com`` be the domain name where the public endpoints of +the instance are reachable. The Taler pay URI is then simply +``taler://pay/example.com/$ORDER_ID/`` where ``$ORDER_ID`` must be replaced +with the ID of the order that was returned. You can put the ``taler://`` URI as the target of a link to open the Taler wallet via the ``taler://`` schema, or put it into a QR code. However, for a Web shop, the easiest way is to simply redirect the browser to -``https://example.com/orders/$ORDER_ID/``. That page will then trigger the +``https://example.com/orders/$ORDER_ID``. That page will then trigger the Taler wallet. Here the backend generates the right logic to trigger the wallet, supporting the various types of Taler wallets in existence. Instead of constructing the above URL by hand, it is best to obtain it by checking for @@ -267,11 +271,11 @@ Checking Payment Status and Prompting for Payment ------------------------------------------------- Given the order ID, the status of a payment can be checked with the -``/private/orders/$ORDER_ID/`` endpoint. If the payment is yet to be completed +``/private/orders/$ORDER_ID`` endpoint. If the payment is yet to be completed by the customer, ``/private/orders/$ORDER_ID`` will give the frontend a URL (under the name ``payment_redirect_url``) that will trigger the customer’s wallet to execute the payment. This is basically the -``https://example.com/orders/$ORDER_ID/`` URL we discussed above. +``https://example.com/orders/$ORDER_ID`` URL we discussed above. Note that the best way to obtain the ``payment_redirect_url`` is to check the status of the payment, even if you know that the user did not pay yet. There @@ -282,7 +286,7 @@ backend to do it is the safest method. >>> import requests >>> r = requests.get("https://backend.demo.taler.net/private/orders/" + order_id, - ... headers={"Authorization": "ApiKey sandbox"}) + ... headers={"Authorization": "Bearer secret-token:sandbox"}) >>> print(r.json()) If the ``order_status`` field in the response is ``paid``, you will not @@ -350,12 +354,12 @@ This code snipped illustrates giving a refund: ... reason="Customer did not like the product") >>> requests.post("https://backend.demo.taler.net/private/orders/" ... + order_id + "/refund", json=refund_req, - ... headers={"Authorization": "ApiKey sandbox"}) + ... headers={"Authorization": "Bearer secret-token:sandbox"}) <Response [200]> .. Note:: After granting a refund, the public - ``https://example.com/orders/$ORDER_ID/`` endpoint will + ``https://example.com/orders/$ORDER_ID`` endpoint will change its wallet interaction from requesting payment to offering a refund. Thus, frontends may again redirect browsers to this endpoint. However, to do so, a @@ -372,8 +376,6 @@ This code snipped illustrates giving a refund: Repurchase detection and fulfillment URLs ========================================= -.. TODO:: This section needs to be reviewed for 0.8. - A possible problem for merchants selling access to digital articles is that a customer may have paid for an article on one device, but may then want to read it on a different device, possibly one that @@ -411,79 +413,11 @@ considered to identify a resource you can pay for and thus do not have to be unique. -.. _Giving-Customers-Tips: -.. index:: tips - -Giving Customers Tips -===================== - -.. TODO:: This section needs to be updated for 0.8. - - -GNU Taler allows Web sites to grant small amounts directly to the -visitor. The idea is that some sites may want incentivize actions such -as filling out a survey or trying a new feature. It is important to note -that tips are not enforceable for the visitor, as there is no contract. -It is simply a voluntary gesture of appreciation of the site to its -visitor. However, once a tip has been granted, the visitor obtains full -control over the funds provided by the site. - -The “merchant” backend of the site must be properly configured for -tipping, and sufficient funds must be made available for tipping See -Taler Merchant Operating Manual. - -To check if tipping is configured properly and if there are sufficient -funds available for tipping, query the ``/tip-query`` endpoint: - -.. code-block:: python - - >>> import requests - >>> requests.get("https://backend.demo.taler.net/tip-query?instance=default", - ... headers={"Authorization": "ApiKey sandbox"}) - <Response [200]> - -.. _authorize-tip: - -To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields -are recognized in the JSON request object: - -- ``amount``: Amount that should be given to the visitor as a tip. - -- ``instance``: Merchant instance that grants the tip (each instance may - have its own independent tipping funds configured). - -- ``justification``: Description of why the tip was granted. Human-readable - text not exposed to the customer, but used by the Back Office. - -- ``next_url``: The URL that the user’s browser should be redirected to by - the wallet, once the tip has been processed. - -The response from the backend contains a ``tip_redirect_url``. The -customer’s browser must be redirected to this URL for the wallet to pick -up the tip. - -.. _pick-up-tip: - -This code snipped illustrates giving a tip: - -.. code-block:: python - - >>> import requests - >>> tip_req = dict(amount="KUDOS:0.5", - ... instance="default", - ... justification="User filled out survey", - ... next_url="https://merchant.com/thanks.html") - >>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req, - ... headers={"Authorization": "ApiKey sandbox"}) - <Response [200]> - .. _Advanced-topics: Advanced topics =============== -.. TODO:: This section needs to be updated for 0.8. - .. _Session_002dBound-Payments: Session-Bound Payments |