Refunding orders

3.1.4. Refunding orders#

This page contains all the documentation for the video tutorial explaining the process of refunding orders and the different deadlines involved in refunds.

3.1.4.1. Video#

3.1.4.2. Information#

If you are not familiar with the process of creating orders, you can watch the Taler merchant creating orders tutorial.

3.1.4.3. 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.4.4. 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.4.5. More notes on Merchant order refunds#

A refund in GNU Taler is a way to “undo” a payment. It needs to be authorized by the merchant. Refunds can be for any fraction of the original amount paid, but they cannot exceed the original payment. Refunds are time-limited and can only happen while the exchange holds funds for a particular payment in escrow. The time during which a refund is possible can be controlled by setting the refund_deadline in an order. The default value for this refund deadline is specified in the configuration of the merchant’s backend.

The frontend can instruct the merchant backend to authorize a refund by POSTing to the /private/orders/$ORDER_ID/refund endpoint.

The refund request JSON object has only two fields:

  • refund: Amount to be refunded. If a previous refund was authorized for the same order, the new amount must be higher, otherwise the operation has no effect. The value indicates the total amount to be refunded, not an increase in the refund.

  • reason: Human-readable justification for the refund. The reason is only used by the Back Office and is not exposed to the customer.

If the request is successful (indicated by HTTP status code 200), the response includes a taler_refund_uri. The frontend must redirect the customer’s browser to that URL to allow the refund to be processed by the wallet.

This code snipped illustrates giving a refund:

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

Note

After granting a refund, the public 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 h_contract field must be appended (?h_contract=$H_CONTRACT) as the public endpoint requires it to authenticate the client. The required $H_CONTRACT value is returned in the refund response under the h_contract field.

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