commit c3777818d839ad9f92c6fbea670aa63d32548d10
parent 58a829a8d2370996609cc55fac1958abe15fa54e
Author: Bohdan Potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date: Tue, 23 Sep 2025 11:14:44 +0200
adding missing donau stuff + fixing the hierarchy in core/api-merchant.rst
Diffstat:
| M | core/api-merchant.rst | | | 202 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------- |
1 file changed, 165 insertions(+), 37 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -92,7 +92,7 @@ Examples:
https://merchant-backend.example.com/management/instances/$ID
Endpoints to manage own instance:
-https://merchant-backend.example.com/private
+ https://merchant-backend.example.com/private
https://merchant-backend.example.com/private/auth
https://merchant-backend.example.com/instances/$ID/private
https://merchant-backend.example.com/instances/$ID/forgot-password
@@ -407,7 +407,7 @@ and to process refunds (checking refund status, obtaining the refund).
Claiming an order
------------------
+^^^^^^^^^^^^^^^^^
The first step of processing any Taler payment consists of the
(authorized) wallet claiming the order for itself. In this process,
@@ -469,7 +469,7 @@ claim orders (say in a case where stocks are limited).
}
Making the payment
-------------------
+^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/pay
@@ -781,7 +781,7 @@ Making the payment
Querying payment status
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/orders/$ORDER_ID
@@ -882,7 +882,7 @@ Querying payment status
Demonstrating payment
----------------------
+^^^^^^^^^^^^^^^^^^^^^
In case a wallet has already paid for an order, this is a fast way of proving
to the merchant that the order was already paid. The alternative would be to
@@ -963,7 +963,7 @@ again.
Aborting incomplete payments
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In rare cases (such as a wallet restoring from an outdated backup) it is possible
that a wallet fails to complete a payment because it runs out of e-cash in the
@@ -1126,7 +1126,7 @@ are for incomplete payments for an order and never for established contracts.
Obtaining refunds
------------------
+^^^^^^^^^^^^^^^^^
Refunds allow merchants to fully or partially restitute e-cash to a wallet,
for example because the merchant determined that it could not actually fulfill
@@ -1272,7 +1272,7 @@ instance setup before it can be used to manage inventory or process payments.
Setting up instances
---------------------
+^^^^^^^^^^^^^^^^^^^^
.. http:post:: /instances
@@ -1709,7 +1709,7 @@ Setting up instances
Inspecting instances
---------------------
+^^^^^^^^^^^^^^^^^^^^
.. _instances:
.. http:get:: /management/instances
@@ -1850,7 +1850,7 @@ Inspecting instances
Getting statistics
-------------------
+^^^^^^^^^^^^^^^^^^
.. http:get:: /management/instances/$INSTANCE/statistics-amount/$SLUG
.. http:get:: [/instances/$INSTANCE]/private/statistics-amount/$SLUG
@@ -2010,7 +2010,7 @@ Getting statistics
}
Deleting instances
-------------------
+^^^^^^^^^^^^^^^^^^
.. http:delete:: /management/instances/$INSTANCE
.. http:delete:: [/instances/$INSTANCE]/private
@@ -2053,7 +2053,7 @@ Deleting instances
KYC status checks
------------------
+^^^^^^^^^^^^^^^^^
.. _merchantkycstatus:
@@ -2448,7 +2448,7 @@ management.
Managing product categories
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/categories
@@ -2607,7 +2607,7 @@ Managing product categories
Adding products to the inventory
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCE]/private/products
@@ -2775,7 +2775,7 @@ Adding products to the inventory
}
Inspecting inventory
---------------------
+^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/products
@@ -2992,7 +2992,7 @@ Inspecting inventory
Reserving inventory
--------------------
+^^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock
@@ -3052,7 +3052,7 @@ Reserving inventory
Removing products from inventory
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:delete:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
@@ -3082,7 +3082,7 @@ order. Once the order is paid, the merchant may (for a limited time)
grant refunds on the order.
Creating orders
----------------
+^^^^^^^^^^^^^^^
.. _post-order:
@@ -3474,7 +3474,7 @@ Creating orders
Inspecting orders
------------------
+^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/orders
@@ -3756,7 +3756,7 @@ Inspecting orders
.. _private-order-data-cleanup:
Private order data cleanup
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
Some orders may contain sensitive information that the merchant may not want
to retain after fulfillment, such as the customer's shipping address. By
@@ -3914,7 +3914,7 @@ exchange failed to perform a wire transfer that was due.
Informing the backend about incoming wire transfers
----------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCE]/private/transfers
@@ -3958,7 +3958,7 @@ Informing the backend about incoming wire transfers
Querying known wire transfers
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/transfers
@@ -4041,7 +4041,7 @@ Querying known wire transfers
Querying expected wire transfers
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/incoming
@@ -4133,7 +4133,7 @@ Querying expected wire transfers
Deleting confirmed wire transfer
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Deleting a wire transfer can be useful in case of a data entry
mistake. In particular, if the exchange base URL was entered
@@ -4435,7 +4435,7 @@ Internet connectivity, the OTP mechanism can also be used to confirm payments.
Adding templates
-----------------
+^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCE]/private/templates
@@ -4514,7 +4514,7 @@ Adding templates
Editing templates
------------------
+^^^^^^^^^^^^^^^^^
.. http:patch:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID
@@ -4564,7 +4564,7 @@ Editing templates
Inspecting template
--------------------
+^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/private/templates
@@ -4657,7 +4657,7 @@ Inspecting template
Removing template
------------------
+^^^^^^^^^^^^^^^^^
.. http:delete:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID
@@ -4675,7 +4675,7 @@ Removing template
Using template
---------------
+^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCE]/templates/$TEMPLATE_ID
@@ -4760,7 +4760,7 @@ customer paid the merchant. It will show the date and the price the customer pai
Adding webhooks
----------------
+^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCES]/private/webhooks
@@ -4808,7 +4808,7 @@ Adding webhooks
Editing webhooks
-----------------
+^^^^^^^^^^^^^^^^
.. http:patch:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
@@ -4855,7 +4855,7 @@ Editing webhooks
Inspecting webhook
-------------------
+^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCES]/private/webhooks
@@ -4936,7 +4936,7 @@ Inspecting webhook
Removing webhook
------------------
+^^^^^^^^^^^^^^^^
.. http:delete:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
@@ -4966,7 +4966,7 @@ backend on the appropriate processing and handling.
Creating token families
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies
@@ -5047,7 +5047,7 @@ Creating token families
Updating token families
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
@@ -5097,7 +5097,7 @@ Updating token families
Inspecting token families
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies
@@ -5225,7 +5225,7 @@ Inspecting token families
Deleting token families
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG
@@ -5243,6 +5243,134 @@ Deleting token families
The merchant backend is unaware of the token family or instance.
+-----------------------
+Donau Charity Instances
+-----------------------
+
+A merchant instance can link one or more **Donau charity instances**.
+Each link associates the instance’s own public key with a charity registered
+at some Donau service. These links are managed under the private API.
+
+Permissions
+^^^^^^^^^^^
+
+* ``donau-read`` — list linked charities.
+* ``donau-write`` — add or remove charity links.
+
+Listing charity instances
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. http:get:: [/instances/$INSTANCE]/private/donau
+
+ Return all Donau charity instances currently linked to ``$INSTANCE``.
+
+ **Required permission:** ``donau-read``
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ Body is a :ts:type:`DonauInstancesResponse`.
+ :http:statuscode:`401 Unauthorized`:
+ Missing or invalid credentials.
+ :http:statuscode:`404 Not found`:
+ The merchant instance is unknown.
+
+ **Details:**
+
+ .. ts:def:: DonauInstancesResponse
+
+ interface DonauInstancesResponse {
+ // List of linked charity instances
+ donau_instances: DonauInstance[];
+ }
+
+ .. ts:def:: DonauInstance
+
+ interface DonauInstance {
+ // Serial number identifying the record inside the backend
+ donau_instance_serial: Integer;
+
+ // Base URL of the Donau service
+ donau_url: string;
+
+ // Human-readable charity name
+ charity_name: string;
+
+ // EdDSA public key of the charity (binary)
+ charity_pub_key: Bytes;
+
+ // Charity identifier inside the Donau service
+ charity_id: Integer;
+
+ // Maximum donation amount per calendar year
+ charity_max_per_year: Amount;
+
+ // Cumulative receipts in the current year
+ charity_receipts_to_date: Amount;
+
+ // Calendar year the receipts refer to
+ current_year: Integer;
+
+ // Exchange-style ``/keys`` response published by Donau
+ donau_keys_json: object;
+ }
+
+Adding a charity instance
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. http:post:: [/instances/$INSTANCE]/private/donau
+
+ Link a new Donau charity instance to ``$INSTANCE``.
+ The backend fetches and validates the charity’s metadata from the given
+ Donau service before persisting the link.
+
+ **Required permission:** ``donau-write``
+
+ **Request:**
+
+ The body **must** be a :ts:type:`PostDonauRequest`.
+
+ .. ts:def:: PostDonauRequest
+
+ interface PostDonauRequest {
+ // Base URL of the Donau service hosting the charity
+ donau_url: string;
+
+ // Numeric charity identifier inside the Donau service
+ charity_id: Integer;
+ }
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The charity link was created successfully.
+ :http:statuscode:`202 Accepted`:
+ Operation requires MFA; a :ts:type:`ChallengeResponse` is returned. @since **v21**
+ :http:statuscode:`400 Bad request`:
+ Malformed JSON or missing fields.
+ :http:statuscode:`409 Conflict`:
+ * The charity is already linked with different parameters, or
+ * The charity’s public key does **not** match the merchant instance’s public key.
+ :http:statuscode:`502 Bad gateway`:
+ Communication with the Donau service failed.
+
+Deleting a charity instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. http:delete:: [/instances/$INSTANCE]/private/donau/$DONAU_SERIAL
+
+ Unlink the Donau charity instance identified by ``$DONAU_SERIAL``.
+
+ **Required permission:** ``donau-write``
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ Charity link removed.
+ :http:statuscode:`404 Not found`:
+ No such charity link exists.
+
+
------------------
The Contract Terms
