Creating orders

3.1.3. Creating orders#

This page contains all the documentation for the video tutorial explaining a simple order creation through the API and checking for its status.

3.1.3.1. Video#

3.1.3.2. Requirements#

Required for this tutorial series:

  • A Taler merchant backend
    If you need help using the merchant backend for the first time, you can watch the Taler merchant introduction tutorial.
  • A Taler wallet instance
    Setup instructions are available on https://wallet.taler.net.
  • A REST API management software or relevant programming skills
    In this video series, we are going to use the Insomnia free software, available for download at https://insomnia.rest.

3.1.3.3. Demo backend notice#

You can use your own merchant backend service or the online demonstration service at https://backend.demo.taler.net/instances/sandbox/ for this tutorial.

3.1.3.4. More notes on Merchant payment processing#

  1. Creating an Order for a Payment

Payments in Taler revolve around an order, which is a machine-readable description of the business transaction for which the payment is to be made. Before accepting a Taler payment as a merchant you must create such an order.

This is done by POSTing a JSON object to the backend’s /private/orders API endpoint. At least the following fields must be given inside the order field:

  • amount: The amount to be paid, as a string in the format CURRENCY:DECIMAL_VALUE, for example EUR:10 for 10 Euros or KUDOS:1.5 for 1.5 KUDOS.

  • summary: A human-readable summary for what the payment is about. The summary should be short enough to fit into titles, though no hard limit is enforced.

  • fulfillment_url: A URL that will be displayed once the payment is completed. For digital goods, this should be a page that displays the product that was purchased. On successful payment, the wallet automatically appends the order_id as a query parameter, as well as the session_sig for session-bound payments (discussed below).

Orders can have many more fields, see The Taler Order Format. When POSTing an order, you can also specify additional details such as an override for the refund duration and instructions for inventory management. These are rarely needed and not covered in this tutorial; please see the reference manual for details.

A minimal Python snippet for creating an order would look like this:

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

The backend will fill in some details missing in the order, such as the address of the merchant instance. The full details are called the contract terms.

Note

The above request disables the use of claim tokens by setting the create_token option to false. If you need claim tokens, you must adjust the code to construct the taler://pay/ URI given below to include the claim token.

After successfully POSTing 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 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 also possible to obtain it by checking for the payment status as described in the next section.

When manually constructing this URL, make sure to supply the claim token (unless it was disabled) and if the backend is running without TLS to use taler+http:// (note that the latter is only supported by wallets running in debug mode).

Note

A trivial way to obtain the correct payment_redirect_url is to check the status of the payment (see below). So if you are still unsure how to construct it, you can simply ask the backend to do for you. However, in production you should probably construct it manually and avoid the extra request to the backend.

  1. 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 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.

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

If the order_status field in the response is paid, you will not get a payment_redirect_url and instead information about the payment status, including:

  • contract_terms: The full contract terms of the order.

  • refunded: true if a (possibly partial) refund was granted for this purchase.

  • refunded_amount: Amount that was refunded

Once the frontend has confirmed that the payment was successful, it usually needs to trigger the business logic for the merchant to fulfill the merchant’s obligations under the contract.

Note

You do not need to keep querying to notice changes to the order’s transaction status. The endpoints support long polling, simply specify a timeout_ms query parameter with how long you want to wait at most for the order status to change to paid.

3.1.3.5. More tutorials#

To view additional tutorials, you can browse this site or head to https://docs.taler.net to get the latest documentation about the Taler services.